forecast.bage_mod: Use a Model to Make a Forecast

Description

Forecast rates, probabilities, means, and other model parameters.

Usage

# S3 method for bage_mod
forecast(
  object,
  newdata = NULL,
  labels = NULL,
  output = c("augment", "components"),
  include_estimates = FALSE,
  ...
)

Value

A tibble.

Arguments

object: A bage_mod object, typically created with mod_pois(), mod_binom(), or mod_norm().
newdata: Data frame with data for future periods.
labels: Labels for future values.
output: Type of output returned
include_estimates: Whether to include historical estimates along with the forecasts. Default is FALSE.
...: Not currently used.

How the forecasts are constructed

Internally, the steps involved in a forecast are:

Forecast time-varying main effects and interactions, e.g. a time main effect, or an age-time interaction.
Combine forecasts for the time-varying main effects and interactions with non-time-varying parameters, e.g. age effects or dispersion.
Use the combined parameters to generate values for rates, probabilities or means.
Optionally, generate values for the outcome variable.

forecast() generates values for the outcome variable when,

output is "augment",
a value has been supplied for newdata,
newdata included a value for the exposure, size, or weights variable (except if exposure = 1 or weights = 1 in the original call to mod_pois() or mod_norm()).

Mathematical Details gives more details on the internal calculations in forecasting.

Output format

When output is "augment" (the default), the return value from forecast() looks like output from function augment(). When output is "components", the return value looks like output from components().

When include_estimates is FALSE (the default), the output of forecast() excludes values for time-varying parameters for the period covered by the data. When include_estimates is TRUE, the output includes these values. Setting include_estimates to TRUE can be helpful when creating graphs that combine estimates and forecasts.

Forecasting with covariates

Models that contain covariates can be used in forecasts, provided that

all coefficients (the \(\zeta_p\)) are estimated from historical data via fit(), and
if any covariates (the columns of \(\pmb{Z}\)) are time-varying, then future values for these covariates are supplied via the newdata argument.

Fitted and unfitted models

forecast() is typically used with a fitted model, i.e. a model in which parameter values have been estimated from the data. The resulting forecasts reflect data and priors.

forecast() can, however, be used with an unfitted model. In this case, the forecasts are based entirely on the priors. See below for an example. Experimenting with forecasts based entirely on the priors can be helpful for choosing an appropriate model.

Warning

The interface for forecast() has not been finalised.

Examples

Run this code

## specify and fit model
mod <- mod_pois(injuries ~ age * sex + ethnicity + year,
                data = nzl_injuries,
                exposure = popn) |>
  fit()
mod

## forecasts
mod |>
  forecast(labels = 2019:2024)

## combined estimates and forecasts
mod |>
  forecast(labels = 2019:2024,
           include_estimates = TRUE)

## hyper-parameters
mod |>
  forecast(labels = 2019:2024,
           output = "components")

## hold back some data and forecast
library(dplyr, warn.conflicts = FALSE)
data_historical <- nzl_injuries |>
  filter(year <= 2015)
data_forecast <- nzl_injuries |>
  filter(year > 2015) |>
  mutate(injuries = NA)
mod_pois(injuries ~ age * sex + ethnicity + year,
         data = data_historical,
         exposure = popn) |>
  fit() |>
  forecast(newdata = data_forecast)

## forecast using GDP per capita in 2023 as a covariate
mod_births <- mod_pois(births ~ age * region + time,
                       data = kor_births,
                       exposure = popn) |>
  set_covariates(~ gdp_pc_2023) |>
  fit()
mod_births |>
  forecast(labels = 2024:2025)

Run the code above in your browser using DataLab