Re-fit a model object using the complete model data

Fits the fitted model (such as lm) expressed in a “model” object using the complete model data. In a way, fit() is the inverse operation of model().

add_fit() adds the model fit to a “model” object, as its component fit (if not already present). The methods for classes “multimodel” and “cv” similarly add the fitted models to all included models.

has_fit() is a generic function that discerns whether a (multi-)model contains the corresponding fitted model(s).

Usage

fit(x, ...)

# S3 method for model
fit(
  x,
  eval = TRUE,
  use_original_args = FALSE,
  force = FALSE,
  env = parent.frame(),
  ...
)

# S3 method for multimodel
fit(
  x,
  eval = TRUE,
  use_original_args = FALSE,
  force = FALSE,
  which,
  env = parent.frame(),
  ...
)

# S3 method for cv
fit(
  x,
  eval = TRUE,
  use_original_args = FALSE,
  force = FALSE,
  which,
  env = parent.frame(),
  ...
)

add_fit(x, ...)

has_fit(x)

# S3 method for model_fm_glmnet
fit(x, iter, eval = TRUE, force = FALSE, ...)

# S3 method for model_fm_xgb
fit(x, iter, eval = TRUE, force = FALSE, ...)

Arguments

x: A “model” object
...: Passed to the model fitting function.
eval: Logical: If FALSE, the call to the model fitting function is returned, but not executed.
use_original_args: Logical: If FALSE, the model generating call is evaluated internally, using the data (and potential additional objects) saved in x; if TRUE, evaluation takes place in the calling environment of fit(), using the original input data.
force: Logical: If FALSE and a fitted model is present as the fit component of the model x, then this fit is returned. If force=TRUE, the model will be re-fitted in any case.
env: An environment. Used for internal purposes.
which: Selection of one model: An integer value or a logical vector of length n_model(x) having exactly one TRUE, or a character value (selection by name, a model's label). If n_model(x)==1, the only model is selected by default.
iter: iteration

Value

fit() returns a fitted model. add_fit() returns an object of class “model”. has_fit() returns a logical vector of length n_model(x).

Details

fit() is generic and has specific methods for classes “model_fm_glmnet” and “model_fm_xgb”. See fm_glmnet, fm_xgb and the examples below.

For iteratively fitted models (ifms, currently classes “fm_xgb” and “fm_glmnet”), fit() executes set_pref_iter() internally. If there is information on the preferred iteration (from a cross-validation) attached to x, the call to the model generating function is thereby adjusted. To suppress this adjustment, run fit() with iter=NULL.

Another peculiarity of fit(x) when x is an IFM and has information on preferred iterations comes into play when, in addition, x has a model fit attached to it (i.e. has_fit(x)==TRUE). In this case, the fitted model is partially adapted according to the preferred iteration. Specifically, the pref_iter is set in the fitted model and in the call (and more parameters related to stopping or choice of iteration for predictions are modified). The model fit attached to the output is improper in the sense that it differs from what would result when you execute its call (but predictions are the same). This default behavior can be suppressed by setting force=TRUE, which consequently increases execution time by the time required to fit the model.

Methods

fit.model() converts the “model” object x to a fitted model of class x$class.
fit.multimodel() and fit.cv() extract a single model from x according to argument which (see extract_model()) and applies fit.model() to the result.
fit.model_fm_glmnet() and fit.model_fm_xgb() are specific methods for these two model classes. A special feature of these methods goes into action if x contains results on preferred iteration resulting from a cross-validation. In that case the preferred iteration is selected from the cross-validation results (see set_pref_iter()).

Examples

# Applying model() then fit() to a model returns the original model:
mod <- model(lm(Sepal.Width ~ ., iris), label = "lm")
mod
#> --- A “model” object ---
#>   label:          lm
#>   model class:    lm
#>   formula:        Sepal.Width ~ Sepal.Length + Petal.Length + Petal.Width + 
#>                       Species
#>   data:           data.frame [150 x 5], 
#>                   input as: ‘data = iris’
#>   response_type:  continuous
#>   call:           lm(formula = Sepal.Width ~ ., data = data)
#>   fit:            Object of class ‘lm’
fit(mod)
#> 
#> Call:
#> lm(formula = Sepal.Width ~ ., data = iris)
#> 
#> Coefficients:
#>       (Intercept)       Sepal.Length       Petal.Length        Petal.Width  
#>            1.6572             0.3778            -0.1876             0.6257  
#> Speciesversicolor   Speciesvirginica  
#>           -1.1603            -1.3983  
#> 

# Obtain the model call without executing it:
fit(mod, eval = FALSE)
#> lm(formula = Sepal.Width ~ ., data = data)
# Note the generic 'data=data' in the result
# In order to obtain the original call, do:
fit(mod, eval = FALSE, use_original_args = TRUE)
#> lm(formula = Sepal.Width ~ ., data = iris)