forecast.bage_mod {bage} | R Documentation |
Use a Model to Make a Forecast
Description
Forecast rates, probabilities, means, and other model parameters.
Usage
## S3 method for class 'bage_mod'
forecast(
object,
newdata = NULL,
labels = NULL,
output = c("augment", "components"),
include_estimates = FALSE,
...
)
Arguments
object |
A |
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 |
... |
Not currently used. |
Value
A tibble.
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 ifexposure = 1
orweights = 1
in the original call tomod_pois()
ormod_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 viafit()
, andif any covariates (the columns of
\pmb{Z}
) are time-varying, then future values for these covariates are supplied via thenewdata
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.
See Also
-
mod_pois()
Specify a Poisson model -
mod_binom()
Specify a binomial model -
mod_norm()
Specify a normal model -
fit()
Fit a model -
augment()
Extract values for rates, probabilities, or means, together with original data -
components()
Extract values for hyper-parameters -
Mathematical Details vignette
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 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)