Skip to contents

Use a Model to Make a Forecast

Source: R/bage_mod-methods.R
forecast.bage_mod.Rd

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

Usage

# S3 method for class 'bage_mod'
forecast(
  object,
  newdata = NULL,
  output = c("augment", "components"),
  include_estimates = FALSE,
  standardize = c("terms", "anova", "none"),
  labels = NULL,
  ...
)

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.

standardize

Standardization method: one of "terms", "anova", or "none". The default is "terms". See below for details.

labels

Labels for future values.

...

Not currently used.

Value

A tibble.

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.

Standardization

The standardization used by forecast() is equivalent to the standardization applied by components(), except that values for forecasted terms are are shifted so that they line up with the values for estimates.

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

Examples

## specify and fit model
mod <- mod_pois(injuries ~ age * sex + ethnicity + year,
                data = injuries,
                exposure = popn) |>
  fit()
mod
#> -- Fitted Poisson model --
#> 
#>    injuries ~ age * sex + ethnicity + year
#> 
#> (Intercept) ~ NFix()
#>         age ~ RW()
#>         sex ~ NFix()
#>   ethnicity ~ NFix()
#>        year ~ RW()
#>     age:sex ~ RW()
#> 
#>       term n_par n_par_free std_dev
#>        age    12         12   0.730
#>        sex     2          2   0.110
#>  ethnicity     2          2   0.450
#>       year    19         19   0.092
#>    age:sex    24         24   0.430
#> 
#>      dispersion: mean=1
#>        exposure: popn
#>         var_age: age
#>   var_sexgender: sex
#>        var_time: year
#>          n_draw: 1000

## forecasts
mod |>
  forecast(labels = 2019:2024)
#> # A tibble: 288 × 9
#>    age   sex    ethnicity  year injuries  popn .observed
#>    <fct> <chr>  <chr>     <int>    <dbl> <int>     <dbl>
#>  1 0-4   Female Maori      2019       NA    NA        NA
#>  2 0-4   Female Maori      2020       NA    NA        NA
#>  3 0-4   Female Maori      2021       NA    NA        NA
#>  4 0-4   Female Maori      2022       NA    NA        NA
#>  5 0-4   Female Maori      2023       NA    NA        NA
#>  6 0-4   Female Maori      2024       NA    NA        NA
#>  7 0-4   Female Non Maori  2019       NA    NA        NA
#>  8 0-4   Female Non Maori  2020       NA    NA        NA
#>  9 0-4   Female Non Maori  2021       NA    NA        NA
#> 10 0-4   Female Non Maori  2022       NA    NA        NA
#> # ℹ 278 more rows
#> # ℹ 2 more variables: .fitted <rdbl<1000>>, .expected <rdbl<1000>>

## combined estimates and forecasts
mod |>
  forecast(labels = 2019:2024,
           include_estimates = TRUE)
#> # A tibble: 1,200 × 9
#>    age   sex    ethnicity  year injuries  popn .observed
#>    <fct> <chr>  <chr>     <int>    <dbl> <int>     <dbl>
#>  1 0-4   Female Maori      2000       12 35830 0.000335 
#>  2 5-9   Female Maori      2000        6 35120 0.000171 
#>  3 10-14 Female Maori      2000        3 32830 0.0000914
#>  4 15-19 Female Maori      2000        6 27130 0.000221 
#>  5 20-24 Female Maori      2000        6 24380 0.000246 
#>  6 25-29 Female Maori      2000        6 24160 0.000248 
#>  7 30-34 Female Maori      2000       12 22560 0.000532 
#>  8 35-39 Female Maori      2000        3 22230 0.000135 
#>  9 40-44 Female Maori      2000        6 18130 0.000331 
#> 10 45-49 Female Maori      2000        6 13770 0.000436 
#> # ℹ 1,190 more rows
#> # ℹ 2 more variables: .fitted <rdbl<1000>>, .expected <rdbl<1000>>

## hyper-parameters
mod |>
  forecast(labels = 2019:2024,
           output = "components")
