# Getting Started with earthUI

## Prerequisites

earthUI works on macOS, Windows, and Linux with R >= 4.1.0. All features work out of the box except:

- PDF reports require a LaTeX installation. Install with `tinytex::install_tinytex()`. If LaTeX is not detected, the PDF option is automatically hidden and HTML/Word reports remain available.
- Roboto Condensed font is downloaded from Google Fonts for plot styling. If your machine is offline, the app uses the system sans-serif font automatically.

## Introduction

`earthUI` provides both an interactive Shiny GUI and a set of composable R functions for building Earth (MARS-style) models using the `earth` package.

This vignette demonstrates the programmatic API. To launch the interactive app, simply run:

    library(earthUI)
    launch()

## Basic Workflow

### 1. Import Data

    library(earthUI)

    # For this example, we use the built-in mtcars dataset
    df <- mtcars
    head(df)
    #>                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
    #> Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
    #> Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
    #> Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
    #> Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
    #> Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
    #> Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

You can also import from files:

    df <- import_data("my_data.csv")        # CSV
    df <- import_data("my_data.xlsx")       # Excel

### 2. Detect Categorical Variables

    cats <- detect_categoricals(df)
    cats
    #>   mpg   cyl  disp    hp  drat    wt  qsec    vs    am  gear  carb
    #> FALSE  TRUE FALSE FALSE FALSE FALSE FALSE  TRUE  TRUE  TRUE  TRUE

Variables with few unique values (default: 10 or fewer) are flagged as likely categorical. Character and factor columns are always flagged.

### 3. Fit the Model

    result <- fit_earth(
      df = df,
      target = "mpg",
      predictors = c("cyl", "disp", "hp", "wt", "qsec", "am", "gear"),
      categoricals = c("am", "gear"),
      degree = 1
    )

Important defaults:

- `degree = 1` — no interaction terms. This is intentional to avoid overfitting. Set `degree = 2` or higher only when you have domain knowledge supporting interactions.
- When `degree >= 2`, cross-validation (10-fold) is automatically enabled.

Recommended parameter values:

earthUI displays recommended values below key parameters in the sidebar. These update reactively based on the number of fitting rows (n) and selected predictors (p). Key recommendations:

Parameter | Formula | Example (n=200, p=10)
--- | --- | ---
nk | `min(100, max(21, 2*p+1, floor(n/10)))` | 21
minspan | `min(16, floor(5 + n/50))` | 9
endspan | `min(16, floor(5 + n/28))` | 12
penalty | `if (degree > 1) 3 else 2` | 2
pmethod | backward | backward
nprune | leave empty (let GCV decide) | NULL
nfold | `min(15, max(10, round(n/100)))` | 10
ncross | `max(3, ceiling(100/n))` | 3
varmod.method | lm | lm
newvar.penalty | 0.1 (if collinear predictors) | 0.1

The formulas are derived from Friedman’s MARS paper, earth’s C source code, and empirical testing. See the earthUI User Guide, Chapter 7 for detailed explanations and scaling tables.

### 4. Examine Results

    # Model summary
    s <- format_summary(result)
    cat(sprintf("R²: %.4f\nGRSq: %.4f\nTerms: %d\n",
                s$r_squared, s$grsq, s$n_terms))
    #> R²: 0.8591
    #> GRSq: 0.8143
    #> Terms: 3

    # Coefficients
    s$coefficients
    #>            term       mpg
    #> 1   (Intercept) 20.436170
    #> 2 h(disp-146.7) -0.024758
    #> 3 h(146.7-disp)  0.145722

    # Variable importance
    format_variable_importance(result)
    #>   variable nsubsets gcv rss
    #> 1     disp        2 100 100

    # ANOVA decomposition
    format_anova(result)
    #>   term     description variables       mpg
    #> 1    1     (Intercept)           20.436170
    #> 2    2 h(disp - 146.7)      disp -0.024758
    #> 3    3 h(146.7 - disp)      disp  0.145722

### 5. Plots

    plot_variable_importance(result)

    plot_partial_dependence(result, "wt")

    plot_actual_vs_predicted(result)

    plot_residuals(result)

## Controlling Interactions

When using `degree >= 2`, you can control which variable pairs are allowed to interact:

    # Build default all-allowed matrix
    preds <- c("wt", "hp", "cyl", "disp")
    mat <- build_allowed_matrix(preds)

    # Block wt-cyl interaction
    mat["wt", "cyl"] <- FALSE
    mat["cyl", "wt"] <- FALSE

    # Convert to earth-compatible function
    allowed_fn <- build_allowed_function(mat)

    # Fit with interactions
    result2 <- fit_earth(
      df = df,
      target = "mpg",
      predictors = preds,
      degree = 2,
      allowed_func = allowed_fn
    )

    s2 <- format_summary(result2)
    cat(sprintf("Training R²: %.4f\nCV R²: %s\n",
                s2$r_squared,
                if (!is.na(s2$cv_rsq)) sprintf("%.4f", s2$cv_rsq) else "N/A"))
    #> Training R²: 0.8938
    #> CV R²: 0.8380

## Exporting Reports

Generate publication-quality reports in HTML, PDF, or Word:

    render_report(result, output_format = "html", output_file = "my_report.html")

This requires the `quarto` R package and a Quarto installation.

For faster rendering when producing multiple formats, pre-generate the report assets (plots and data) once, then render each format without re-computation:

    assets <- prepare_report_assets(result)
    render_report(result, "html", "report.html", assets_dir = assets)
    render_report(result, "pdf",  "report.pdf",  assets_dir = assets)
    render_report(result, "docx", "report.docx", assets_dir = assets)

In the Shiny app, report rendering runs in the background — the UI stays responsive while the report is generated, and a modal dialog shows progress.