fit: Fit a Model Specification to a Dataset

Description

fit will take a model specification, translate the required code by substituting arguments, and execute the model fit routine.

Usage

fit(object, ...)
# S3 method for model_spec
fit(object, formula = NULL, recipe = NULL, x = NULL,
  y = NULL, data = NULL, engine = object$engine,
  control = fit_control(), ...)

Arguments

object

An object of class model_spec

...

Not currently used; values passed here will be ignored. Other options required to fit the model should be passed using the others argument in the original model specification.

formula

An object of class "formula" (or one that can be coerced to that class): a symbolic description of the model to be fitted.

recipe

Optional, depending on the interface (see Details below). An object of class recipes::recipe(). Note: when needed, a named argument should be used.

Optional, depending on the interface (see Details below). Can be data frame or matrix of predictors. Note: when needed, a named argument should be used.

Optional, depending on the interface (see Details below). Can be a vector, data frame or matrix of predictors (the latter two in case of multivariate outcomes). Note: when needed, a named argument should be used.

data

Optional, depending on the interface (see Details below). A data frame containing all relevant variables (e.g. outcome(s), predictors, case weights, etc). Note: when needed, a named argument should be used.

engine

A character string for the software that should be used to fit the model. This is highly dependent on the type of model (e.g. linear regression, random forest, etc.).

control

A named list with elements verbosity and catch. See fit_control().

Value

An object for the fitted model.

Details

fit substitutes the current arguments in the model specification into the computational engine's code, checks them for validity, then fits the model using the data and the engine-specific code. Different model functions have different interfaces (e.g. formula or x/y) and fit translates between the interface used when fit was invoked and the one required by the underlying model.

When possible, fit attempts to avoid making copies of the data. For example, if the underlying model uses a formula and fit is invoked with a formula, the original data are references when the model is fit. However, if the underlying model uses something else, such as x/y, the formula is evaluated and the data are converted to the required format. In this case, any calls in the resulting model objects reference the temporary objects used to fit the model.

Examples

Run this code

# NOT RUN {
# Although `glm` only has a formula interface, different
# methods for specifying the model can be used

data("lending_club")

lm_mod <- logistic_reg()

using_formula <-
  fit(lm_mod,
      Class ~ funded_amnt + int_rate,
      data = lending_club,
      engine = "glm")

# NOTE: use named arguments for "x" and "y" when using this interface
using_xy <-
  fit(lm_mod,
      x = lending_club[, c("funded_amnt", "int_rate")],
      y = lending_club$Class,
      engine = "glm")

# NOTE: use named arguments for "recipe" and "data" when using this interface
library(recipes)
lend_rec <- recipe(Class ~ funded_amnt + int_rate,
                   data = lending_club)

using_recipe <-
  fit(lm_mod,
      recipe = lend_rec,
      data = lending_club,
      engine = "glm")

coef(using_formula)
coef(using_xy)
coef(using_recipe)

# Using other options:

# }