#> # A tibble: 6 × 4
#>   term  component level                .fitted
#>   <chr> <chr>     <chr>           <rdbl<1000>>
#> 1 year  effect    2019  -0.097 (-0.21, 0.0084)
#> 2 year  effect    2020   -0.097 (-0.24, 0.046)
#> 3 year  effect    2021   -0.097 (-0.27, 0.082)
#> 4 year  effect    2022     -0.096 (-0.3, 0.11)
#> 5 year  effect    2023    -0.096 (-0.32, 0.12)
#> 6 year  effect    2024    -0.095 (-0.32, 0.14)

## hold back some data and forecast
library(dplyr, warn.conflicts = FALSE)
data_historical <- injuries |>
  filter(year <= 2015)
data_forecast <- injuries |>
  filter(year > 2015) |>
  mutate(injuries = NA)
mod_pois(injuries ~ age * sex + ethnicity + year,
         data = data_historical,
         exposure = popn) |>
  fit() |>
  forecast(newdata = data_forecast)
#> # A tibble: 144 × 9
#>    age   sex    ethnicity  year     injuries  popn .observed
#>    <fct> <chr>  <chr>     <int> <rdbl<1000>> <int>     <dbl>
#>  1 0-4   Female Maori      2016    8 (3, 15) 41220        NA
#>  2 5-9   Female Maori      2016     2 (0, 6) 43230        NA
#>  3 10-14 Female Maori      2016     2 (0, 6) 37640        NA
#>  4 15-19 Female Maori      2016   12 (6, 21) 36040        NA
#>  5 20-24 Female Maori      2016   10 (4, 19) 33760        NA
#>  6 25-29 Female Maori      2016    8 (2, 15) 30530        NA
#>  7 30-34 Female Maori      2016    6 (2, 12) 24480        NA
#>  8 35-39 Female Maori      2016    6 (1, 12) 23170        NA
#>  9 40-44 Female Maori      2016    6 (2, 12) 23940        NA
#> 10 45-49 Female Maori      2016    6 (2, 12) 23580        NA
#> # ℹ 134 more rows
#> # ℹ 2 more variables: .fitted <rdbl<1000>>, .expected <rdbl<1000>>

## forecast based on priors only
mod_unfitted <- mod_pois(injuries ~ age * sex + ethnicity + year,
                         data = injuries,
                         exposure = popn)
mod_unfitted |>
  forecast(labels = 2019:2024)
#> ℹ Model not fitted, so values drawn straight from prior distribution.
#> # A tibble: 288 × 9
#>    age   sex    ethnicity  year injuries  popn .observed               .fitted
#>    <fct> <chr>  <chr>     <int>    <dbl> <int>     <dbl>          <rdbl<1000>>
#>  1 0-4   Female Maori      2019       NA    NA        NA 0.52 (4.7e-06, 26982)
#>  2 0-4   Female Maori      2020       NA    NA        NA 0.58 (2.2e-06, 61073)
#>  3 0-4   Female Maori      2021       NA    NA        NA 0.57 (3.4e-06, 39302)
#>  4 0-4   Female Maori      2022       NA    NA        NA 0.59 (4.4e-06, 40226)
#>  5 0-4   Female Maori      2023       NA    NA        NA  0.5 (1.6e-06, 49473)
#>  6 0-4   Female Maori      2024       NA    NA        NA 0.61 (1.5e-06, 1e+05)
#>  7 0-4   Female Non Maori  2019       NA    NA        NA 0.48 (6.7e-06, 50684)
#>  8 0-4   Female Non Maori  2020       NA    NA        NA 0.61 (2.7e-06, 45910)
#>  9 0-4   Female Non Maori  2021       NA    NA        NA 0.52 (1.5e-06, 66433)
#> 10 0-4   Female Non Maori  2022       NA    NA        NA 0.58 (2.3e-06, 42274)
#> # ℹ 278 more rows
#> # ℹ 1 more variable: .expected <rdbl<1000>>