earthUI: Interactive 'shiny' GUI for the 'earth' Package

Description

Provides a 'shiny'-based graphical user interface for the 'earth' package, enabling interactive building and exploration of Multivariate Adaptive Regression Splines (MARS) models. Features include data import from CSV and 'Excel' files, automatic detection of categorical variables, interactive control of interaction terms via an allowed matrix, comprehensive model diagnostics with variable importance and partial dependence plots, and publication-quality report generation via 'Quarto'.

Author(s)

Maintainer: William Craytor bcraytor@proton.me

See Also

Useful links:

• https://github.com/wcraytor/earthUI

• Report bugs at https://github.com/wcraytor/earthUI/issues

Build an allowed function for earth()

Description

Converts an allowed interaction matrix into a function compatible with the allowed parameter of earth::earth(). The function checks that ALL pairwise combinations among the predictors in a proposed interaction term are TRUE in the matrix.

Usage

build_allowed_function(allowed_matrix)

Arguments

Details

The returned function implements the standard earth() allowed function contract. When earth proposes a new hinge function involving predictor pred with existing parent predictors indicated by the parents logical vector, the function checks that every pair of involved predictors is allowed in the matrix.

For a 3-way interaction between X, Y, Z, the function verifies that (X,Y), (Y,Z), and (X,Z) are all TRUE in the matrix.

Value

A function with signature ⁠function(degree, pred, parents, namesx, first)⁠ suitable for the allowed parameter of earth::earth().

Examples

mat <- build_allowed_matrix(c("sqft", "bedrooms", "pool"))
mat["sqft", "pool"] <- FALSE
mat["pool", "sqft"] <- FALSE
func <- build_allowed_function(mat)

Build an allowed interaction matrix

Description

Creates a symmetric logical matrix indicating which pairs of predictors are allowed to interact. By default, all interactions are allowed.

Usage

build_allowed_matrix(variable_names, default = TRUE)

Arguments

Value

A symmetric logical matrix with variable_names as both row and column names.

Examples

mat <- build_allowed_matrix(c("sqft", "bedrooms", "pool"))
mat["sqft", "pool"] <- FALSE
mat["pool", "sqft"] <- FALSE
mat

Detect likely categorical variables in a data frame

Description

Returns a logical named vector indicating which columns are likely categorical. Character and factor columns are always flagged. Numeric columns with fewer than max_unique unique values are also flagged.

Usage

detect_categoricals(df, max_unique = 10L)

Arguments

Value

A named logical vector with one element per column. TRUE indicates the column is likely categorical.

Examples

df <- data.frame(
  price = c(100, 200, 300, 400),
  pool = c("Y", "N", "Y", "N"),
  bedrooms = c(2, 3, 2, 4),
  sqft = c(1200, 1500, 1300, 1800)
)
detect_categoricals(df)

Detect column types in a data frame

Description

Inspects each column and returns a best-guess R type string. Character columns are tested for common date patterns. Numeric columns containing only 0/1 values (with both present) are flagged as logical.

Usage

detect_types(df)

Arguments

Value

A named character vector with one element per column. Possible values: "numeric", "integer", "character", "logical", "factor", "Date", "POSIXct", "unknown".

Examples

df <- data.frame(
  price = c(100.5, 200.3, 300.1),
  rooms = c(2L, 3L, 4L),
  pool  = c("Y", "N", "Y"),
  sold  = c(TRUE, FALSE, TRUE)
)
detect_types(df)

Fit an earth model

Description

Wrapper around earth::earth() with parameter validation and automatic cross-validation when interaction terms are enabled.

Usage

fit_earth(
  df,
  target,
  predictors,
  categoricals = NULL,
  linpreds = NULL,
  type_map = NULL,
  degree = 1L,
  allowed_func = NULL,
  allowed_matrix = NULL,
  nfold = NULL,
  nprune = NULL,
  thresh = NULL,
  penalty = NULL,
  minspan = NULL,
  endspan = NULL,
  fast.k = NULL,
  pmethod = NULL,
  glm = NULL,
  trace = NULL,
  nk = NULL,
  newvar.penalty = NULL,
  fast.beta = NULL,
  ncross = NULL,
  stratify = NULL,
  varmod.method = NULL,
  varmod.exponent = NULL,
  varmod.conv = NULL,
  varmod.clamp = NULL,
  varmod.minspan = NULL,
  keepxy = NULL,
  Scale.y = NULL,
  Adjust.endspan = NULL,
  Auto.linpreds = NULL,
  Force.weights = NULL,
  Use.beta.cache = NULL,
  Force.xtx.prune = NULL,
  Get.leverages = NULL,
  Exhaustive.tol = NULL,
  wp = NULL,
  weights = NULL,
  ...,
  .capture_trace = TRUE
)

