Re-evaluates the stored frm() call with the given arguments
replaced. Any frm() argument can be updated by name.
Usage
# S3 method for class 'frmtmb_fit'
update(object, formula., ..., evaluate = TRUE)Details
The formula argument is formula., as in stats::update() and in
brms; formula = reaches it by partial matching. A formula
carrying a . is a delta applied to the stored mu formula with
stats::update.formula semantics - one-sided ~ . + z, dotted
. ~ . + z, or a changed response z ~ . + x - and keeps the dpar
formulas, the fixed dpar values and the family. A formula or bf()
with no . replaces the stored location formula and, as in brms,
keeps the stored parameter formulas, constants and equations, pooled
with its own. On a nonlinear model that keeps the nonlinear
parameters' formulas, so update(fit, bf(y ~ a + b, nl = TRUE))
gives the new body the old a and b, and a plain formula stays
nonlinear. brms's newdata is accepted as a synonym for data.
A bf() whose location formula is such a delta is read as brms
reads it: update(fit, bf(~ ., family = acat())) keeps the formula
and changes the family, and bf(. ~ . + z, sigma ~ z) updates the
location formula and adds the parameter formula. The parameter
formulas, constants and equations of the stored model and of the
delta are pooled, and one of the delta replaces one of the same
name, with a message. The family of the delta wins over the family
argument. On a nonlinear model the delta can only be ~ ., which
keeps the body.
The prior of the original fit is carried over. As in brms, a
specification in it that matches no parameter of the updated model,
such as a class "cor" prior after the update removes the last
correlation, is dropped. brms drops it silently; frmtmb says which
it dropped, in a message. A prior given to update() is merged
with the stored one, as brms merges them: each of its specifications
replaces the stored one for the same slot (class, coef, group,
resp, dpar and nlpar), and the stored specifications for every
other slot stay. This holds for every spelling frm() takes: a
set_prior() specification, a brmsprior from brms's prior(), and
a table from default_prior() or brms's get_prior(). As in brms,
every row of a table takes its slot, a row with an empty prior too:
that slot goes back to its default (flat), so a table from
default_prior() with one row edited resets every other slot it
lists. To keep the stored rows, give only the rows you change.
prior = NULL, or a prior with no rows, keeps the stored prior, as
in brms.
The specifications given to update() are checked as frm() checks
a prior, so one that matches no parameter is an error; brms drops it
with no message.
Without data (or newdata), the refit reads the data the fit
holds, as brms's update() does: the model frame and the variables
the formula reads through a transform, on the rows the fit used,
after na.action. A data-dependent basis (splines::ns(), poly(),
scale()) keeps the knots, coefficients or center that the fit
computed, so update(fit) with nothing changed gives the fit. The
result does not change when the data object is changed or removed,
or after saveRDS() and readRDS() in a new session.
Rows that na.action removed from the fit stay out of the refit.
This is also true when the update drops the variable that held the
missing value. Under na.action = na.exclude, the refit pads its
residuals and fitted values to the same rows as the fit.
A formula that reads a variable the fit does not hold, as
update(fit, ~ . + z) with a new z, reads the data of the stored
call again, as stats::update() does. That is done only when those
data still hold the fit's rows and values. Otherwise the update is
refused with brms's advice to give the data as newdata.
The formula, the family, the control, the start and the flags of the
stored call that update() does not replace come from the fit, as in
brms. So a fit made inside a function updates where the function's
arguments are gone, and an object of the same name in the workspace
does not become the model. The new fit's call names them as the
stored call did. evaluate = FALSE returns the call that update()
evaluates. It holds those values and the data, so it gives the same
refit wherever it is evaluated, as in stats::step() and
stats::add1().
The data are in the call by value, so printing the call prints
them. The call names the model it was made for: if it is edited
before it is evaluated, for example with a new formula, the fit
records its own call and does not take the old fit's bases or
missing rows.
Examples
set.seed(3)
dd <- data.frame(x = rnorm(60), z = rnorm(60))
dd$y <- rnorm(60, 1 + 0.5 * dd$x, 1)
fit <- frm(bf(y ~ x), family = gaussian(), data = dd)
# a delta on the stored formula, in either spelling
fit2 <- update(fit, ~ . + z)
formula(fit2)
#> y ~ x + z
#> <environment: 0x563b4fc4c138>
formula(update(fit, . ~ . + z))
#> y ~ x + z
#> <environment: 0x563b4fc4c138>
fit3 <- update(fit, formula. = ~ . - x, newdata = dd[1:40, ])
nobs(fit3)
#> [1] 40