bage (version 0.9.0)

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,
  output = c("augment", "components"),
  include_estimates = FALSE,
  labels = NULL,
  ...
)

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.

output

Type of output returned

include_estimates

Whether to include historical estimates along with the forecasts. Default is FALSE.

labels

Labels for future values.

...

Not currently used.

How the forecasts are constructed

Internally, the steps involved in a forecast are:

1. Forecast time-varying main effects and interactions, e.g. a time main effect, or an age-time interaction.

2. Combine forecasts for the time-varying main effects and interactions with non-time-varying parameters, e.g. age effects or dispersion.

3. Use the combined parameters to generate values for rates, probabilities or means.

4. If a newdata argument has been provided, and output is "augment", draw values for outcome.

vignette("vig2_math") has the technical details.

Output

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.

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.

See Also

• mod_pois(), mod_binom(), mod_norm() to specify a model

• fit() to fit a model

Examples

## 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 based on priors only
mod_unfitted <- mod_pois(injuries ~ age * sex + ethnicity + year,
                         data = nzl_injuries,
                         exposure = popn)
mod_unfitted |>
  forecast(labels = 2019:2024)