Create a model object — model • modeltuner

model() takes a fitted statistical model x, e.g. a lm, and returns an output of class “model”, an R object containing the model's structure, the data and optionally the fitting weights. The “model” object does not necessarily contain the model fit, but has all information needed to refit the model, possibly after making changes to the generating call. model() works for fitted models created by a model fitting function having a formula and a data argument.

model() is applicable to many popular model classes such as lm, lmrob, rpart, lmer and many more.

Usage

model(x, ...)

# S3 method for default
model(
  x,
  label = "model",
  class = attr(x, "class"),
  add_fit = TRUE,
  response_type = NULL,
  predict_function = predict,
  env = parent.frame(),
  ...
)

# S3 method for call
model(x, label = "model", class, add_fit = FALSE, env = parent.frame(), ...)

# S3 method for character
model(x, ..., label = "model", class, add_fit = FALSE, env = parent.frame())

# S3 method for model
model(x, ...)

# S3 method for model
print(
  x,
  what = c("label", "class", "formula", "data", "response_type", "weights", "call",
    "fit"),
  abbreviate = TRUE,
  width = getOption("width"),
  indent = "",
  ...
)

Arguments

x: A fitted model meeting the formal requirements described in the “Details” section. Alternatively, an unevaluated call to a model fitting function; in that case, the model class must be provided as argument class (see examples).
...: Arguments passed to methods. Not used in the default method.
label: Character string: A label to be attributed to the model.
class: Class of the model object. Not required if x is a fitted model.
add_fit: Logical: Save the fitted object as a component of the result?
response_type: Character string, "continuous" or "binary". Default: "binary" if all response values (converted to numeric) are 0 or 1, else "continuous".
predict_function: Predict function, often predict - see “Details”.
env: An environment. Used for internal purposes.
what: What to print: Either a character vector being a subset of {"label", "formula", "data", "call", "response_type", "response", "fit", "predict_function", "saved_objects", "class", "weights"} or TRUE, meaning all of these elements.
abbreviate: Logical. If TRUE (the default), long formulas and calls are printed in abbreviated mode, such that they usually fit on 4 or fewer output lines; otherwise they are printed entirely, no matter how long they are.
width: Integer: Width of printed output.
indent: Used internally only.

Value

model() returns a list with class attribute c(paste0("model_", class), "model") having the following elements:

label, a character string used as identifier of the model;
formula, a formula defining the model's structure;
data, a data.frame;
call, the call fitting the model;
response_type, character string, "continuous" or "binary";
response, character string containing the variable name or expression defining the response;
fit (optional), the fitted object of class class;
predict_function, a real valued function with two arguments: A model and a data of the same structure as data;
saved_objects, a list of objects appearing in the call and not being part of the data;
class, the class of the fitted model;
weights, an optional vector of fitting weights.

Details

Model classes suited for model() must meet the following requirements:

The model fitting function must have formal arguments formula and data, accepting a formula and a data.frame, respectively.
In case of a binary response, the response must be numeric and have values 0 or 1.
getCall(x) with x a model of the class in question must return the call generating x.
There should usually be a predict method for the class of x returning a vector of length nrow(data). Alternatively, a real valued function with two arguments, a model and a data.frame, can be specified as the predict_function.
If weighted fitting is required, the model fitting function must have an argument weights. In that case, there should be an appropriate weights method for the class class returning either NULL or a vector of non-negative values of length nrow(data). However, a model class not supporting weighted fitting will work as long as you do not specify weights in model().

The model generating call is saved in the output object in a partially generic mode. Specifically, the arguments data and weights (if present) are given generic values data=data and weights=weights, respectively. This is convenient for cross-validation with cv(), where the model generating call is repeatedly adapted and executed internally, using data and weights stored in the “model” object. See also the argument use_original_args in fit(), which is related to this reformulation of the model generating call.

Note

If the current settings of the options na.action and contrasts (or other options) potentially change the behavior of the model fitting function, then changing these options during an analysis involving that type of model must be avoided.

Methods

model.call() and model.character() allow creating a “model” object without having to fit the corresponding model. See examples. Specifying the class is mandatory here, as it can not be queried from the input x.
There is a method model.model() that returns its input x unchanged.

Examples

# lm
fitted <- lm(Sepal.Width ~ ., iris)
mod1 <- model(fitted, label = "LinearModel")
mod1
#> --- A “model” object ---
#>   label:          LinearModel
#>   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’

# weighted lm
model(lm(Sepal.Width ~ ., iris, weights = runif(nrow(iris))), 
      label = "weightedLm")
#> --- A “model” object ---
#>   label:          weightedLm
#>   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
#>   weights:        numeric [150], 
#>                   input as: ‘weights = runif(nrow(iris))’
#>   call:           lm(formula = Sepal.Width ~ ., data = data, weights = weights)
#>   fit:            Object of class ‘lm’

# print.model
print(mod1, what = TRUE)
#> --- A “model” object ---
#>   label:             LinearModel
#>   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
#>   response:          Sepal.Width
#>   call:              lm(formula = Sepal.Width ~ ., data = data)
#>   predict_function:  function (object, ...)  
#>   fit:               Object of class ‘lm’
print(mod1, what = c("label", "call", "class"))
#> --- A “model” object ---
#>   label:        LinearModel
#>   model class:  lm
#>   call:         lm(formula = Sepal.Width ~ ., data = data)
print(mod1, what = NULL)
#> --- A “model” object ---

# model() applied to an unevaluated call:
lm_call <- quote(lm(Sepal.Width~., iris))
model(lm_call, class = "lm")
#> --- A “model” object ---
#>   label:          model
#>   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)
# Same using the method model.character():
model("lm", Sepal.Width~., iris, class = "lm")
#> --- A “model” object ---
#>   label:          model
#>   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)