Arguments

Value

A list with class "earthUI_result" containing:

model

The fitted earth model object.

target

Name of the response variable.

predictors

Names of predictor variables used.

categoricals

Names of categorical predictors.

degree

Degree of interaction used.

cv_enabled

Logical; whether cross-validation was used.

data

The data frame used for fitting.

Examples

df <- mtcars
result <- fit_earth(df, target = "mpg",
                    predictors = c("cyl", "disp", "hp", "wt"))
format_summary(result)

Format ANOVA decomposition

Description

Extracts the ANOVA table from a fitted earth model.

Usage

format_anova(earth_result)

Arguments

Value

A data frame with the ANOVA decomposition showing which predictors contribute to each basis function and their importance.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
format_anova(result)

Format earth model as LaTeX equation

Description

Converts a fitted earth model into a LaTeX-formatted mathematical representation using g-function notation. Basis functions are grouped by degree (constant, first-degree, second-degree, third-degree) and labeled with indices that encode the group, position, and factor variable count.

Usage

format_model_equation(earth_result, digits = 7L, response_idx = NULL)

Arguments

Value

A list containing:

latex

Character string. LaTeX array environment for HTML/MathJax rendering.

latex_inline

Character string. Wrapped in display math delimiters for MathJax/HTML rendering.

latex_pdf

Character string. LaTeX for native PDF output with escaped special characters in text blocks.

latex_word

Character string. LaTeX for Word/docx output.

groups

List of group structures for programmatic access.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
eq <- format_model_equation(result)
cat(eq$latex)

Format earth model summary

Description

Extracts key statistics from a fitted earth model including coefficients, basis functions, R-squared, GCV, GRSq, and RSS.

Usage

format_summary(earth_result)

Arguments

Value

A list containing:

coefficients

Data frame of model coefficients and basis functions.

r_squared

Training R-squared.

gcv

Generalized cross-validation value.

grsq

Generalized R-squared (1 - GCV/variance).

rss

Residual sum of squares.

n_terms

Number of terms in the pruned model.

n_predictors

Number of predictors used in the final model.

n_obs

Number of observations.

cv_rsq

Cross-validated R-squared (if CV was used, else NA).

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
summary_info <- format_summary(result)
summary_info$r_squared

Format variable importance

Description

Extracts variable importance scores from a fitted earth model using earth::evimp().

Usage

format_variable_importance(earth_result)

Arguments

Value

A data frame with columns variable, nsubsets, gcv, and rss, sorted by overall importance (nsubsets).

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
format_variable_importance(result)

Import data from CSV or Excel files

Description

Reads a CSV (.csv) or 'Excel' (.xlsx, .xls) file and returns a data frame. Column names are converted to snake_case and duplicates are made unique.

Usage

import_data(filepath, sheet = 1, ...)

Arguments

Value

A data frame with column names converted to snake_case. Duplicate column names are made unique by appending numeric suffixes.

Examples

# Create a temporary CSV for demonstration
tmp <- tempfile(fileext = ".csv")
write.csv(mtcars, tmp, row.names = FALSE)
df <- import_data(tmp)
head(df)
unlink(tmp)

Launch the earthUI Shiny application

Description

Opens an interactive 'shiny' GUI for building and exploring 'earth' (MARS-style) models. The application provides data import, variable configuration, model fitting, result visualization, and report export.

Usage

launch(port = 7878L, ...)

Arguments

Value

This function does not return a value; it launches the Shiny app.

Examples

if (interactive()) {
  launch()
}

List g-function groups from a fitted earth model

Description

Returns a data frame describing each non-intercept g-function group from the model equation, including degree, factor count, graph dimensionality, and the number of terms. The g-function notation is {}^{f}g^{j}_{k} where f = number of factor variables (top-left), j = degree of interaction (top-right), k = position within the degree group (bottom-right).

Usage

list_g_functions(earth_result)

Arguments

Value

A data frame with columns:

index

Integer. Sequential index (1-based).

label

Character. Variable names in the group.

g_j

Integer. Degree of the g-function (top-right superscript).

g_k

Integer. Position within the degree (bottom-right subscript).

g_f

Integer. Number of factor variables (top-left superscript).

