mvgam (version 1.1.594)

plot_mvgam_forecasts: 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 mvgam_forecast
plot(
  x,
  series = 1,
  realisations = FALSE,
  n_realisations = 15,
  xlab,
  ylab,
  ylim,
  ...
)

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

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

Author

Nicholas J Clark

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.

Examples

if (FALSE) {
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)
}