This function allows a previously fitted mvgam model to be updated.
# S3 method for mvgam
update(
object,
formula,
trend_formula,
knots,
trend_knots,
trend_model,
family,
share_obs_params,
data,
newdata,
trend_map,
use_lv,
n_lv,
priors,
chains,
burnin,
samples,
threads,
algorithm,
lfo = FALSE,
...
)# S3 method for jsdgam
update(
object,
formula,
factor_formula,
knots,
factor_knots,
data,
newdata,
n_lv,
family,
share_obs_params,
priors,
chains,
burnin,
samples,
threads,
algorithm,
lfo = FALSE,
...
)
A list object of class mvgam containing model output,
the text representation of the model file, the mgcv model output (for
easily generating simulations at unsampled covariate values), Dunn-Smyth
residuals for each outcome variable and key information needed for other
functions in the package. See mvgam-class for details. Use
methods(class = "mvgam") for an overview on available methods.
A list object of class mvgam containing model output,
the text representation of the model file, the mgcv model output (for
easily generating simulations at unsampled covariate values), Dunn-Smyth
residuals for each series and key information needed for other functions in
the package. See mvgam-class for details. Use
methods(class = "mvgam") for an overview on available methods.
list object returned from mvgam. See mvgam()
Optional new formula object. Note, mvgam currently does
not support dynamic formula updates such as removal of specific terms with
- term. When updating, the entire formula needs to be supplied.
An optional formula object specifying the GAM process
model formula. If supplied, a linear predictor will be modelled for the
latent trends to capture process model evolution separately from the
observation model.
Important notes:
Should not have a response variable specified on the left-hand side
(e.g., ~ season + s(year))
Use trend instead of series for effects that vary across time series
Only available for RW(), AR() and VAR() trend models
In nmix() family models, sets up linear predictor for latent abundance
Consider dropping one intercept using - 1 convention to avoid
estimation challenges
An optional list containing user specified knot values for
basis construction. For most bases the user simply supplies the knots to be
used, which must match up with the k value supplied. Different terms can
use different numbers of knots, unless they share a covariate.
As for knots above, this is an optional list of knot
values for smooth functions within the trend_formula.
character or function specifying the time series dynamics
for the latent trend.
Available options:
None: No latent trend component (GAM component only, like gam)
ZMVN or ZMVN(): Zero-Mean Multivariate Normal (Stan only)
'RW' or RW(): Random Walk
'AR1', 'AR2', 'AR3' or AR(p = 1, 2, 3): Autoregressive models
'CAR1' or CAR(p = 1): Continuous-time AR (Ornstein–Uhlenbeck process)
'VAR1' or VAR(): Vector Autoregressive (Stan only)
'PWlogistic', 'PWlinear' or PW(): Piecewise trends (Stan only)
'GP' or GP(): Gaussian Process with squared exponential kernel (Stan only)
Additional features:
Moving average and/or correlated process error terms available for most types
(e.g., RW(cor = TRUE) for multivariate Random Walk)
Hierarchical correlations possible for structured data
See mvgam_trends for details and ZMVN() for examples
family specifying the exponential observation family for the series.
Supported families:
gaussian(): Real-valued data
betar(): Proportional data on (0,1)
lognormal(): Non-negative real-valued data
student_t(): Real-valued data
Gamma(): Non-negative real-valued data
bernoulli(): Binary data
poisson(): Count data (default)
nb(): Overdispersed count data
binomial(): Count data with imperfect detection when number of trials is known
(use cbind() to bind observations and trials)
beta_binomial(): As binomial() but allows for overdispersion
nmix(): Count data with imperfect detection when number of trials is unknown
(State-Space N-Mixture model with Poisson latent states and Binomial observations)
See mvgam_families for more details.
logical. If TRUE and the family has additional
family-specific observation parameters (e.g., variance components, dispersion
parameters), these will be shared across all outcome variables. Useful when
multiple outcomes share properties. Default is FALSE.
A dataframe or list containing the model response variable
and covariates required by the GAM formula and optional trend_formula.
Required columns for most models:
series: A factor index of the series IDs (number of levels should equal
number of unique series labels)
time: numeric or integer index of time points. For most dynamic trend
types, time should be measured in discrete, regularly spaced intervals
(i.e., c(1, 2, 3, ...)). Irregular spacing is allowed for trend_model = CAR(1),
but zero intervals are adjusted to 1e-12 to prevent sampling errors.
Special cases:
Models with hierarchical temporal correlation (e.g., AR(gr = region, subgr = species))
should NOT include a series identifier
Models without temporal dynamics (trend_model = 'None' or trend_model = ZMVN())
don't require a time variable
Optional dataframe or list of test data containing the same
variables as in data. If included, observations in variable y will be
set to NA when fitting the model so that posterior simulations can be obtained.
Optional data.frame specifying which series should depend on
which latent trends. Enables multiple series to depend on the same latent
trend process with different observation processes.
Required structure:
Column series: Single unique entry for each series (matching factor levels in data)
Column trend: Integer values indicating which trend each series depends on
Notes:
Sets up latent factor model by enabling use_lv = TRUE
Process model intercept is NOT automatically suppressed
Not yet supported for continuous time models (CAR())
logical. If TRUE, use dynamic factors to estimate series'
latent trends in a reduced dimension format. Only available for RW(),
AR() and GP() trend models. Default is FALSE.
See lv_correlations for examples.
integer specifying the number of latent dynamic factors to use
if use_lv == TRUE. Cannot exceed n_series. Default is
min(2, floor(n_series / 2)).
An optional data.frame with prior definitions or, preferably,
a vector of brmsprior objects (see prior()).
See get_mvgam_priors() and Details for more information.
integer specifying the number of parallel chains for the model.
Ignored for variational inference algorithms.
integer specifying the number of warmup iterations to tune
sampling algorithms. Ignored for variational inference algorithms.
integer specifying the number of post-warmup iterations for
sampling the posterior distribution.
integer. Experimental option for within-chain parallelisation
in Stan using reduce_sum. Recommended only for experienced Stan users with
slow models. Currently works for all families except nmix() and when using
Cmdstan backend.
Character string naming the estimation approach:
"sampling": MCMC (default)
"meanfield": Variational inference with factorized normal distributions
"fullrank": Variational inference with multivariate normal distribution
"laplace": Laplace approximation (cmdstanr only)
"pathfinder": Pathfinder algorithm (cmdstanr only)
Can be set globally via "brms.algorithm" option. Limited testing suggests
"meanfield" performs best among non-MCMC approximations for dynamic GAMs.
logical. Indicates whether this is part of lfo_cv.mvgam call.
Returns lighter model version for speed. Users should leave as FALSE.
Other arguments to be passed to mvgam or
jsdgam
Optional new formula object for the factor linear
predictors
An optional list containing user specified knot
values to be used for basis construction of any smooth terms in
factor_formula. For most bases the user simply supplies the knots to be
used, which must match up with the k value supplied (note that the
number of knots is not always just k). Different terms can use different
numbers of knots, unless they share a covariate
Nicholas J Clark
if (FALSE) {
# Simulate some data and fit a Poisson AR1 model
simdat <- sim_mvgam(n_series = 1, trend_model = AR())
mod <- mvgam(
y ~ s(season, bs = 'cc'),
trend_model = AR(),
noncentred = TRUE,
data = simdat$data_train,
chains = 2
)
summary(mod)
conditional_effects(mod, type = 'link')
# Update to an AR2 model
updated_mod <- update(
mod,
trend_model = AR(p = 2),
noncentred = TRUE
)
summary(updated_mod)
conditional_effects(updated_mod, type = 'link')
# Now update to a Binomial AR1 by adding information on trials
# requires that we supply newdata that contains the 'trials' variable
simdat$data_train$trials <- max(simdat$data_train$y) + 15
updated_mod <- update(
mod,
formula = cbind(y, trials) ~ s(season, bs = 'cc'),
noncentred = TRUE,
data = simdat$data_train,
family = binomial()
)
summary(updated_mod)
conditional_effects(updated_mod, type = 'link')
}
Run the code above in your browser using DataLab