get_mvgam_priors: Extract information on default prior distributions for an...

In mvgam: Multivariate (Dynamic) Generalized Additive Models

Extract information on default prior distributions for an mvgam model

Description

This function lists the parameters that can have their prior distributions changed for a given model, as well listing their default distributions

Usage

get_mvgam_priors(
  formula,
  trend_formula,
  factor_formula,
  knots,
  trend_knots,
  trend_model = "None",
  family = poisson(),
  data,
  unit = time,
  species = series,
  use_lv = FALSE,
  n_lv,
  trend_map,
  ...
)

Arguments

formula	A formula object specifying the GAM observation model formula. These are exactly like the formula for a GLM except that smooth terms, s(), te(), ti(), t2(), as well as time-varying dynamic() terms, nonparametric gp() terms and offsets using offset(), can be added to the right hand side to specify that the linear predictor depends on smooth functions of predictors (or linear functionals of these). In nmix() family models, the formula is used to set up a linear predictor for the detection probability. Details of the formula syntax used by mvgam can be found in mvgam_formulae
trend_formula	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
factor_formula	Can be supplied instead trend_formula to match syntax from jsdgam
knots	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.
trend_knots	As for knots above, this is an optional list of knot values for smooth functions within the trend_formula.
trend_model	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	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.
data	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
unit	The unquoted name of the variable that represents the unit of analysis in data over which latent residuals should be correlated. This variable should be either a numeric or integer variable in the supplied data. Defaults to time to be consistent with other functionalities in mvgam, though note that the data need not be time series in this case. See examples below for further details and explanations
species	The unquoted name of the factor variable that indexes the different response units in data (usually 'species' in a JSDM). Defaults to series to be consistent with other mvgam models
use_lv	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.
n_lv	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)).
trend_map	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())
...	Not currently used

Details

