forecast.mvgam: Extract or compute hindcasts and forecasts for a fitted...
In mvgam: Multivariate (Dynamic) Generalized Additive Models

forecast.mvgam

R Documentation

Extract or compute hindcasts and forecasts for a fitted `mvgam` object

Description

Extract or compute hindcasts and forecasts for a fitted mvgam object

Usage

## S3 method for class 'mvgam'
forecast(object, newdata, data_test, n_cores = 1, type = "response", ...)

Arguments

`object`	`list` object of class `mvgam` or `jsdgam`. See `mvgam()`
`newdata`	Optional `dataframe` or `list` of test data containing the same variables that were included in the original `data` used to fit the model. 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 in the original model (i.e. we assume there is no time gap between the last observation of series 1 in the original data and the first observation for series 1 in `newdata`)
`data_test`	Deprecated. Still works in place of `newdata` but users are recommended to use `newdata` instead for more seamless integration into `R` workflows
`n_cores`	Deprecated. Parallel processing is no longer supported
`type`	When this has the value `link` (default) the linear predictor is calculated on the link scale. If `expected` is used, predictions reflect the expectation of the response (the mean) but ignore uncertainty in the observation process. When `response` is used, the predictions take uncertainty in the observation process into account to return predictions on the outcome scale. When `variance` is used, the variance of the response with respect to the mean (mean-variance relationship) is returned. When `type = "terms"`, each component of the linear predictor is returned separately in the form of a `list` (possibly with standard errors, if `summary = TRUE`): this includes parametric model components, followed by each smooth component, but excludes any offset and any intercept. Two special cases are also allowed: type `latent_N` will return the estimated latent abundances from an N-mixture distribution, while type `detection` will return the estimated detection probability from an N-mixture distribution
`...`	Ignored

Details

Posterior predictions are drawn from the fitted mvgam and used to simulate a forecast distribution

Value

An object of class mvgam_forecast containing hindcast and forecast distributions. See mvgam_forecast-class for details.

Examples

## Not run: 
  # Simulate data with 3 series and AR trend model
  simdat <- sim_mvgam(n_series = 3, trend_model = AR())

  # Fit mvgam model
  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)

  # Use summary() to extract hindcasts / forecasts for custom plotting
  head(summary(hc), 12)

  # Or just use the plot() function for quick plots
  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)
  head(summary(fc), 12)
  plot(fc, series = 1)
  plot(fc, series = 2)
  plot(fc, series = 3)

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

  # Dynamic trend extrapolations
  fc <- forecast(
    mod,
    newdata = simdat$data_test,
    type = 'trend'
  )
  head(summary(fc), 12)
  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.