plot_mvgam_smooth: Plot smooth terms from 'mvgam' models

In mvgam: Multivariate (Dynamic) Generalized Additive Models

Plot smooth terms from mvgam models

Description

This function plots posterior empirical quantiles for a series-specific smooth term

Usage

plot_mvgam_smooth(
  object,
  trend_effects = FALSE,
  series = 1,
  smooth,
  residuals = FALSE,
  n_resid_bins = 25,
  realisations = FALSE,
  n_realisations = 15,
  derivatives = FALSE,
  newdata
)

Arguments

object	list object of class mvgam. See mvgam()
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
series	integer specifying which series in the set is to be plotted
smooth	Either a character or integer specifying which smooth term to be plotted
residuals	logical. If TRUE, 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
n_resid_bins	integer specifying the number of bins to group the covariate into when plotting partial residuals. Setting this argument too high can make for messy plots that are difficult to interpret, while setting it too low will likely mask some potentially useful patterns in the partial residuals. Default is 25
realisations	logical. If TRUE, posterior realisations are shown as a spaghetti plot, making it easier to visualise the diversity of possible functions. If FALSE, the default, empirical quantiles of the posterior distribution are shown
n_realisations	integer specifying the number of posterior realisations to plot, if realisations = TRUE. Ignored otherwise
derivatives	logical. If TRUE, an additional plot will be returned to show the estimated 1st derivative for the specified smooth (Note: this only works for univariate smooths)
newdata	Optional dataframe for predicting the smooth, containing at least 'series' in addition to any other variables included in the linear predictor of the original model's formula. Note that this currently is only supported for plotting univariate smooths

Details

Smooth functions are shown as empirical quantiles (or spaghetti plots) of posterior partial expectations across a sequence of values between the variable's min and max, while zeroing out effects of all other variables. At present, only univariate and bivariate smooth plots are allowed, though note that bivariate smooths rely on default behaviour from plot.gam. plot_mvgam_smooth generates posterior predictions from an object of class mvgam, calculates posterior empirical quantiles and plots them. If realisations = FALSE, the returned plot shows 90, 60, 40 and 20 percent posterior quantiles (as ribbons of increasingly darker shades of red) as well as the posterior median (as a dark red line). If realisations = TRUE, a set of n_realisations posterior draws are shown. For more nuanced visualisation, supply newdata just as you would when predicting from a gam model or use the more flexible conditional_effects.mvgam. Alternatively, if you prefer to use partial effect plots in the style of gratia, and if you have the gratia package installed, you can use draw.mvgam. See gratia_mvgam_enhancements for details.

Value

A base R graphics plot

Author(s)

Nicholas J Clark

See Also

plot.gam, conditional_effects.mvgam, gratia_mvgam_enhancements

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