Update an object of class “model” or “multimodel”

The method update.model() allows updating selected arguments in the original call to the model fitting function, in particular formula, data. Changing the model fitting function is not possible, however. update.multimodel() will apply update.model() to each of its models.

absent(), unchanged() and null() are auxiliary functions designed for usage in update.model() and multimodel(). absent() states the removal/absence of an argument in the model fitting call, unchanged() leaves an argument unchanged, and null() attributes an explicit NULL to a formal parameter. Find more about the usage of these functions in the the “Details” section and the examples.

Usage

# S3 method for model
update(
  object,
  ...,
  label = label.model(object),
  add_fit = FALSE,
  ignore_changes_in_arg = NULL
)

# S3 method for multimodel
update(object, ...)

absent()

null()

unchanged()

Arguments

object

A “model” or “multimodel”.

...

Arguments to be updated.

label

Character string: A label to be attributed to the model.

add_fit

Logical: Save the fitted object as a component of the result?

ignore_changes_in_arg

Parameter for internal use.

Value

udpate.model() returns the modified model. If “...” is empty, x is not changed. Otherwise, the output will not contain the model fit.

Details

update(model, parameter=NULL) is ambiguous -- it's clearer to use null() or absent().

Using a dot in a formula can be ambiguous, too. update(model, formula=new_formula) updates the model's original formula with new_formula (using update.formula). In order to replace the existing formula by a different one containing a dot, use update(model, formula=I(new_formula)). See the examples.

absent(), unchanged() and null() can also be used in multimodel(), which uses update.model() internally. As an example, multimodel(lm(y~x), weights = list(w, absent())) will return a multimodel containing the two model definitions based on calls lm(y~x, weights = w) and lm(y~x). Always enclose absent(), unchanged() and null() in a list() if several alternative model parameterizations are proposed in multimodel()! The example won't work properly with c(w, absent()) instead of list(w, absent())!

See also

model, multimodel; update.formula

Examples

if (require(lme4)){
  # Simluate data
  d <- simuldat()
  (mixmod <- lmer(Y ~ (X1|g) + X2 + X3, d, REML = TRUE))
  
  # update.model
  m_REML <- model(mixmod, label = "REML")
  # update parater "REML"
  m_ML <- update(m_REML, REML = FALSE, label = "ML")
  
  # absent(), unchanged(), null()
  update(m_REML, REML = absent())$call
  update(m_REML, REML = unchanged())$call
  update(m_REML, REML = null())$call # Note: not meaningful - fit() will fail
  
  # update.multimodel
  mm <- multimodel(m_REML, REML = c(TRUE, FALSE))
  w <- runif(nrow(d))
  update(mm, weights = w)
  
  # Dots in formula: 
  update(m_REML, formula = . ~ . - X2)
  
  # Updating vs replacing a formula:
  update(m_REML, formula = exp(Y) ~ .)    # updates the formula
  update(m_REML, formula = I(exp(Y) ~ .)) # replaces the formula
  
  # Usage of unchanged() in multimodel()
  multimodel(m_REML, REML = list(unchanged(), FALSE))
}
#> Error in initializePtr(): function 'cholmod_factor_ldetA' not provided by package 'Matrix'