fit_earth: Fit an earth model

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

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

df	A data frame containing the modeling data.
target	Character string. Name of the response variable.
predictors	Character vector. Names of predictor variables.
categoricals	Character vector. Names of predictors to treat as categorical (converted to factors before fitting). Default is NULL.
linpreds	Character vector. Names of predictors constrained to enter the model linearly (no hinge functions). Default is NULL.
type_map	Named list or character vector. Maps column names to declared types (e.g., "numeric", "Date", "factor"). When provided, columns are coerced before fitting: Date/POSIXct columns are converted to numeric (days/seconds since epoch), and type-derived categoricals are merged into categoricals. Default is NULL (no coercion).
degree	Integer. Maximum degree of interaction. Default is 1 (no interactions). When >= 2, cross-validation is automatically enabled.
allowed_func	Function or NULL. An allowed function as returned by build_allowed_function(). Only used when degree >= 2.
allowed_matrix	Logical matrix or NULL. The allowed interaction matrix. Stored in the result for report export. Not used for fitting (use allowed_func instead).
nfold	Integer. Number of cross-validation folds. Automatically set to 10 when degree >= 2 unless explicitly provided. Set to 0 to disable.
nprune	Integer or NULL. Maximum number of terms in the pruned model.
thresh	Numeric. Forward stepping threshold. Default is earth's default (0.001).
penalty	Numeric. Generalized cross-validation penalty per knot. Default is earth's default (if degree > 1, 3; otherwise 2).
minspan	Integer or NULL. Minimum number of observations between knots.
endspan	Integer or NULL. Minimum number of observations before the first and after the last knot.
fast.k	Integer. Maximum number of parent terms considered at each step of the forward pass. Default is earth's default (20).
pmethod	Character. Pruning method. One of "backward", "none", "exhaustive", "forward", "seqrep", "cv". Default is "backward".
glm	List or NULL. If provided, passed to earth's glm argument to fit a GLM on the earth basis functions.
trace	Numeric. Trace earth's execution. 0 (default) = none, 0.3 = variance model, 0.5 = cross validation, 1-5 = increasing detail.
nk	Integer or NULL. Maximum number of model terms before pruning.
newvar.penalty	Numeric or NULL. Penalty for adding a new variable in the forward pass (Friedman's gamma). Default 0.
fast.beta	Numeric or NULL. Fast MARS ageing coefficient. Default 1.
ncross	Integer or NULL. Number of cross-validations. Default 1.
stratify	Logical or NULL. Stratify cross-validation samples. Default TRUE.
varmod.method	Character or NULL. Variance model method. One of "none", "const", "lm", "rlm", "earth", "gam", "power", "power0", "x.lm", "x.rlm", "x.earth", "x.gam".
varmod.exponent	Numeric or NULL. Power transform for variance model.
varmod.conv	Numeric or NULL. Convergence criterion for IRLS.
varmod.clamp	Numeric or NULL. Minimum estimated standard deviation.
varmod.minspan	Integer or NULL. minspan for internal variance model.
keepxy	Logical or NULL. Retain x, y in model object. Default FALSE.
Scale.y	Logical or NULL. Scale response internally. Default TRUE.
Adjust.endspan	Numeric or NULL. Interaction endspan multiplier. Default 2.
Auto.linpreds	Logical or NULL. Auto-detect linear predictors. Default TRUE.
Force.weights	Logical or NULL. Force weighted code path. Default FALSE.
Use.beta.cache	Logical or NULL. Cache coefficients in forward pass. Default TRUE.
Force.xtx.prune	Logical or NULL. Force X'X-based pruning. Default FALSE.
Get.leverages	Logical or NULL. Calculate hat values. Default TRUE.
Exhaustive.tol	Numeric or NULL. Condition number threshold for exhaustive pruning. Default 1e-10.
wp	Numeric vector or NULL. Response weights.
weights	Numeric vector or NULL. Case weights passed to earth.
...	Additional arguments passed to earth::earth().
.capture_trace	Logical. If TRUE (default), capture earth's trace output. Set to FALSE when running in a background process.

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

# Using the included demo appraisal dataset
demo_file <- system.file("extdata", "Appraisal_1.csv", package = "earthUI")
df <- import_data(demo_file)
result <- fit_earth(df, target = "sale_price",
                    predictors = c("living_sqft", "lot_size", "age"))
format_summary(result)

earthUI documentation built on March 26, 2026, 1:07 a.m.