Getting Started with earthUI

The hardware and bandwidth for this mirror is donated by METANET, the Webhosting and Full Service-Cloud Provider.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]metanet.ch.

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.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.