fit_model: Fit a machine learning model

In classbound: Visualization for Classification Decision Boundaries

Fit a machine learning model

Description

Fits a classification model and wraps it in a classbound object, which carries the feature metadata needed by boundary_compute() and plot_boundary().

Usage

fit_model(data, formula, classifier, ...)

## Default S3 method:
fit_model(
  data,
  formula,
  classifier,
  interface = c("formula", "matrix", "custom"),
  fit_args = list(),
  ...
)

## S3 method for class ''function''
fit_model(
  data,
  formula,
  classifier,
  interface = c("formula", "matrix", "custom"),
  fit_args = list(),
  ...
)

## S3 method for class 'character'
fit_model(
  data,
  formula,
  classifier,
  interface = c("formula", "matrix", "custom"),
  fit_args = list(),
  ...
)

Arguments

data	A data frame containing the training features and response variable. All columns referenced in formula must be present.
formula	A formula specifying the response and predictors, e.g., species ~ bill_length_mm + bill_depth_mm or species ~ . to use all columns.
classifier	The classification function or model specification to use. Pass a function (e.g., rpart::rpart), a string name (e.g., "rpart::rpart"), or a parsnip model spec / fitted workflow.
...	Additional arguments passed to methods.
interface	A string specifying how to invoke the classifier: "formula" (default), "matrix", or "custom". See Details.
fit_args	A named list of additional arguments forwarded to the classifier during fitting (e.g., list(cp = 0.01) for rpart).

Details

Interface modes

fit_model() supports three calling conventions via the interface argument:

• "formula" (default): passes formula and data directly to the classifier. Works for the vast majority of R classifiers (e.g., rpart::rpart, e1071::svm, stats::lda).

• "matrix": constructs a predictor matrix x and response vector y from the formula, then calls classifier(x, y, ...). Required for classifiers whose primary interface is matrix-based (e.g., randomForest::randomForest).

• "custom": passes only fit_args to the classifier, giving you full control over the call. Use this for non-standard APIs.

Tidymodels support

If classifier is a parsnip model specification (model_spec), a fitted model_fit, or a tidymodels workflow, fit_model() dispatches to the appropriate method automatically. The interface argument is not needed for these objects.

Preprocessing

fit_model() calls preprocess_data() internally to coerce response labels to a factor, handle missing values, and extract feature metadata. Do not call preprocess_data() manually before calling fit_model(); this will corrupt the stored metadata.

Value

A classbound object (a list of class "classbound") containing:

• ⁠$fit⁠: the raw fitted model object returned by the classifier

• ⁠$metadata⁠: a list with ⁠$features⁠ (names, types, ranges, imputation values) and ⁠$class_levels⁠ (sorted character vector of class labels)

• ⁠$boundary_data⁠: NULL until boundary_compute() is called

See Also

boundary_compute(), predict_model(), classbound()

Examples

library(palmerpenguins)
data(penguins)
peng_data <- na.omit(penguins[, c("species", "bill_length_mm", "bill_depth_mm")])

# Formula interface (most classifiers)
m_rpart <- fit_model(peng_data, species ~ ., rpart::rpart)

# Matrix interface (randomForest)
m_rf <- fit_model(peng_data, species ~ ., randomForest::randomForest,
  interface = "matrix"
)

# Additional fitting arguments via fit_args
m_rpart_cp <- fit_model(peng_data, species ~ ., rpart::rpart,
  fit_args = list(control = rpart::rpart.control(cp = 0.001))
)

classbound documentation built on Sept. 30, 2026, 5:13 p.m.