Users can supply a model formula, prior to fitting the model, so that default priors can be inspected and altered. To make alterations, change the contents of the prior column and supplying this data.frame to the mvgam or jsdgam functions using the argument priors. If using Stan as the backend, users can also modify the parameter bounds by modifying the new_lowerbound and/or new_upperbound columns. This will be necessary if using restrictive distributions on some parameters, such as a Beta distribution for the trend sd parameters for example (Beta only has support on (0,1)), so the upperbound cannot be above 1. Another option is to make use of the prior modification functions in brms (i.e. prior) to change prior distributions and bounds (just use the name of the parameter that you'd like to change as the class argument; see examples below)

Value

either a data.frame containing the prior definitions (if any suitable priors can be altered by the user) or NULL, indicating that no priors in the model can be modified

Note

Only the prior, new_lowerbound and/or new_upperbound columns of the output should be altered when defining the user-defined priors for the model. Use only if you are familiar with the underlying probabilistic programming language. There are no sanity checks done to ensure that the code is legal (i.e. to check that lower bounds are smaller than upper bounds, for example)

Author(s)

Nicholas J Clark

See Also

mvgam, mvgam_formulae, prior

Examples

## Not run: 
# ========================================================================
# Example 1: Simulate data and inspect default priors
# ========================================================================

dat <- sim_mvgam(trend_rel = 0.5)

# Get a model file that uses default mvgam priors for inspection (not
# always necessary, but this can be useful for testing whether your
# updated priors are written correctly)
mod_default <- mvgam(
  y ~ s(series, bs = "re") + s(season, bs = "cc") - 1,
  family = nb(),
  data = dat$data_train,
  trend_model = AR(p = 2),
  run_model = FALSE
)

# Inspect the model file with default mvgam priors
stancode(mod_default)

# Look at which priors can be updated in mvgam
test_priors <- get_mvgam_priors(
  y ~ s(series, bs = "re") + s(season, bs = "cc") - 1,
  family = nb(),
  data = dat$data_train,
  trend_model = AR(p = 2)
)
test_priors

# ========================================================================
# Example 2: Modify priors manually
# ========================================================================

# Make a few changes; first, change the population mean for the
# series-level random intercepts
test_priors$prior[2] <- "mu_raw ~ normal(0.2, 0.5);"

# Now use stronger regularisation for the series-level AR2 coefficients
test_priors$prior[5] <- "ar2 ~ normal(0, 0.25);"

# Check that the changes are made to the model file without any warnings
# by setting 'run_model = FALSE'
mod <- mvgam(
  y ~ s(series, bs = "re") + s(season, bs = "cc") - 1,
  family = nb(),
  data = dat$data_train,
  trend_model = AR(p = 2),
  priors = test_priors,
  run_model = FALSE
)
stancode(mod)

# No warnings, the model is ready for fitting now in the usual way with
# the addition of the 'priors' argument

# ========================================================================
# Example 3: Use brms syntax for prior modification
# ========================================================================

# The same can be done using 'brms' functions; here we will also change
# the ar1 prior and put some bounds on the ar coefficients to enforce
# stationarity; we set the prior using the 'class' argument in all brms
# prior functions
brmsprior <- c(
  prior(normal(0.2, 0.5), class = mu_raw),
  prior(normal(0, 0.25), class = ar1, lb = -1, ub = 1),
  prior(normal(0, 0.25), class = ar2, lb = -1, ub = 1)
)
brmsprior

mod <- mvgam(
  y ~ s(series, bs = "re") + s(season, bs = "cc") - 1,
  family = nb(),
  data = dat$data_train,
  trend_model = AR(p = 2),
  priors = brmsprior,
  run_model = FALSE
)
stancode(mod)

# ========================================================================
# Example 4: Error handling example
# ========================================================================

# Look at what is returned when an incorrect spelling is used
test_priors$prior[5] <- "ar2_bananas ~ normal(0, 0.25);"
mod <- mvgam(
  y ~ s(series, bs = "re") + s(season, bs = "cc") - 1,
  family = nb(),
  data = dat$data_train,
  trend_model = AR(p = 2),
  priors = test_priors,
  run_model = FALSE
)
stancode(mod)

# ========================================================================
# Example 5: Parametric (fixed effect) priors
# ========================================================================

simdat <- sim_mvgam()

# Add a fake covariate
simdat$data_train$cov <- rnorm(NROW(simdat$data_train))

priors <- get_mvgam_priors(
  y ~ cov + s(season),
  data = simdat$data_train,
  family = poisson(),
  trend_model = AR()
)

# Change priors for the intercept and fake covariate effects
priors$prior[1] <- "(Intercept) ~ normal(0, 1);"
priors$prior[2] <- "cov ~ normal(0, 0.1);"

mod2 <- mvgam(
  y ~ cov + s(season),
  data = simdat$data_train,
  trend_model = AR(),
  family = poisson(),
  priors = priors,
  run_model = FALSE
)
stancode(mod2)

# ========================================================================
# Example 6: Alternative brms syntax for fixed effects
# ========================================================================

# Likewise using 'brms' utilities (note that you can use Intercept rather
# than `(Intercept)`) to change priors on the intercept
brmsprior <- c(
  prior(normal(0.2, 0.5), class = cov),
  prior(normal(0, 0.25), class = Intercept)
)
brmsprior

mod2 <- mvgam(
  y ~ cov + s(season),
  data = simdat$data_train,
  trend_model = AR(),
  family = poisson(),
  priors = brmsprior,
  run_model = FALSE
)
stancode(mod2)

# ========================================================================
# Example 7: Bulk prior assignment
# ========================================================================

# The "class = 'b'" shortcut can be used to put the same prior on all
# 'fixed' effect coefficients (apart from any intercepts)
set.seed(0)
dat <- mgcv::gamSim(1, n = 200, scale = 2)
dat$time <- 1:NROW(dat)
mod <- mvgam(
  y ~ x0 + x1 + s(x2) + s(x3),
  priors = prior(normal(0, 0.75), class = "b"),
  data = dat,
  family = gaussian(),
  run_model = FALSE
)
stancode(mod)

## End(Not run)

mvgam documentation built on Jan. 21, 2026, 9:07 a.m.