plot_mvgam_forecasts: Plot posterior forecast predictions from 'mvgam' models

In mvgam: Multivariate (Dynamic) Generalized Additive Models

Plot posterior forecast predictions from mvgam models

Description

Plot posterior forecast predictions from mvgam models

Usage

plot_mvgam_fc(
  object,
  series = 1,
  newdata,
  data_test,
  realisations = FALSE,
  n_realisations = 15,
  hide_xlabels = FALSE,
  xlab,
  ylab,
  ylim,
  n_cores = 1,
  return_forecasts = FALSE,
  return_score = FALSE,
  ...
)

## S3 method for class 'mvgam_forecast'
plot(
  x,
  series = 1,
  realisations = FALSE,
  n_realisations = 15,
  xlab,
  ylab,
  ylim,
  ...
)

Arguments

object	list object of class mvgam. See mvgam()
series	integer specifying which series in the set is to be plotted
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. If included, the covariate information in newdata will be used to generate forecasts from the fitted model equations. If this same newdata was originally included in the call to mvgam, then forecasts have already been produced by the generative model and these will simply be extracted and plotted. However if no newdata was supplied to the original model call, an assumption is made that the newdata supplied here comes sequentially after the data supplied as data in the original model (i.e. we assume there is no time gap between the last observation of series 1 in data and the first observation for series 1 in newdata). If newdata contains observations in column y, these observations will be used to compute a Discrete Rank Probability Score for the forecast distribution
data_test	Deprecated. Still works in place of newdata but users are recommended to use newdata instead for more seamless integration into R workflows
realisations	logical. If TRUE, forecast realisations are shown as a spaghetti plot, making it easier to visualise the diversity of possible forecasts. If FALSE, the default, empirical quantiles of the forecast distribution are shown
n_realisations	integer specifying the number of posterior realisations to plot, if realisations = TRUE. Ignored otherwise
hide_xlabels	logical. If TRUE, no xlabels are printed to allow the user to add custom labels using axis from base R
xlab	Label for x axis
ylab	Label for y axis
ylim	Optional vector of y-axis limits (min, max)
n_cores	integer specifying number of cores for generating forecasts in parallel
return_forecasts	logical. If TRUE, the function will plot the forecast as well as returning the forecast object (as a matrix of dimension n_samples x horizon)
return_score	logical. If TRUE and out of sample test data is provided as newdata, a probabilistic score will be calculated and returned. The score used will depend on the observation family from the fitted model. Discrete families (poisson, negative binomial, tweedie) use the Discrete Rank Probability Score. Other families use the Continuous Rank Probability Score. The value returned is the sum of all scores within the out of sample forecast horizon
...	Further par graphical parameters
x	Object of class mvgam_forecast

Details

plot_mvgam_fc generates posterior predictions from an object of class mvgam, calculates posterior empirical quantiles and plots them against the observed data. 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. This function produces an older style base R plot, as opposed to plot.mvgam_forecast

plot.mvgam_forecast takes an object of class mvgam_forecast, in which forecasts have already been computed, and plots the resulting forecast distribution as a ggplot object. This function is therefore more versatile and is recommended over the older and clunkier plot_mvgam_fc version

If realisations = FALSE, these posterior quantiles are plotted along with the true observed data that was used to train the model. Otherwise, a spaghetti plot is returned to show possible forecast paths.

Value

A base R graphics plot (for plot_mvgam_fc) or a ggplot object (for plot.mvgam_forecast) and an optional list containing the forecast distribution and the out of sample probabilistic forecast score

Author(s)

Nicholas J Clark

Examples

## Not run: 
simdat <- sim_mvgam(
  n_series = 3,
  trend_model = AR()
)

mod <- mvgam(
  y ~ s(season, bs = 'cc', k = 6),
  trend_model = AR(),
  noncentred = TRUE,
  data = simdat$data_train,
  chains = 2,
  silent = 2
)

# Hindcasts on response scale
hc <- hindcast(mod)
str(hc)
plot(hc, series = 1)
plot(hc, series = 2)
plot(hc, series = 3)

# Forecasts on response scale
fc <- forecast(
  mod,
  newdata = simdat$data_test
)
str(fc)
plot(fc, series = 1)
plot(fc, series = 2)
plot(fc, series = 3)

# Forecasts as expectations
fc <- forecast(
  mod,
  newdata = simdat$data_test,
  type = 'expected'
)
plot(fc, series = 1)
plot(fc, series = 2)
plot(fc, series = 3)

# Dynamic trend extrapolations
fc <- forecast(
  mod,
  newdata = simdat$data_test,
  type = 'trend'
)
plot(fc, series = 1)
plot(fc, series = 2)
plot(fc, series = 3)

## End(Not run)

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