plot.mvgam: Default plots for 'mvgam' models

In mvgam: Multivariate (Dynamic) Generalized Additive Models

Default plots for mvgam models

Description

This function takes a fitted mvgam object and produces plots of smooth functions, forecasts, trends and uncertainty components

Usage

## S3 method for class 'mvgam'
plot(
  x,
  type = "residuals",
  series = 1,
  residuals = FALSE,
  newdata,
  data_test,
  trend_effects = FALSE,
  ...
)

Arguments

x	list object returned from mvgam. See mvgam()
type	character specifying which type of plot to return. Options are: "series", "residuals", "smooths", "re" (random effect smooths), "pterms" (parametric effects), "forecast", "trend", "uncertainty", "factors"
series	integer specifying which series in the set is to be plotted. This is ignored if type == 're'
residuals	logical. If TRUE and type = 'smooths', posterior quantiles of partial residuals are added to plots of 1-D smooths as a series of ribbon rectangles. Partial residuals for a smooth term are the median Dunn-Smyth residuals that would be obtained by dropping the term concerned from the model, while leaving all other estimates fixed (i.e. the estimates for the term plus the original median Dunn-Smyth residuals). Note that because mvgam works with Dunn-Smyth residuals and not working residuals, which are used by mgcv, the magnitudes of partial residuals will be different to what you would expect from plot.gam. Interpretation is similar though, as these partial residuals should be evenly scattered around the smooth function if the function is well estimated
newdata	Optional dataframe or list of test data containing at least 'series' and 'time' in addition to any other variables included in the linear predictor of the original formula. This argument is optional when plotting out of sample forecast period observations (when type = forecast) and required when plotting uncertainty components (type = uncertainty).
data_test	Deprecated. Still works in place of newdata but users are recommended to use newdata instead for more seamless integration into R workflows
trend_effects	logical. If TRUE and a trend_formula was used in model fitting, terms from the trend (i.e. process) model will be plotted
...	Additional arguments for each individual plotting function.

Details

These plots are useful for getting an overview of the fitted model and its estimated random effects or smooth functions, but the individual plotting functions and the functions from the marginaleffects and gratia packages offer far more customisation.

Value

A base R plot or set of plots

Author(s)

Nicholas J Clark

See Also

plot_mvgam_resids, plot_mvgam_smooth, plot_mvgam_fc, plot_mvgam_trend, plot_mvgam_uncertainty, plot_mvgam_factors, plot_mvgam_randomeffects, conditional_effects.mvgam, plot_predictions, plot_slopes, gratia_mvgam_enhancements

Examples

## Not run: 
# Simulate some time series
dat <- sim_mvgam(
  T = 80,
  n_series = 3
)

# Fit a basic model
mod <- mvgam(
  y ~ s(season, bs = 'cc') + s(series, bs = 're'),
  data = dat$data_train,
  trend_model = RW(),
  chains = 2,
  silent = 2
)

# Plot predictions and residuals for each series
plot(mod, type = 'forecast', series = 1)
plot(mod, type = 'forecast', series = 2)
plot(mod, type = 'forecast', series = 3)
plot(mod, type = 'residuals', series = 1)
plot(mod, type = 'residuals', series = 2)
plot(mod, type = 'residuals', series = 3)

# Plot model effects
plot(mod, type = 'smooths')
plot(mod, type = 're')

# More flexible plots with 'marginaleffects' utilities
library(marginaleffects)

plot_predictions(
  mod,
  condition = 'season',
  type = 'link'
)

plot_predictions(
  mod,
  condition = c('season', 'series', 'series'),
  type = 'link'
)

plot_predictions(
  mod,
  condition = 'series',
  type = 'link'
)

# When using a State-Space model with predictors on the process
# model, set trend_effects = TRUE to visualise process effects
mod <- mvgam(
  y ~ -1,
  trend_formula = ~ s(season, bs = 'cc'),
  data = dat$data_train,
  trend_model = RW(),
  chains = 2,
  silent = 2
)

plot(mod, type = 'smooths', trend_effects = TRUE)

# But 'marginaleffects' functions work without any modification
plot_predictions(
  mod,
  condition = 'season',
  type = 'link'
)

## End(Not run)

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