d

Integer. Graph dimensionality (degree minus factor count).

n_terms

Integer. Number of terms in the group.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
list_g_functions(result)

Plot actual vs predicted values

Description

Creates a scatter plot of actual vs predicted values with a 1:1 reference line.

Usage

plot_actual_vs_predicted(earth_result, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_actual_vs_predicted(result)

Plot variable contribution

Description

Creates a scatter plot showing each variable's actual contribution to the prediction. For each observation, the contribution is the sum of coefficient * basis function value across all terms involving that variable.

Usage

plot_contribution(earth_result, variable, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_contribution(result, "wt")

Plot correlation matrix

Description

Creates a heatmap of pairwise correlations among the target variable and numeric predictors, with cells colored by degree of correlation and values printed in each cell.

Usage

plot_correlation_matrix(earth_result)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_correlation_matrix(result)

Plot g-function as a static contour (for reports)

Description

Creates a ggplot2 visualization for any g-function group. For d <= 1, produces a 2D scatter plot (same as plot_g_function()). For d >= 2, produces a filled contour plot suitable for static formats like PDF and Word.

Usage

plot_g_contour(earth_result, group_index, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_g_contour(result, 1)

Plot g-function contribution

Description

Creates a contribution plot for a specific g-function group. For degree-1 groups (single variable), produces a 2D scatter + piecewise-linear plot with slope labels and knot markers. For degree-2 groups (two variables), produces a 3D surface plot using plotly if available, or a filled contour plot.

Usage

plot_g_function(earth_result, group_index, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object for d <= 1, or a plotly widget for d >= 2 (when plotly is installed). Falls back to ggplot2 contour if plotly is not available.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_g_function(result, 1)

Plot g-function as a static 3D perspective (for reports)

Description

Creates a base R persp() 3D surface plot for g-function groups with d >= 2. For d <= 1, produces a 2D scatter plot (same as plot_g_function()). The surface is colored by contribution value using a blue-white-red scale. Suitable for PDF and Word output where interactive plotly is not available.

Usage

plot_g_persp(
  earth_result,
  group_index,
  theta = 30,
  phi = 25,
  response_idx = NULL
)

Arguments

Value

Invisible NULL (base graphics). For d <= 1, returns a ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"), degree = 2L)
plot_g_persp(result, 1)

Plot partial dependence

Description

Creates a partial dependence plot for a selected variable from a fitted earth model.

Usage

plot_partial_dependence(
  earth_result,
  variable,
  n_grid = 50L,
  response_idx = NULL
)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_partial_dependence(result, "wt")

Plot Q-Q plot of residuals

Description

Creates a normal Q-Q plot of the model residuals.

Usage

plot_qq(earth_result, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_qq(result)

Plot residual diagnostics

Description

Creates a two-panel diagnostic plot: residuals vs fitted values and a Q-Q plot of residuals.

Usage

plot_residuals(earth_result, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object showing residuals vs fitted values. Use plot_qq() for the Q-Q plot separately.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_residuals(result)

Plot variable importance

Description

Creates a horizontal bar chart of variable importance from a fitted earth model.

Usage

plot_variable_importance(earth_result, type = "nsubsets")

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_variable_importance(result)

Render an earth model report

Description

Renders a parameterized 'Quarto' report from the fitted 'earth' model results. Requires the 'quarto' R package and a 'Quarto' installation.

Usage

render_report(earth_result, output_format = "html", output_file = NULL)

Arguments

Value

The path to the rendered output file (invisibly).

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
render_report(result, output_format = "html",
              output_file = tempfile(fileext = ".html"))

Validate earthUI_result object

Description

Validate earthUI_result object

Usage

validate_earthUI_result(x)

Arguments

Value

Invisible NULL. Raises error if invalid.

Validate declared column types against actual data

Description

Checks each selected predictor's actual data against the user-declared type. Returns a list of errors (blocking), warnings (non-blocking), and any Date/POSIXct columns that will be auto-converted to numeric.

Usage

validate_types(df, type_map, predictors)

Arguments

Value

A list with components:

ok

Logical. TRUE if no blocking errors found.

warnings

Character vector of non-blocking warnings.

errors

Character vector of blocking errors.

date_columns

Character vector of Date/POSIXct predictor columns that will be auto-converted to numeric.

Examples

df <- data.frame(price = c(100, 200, 300), city = c("A", "B", "C"))
types <- list(price = "numeric", city = "character")
validate_types(df, types, predictors = c("price", "city"))