Predict Method for RtGam Models

Generates posterior draws from an RtGam fit. Prediction dates can be specified flexibly using various approaches, and predictions can be drawn for different model parameters.

Usage

# S3 method for class 'RtGam'
predict(
  object,
  parameter = "obs_cases",
  horizon = NULL,
  min_date = NULL,
  max_date = NULL,
  n = 100,
  mean_delay = NULL,
  gi_pmf = NULL,
  seed = 12345,
  ...
)

Arguments

object

An RtGam object created using the RtGam() function.

parameter

A character string specifying the prediction target. Options are "obs_cases" (observed cases), "r" (growth rate), or "Rt" reproduction number). Default is "obs_cases".

horizon

Optional. An integer indicating the number of days to forecast beyond the last date in the model fit. For example, horizon = 7 predicts the next 7 days.

min_date, max_date

Optional. Date-like objects specifying the start and end of the prediction range. See Details for more information on their usage.

n

An integer specifying the number of posterior samples to use for predictions. Default is 100.

mean_delay

Optional. An integer specifying the mean number of days between an individual becoming infected and their case being observed (e.g., through an emergency department visit or hospitalization). This value shifts the predictions to account for reporting delays. It is required when predicting "r" (growth rate) or "Rt" (reproduction number).

gi_pmf

Optional. A numeric vector specifying the generation interval probability mass function (PMF), required when parameter = "Rt". The PMF must be a proper probability distribution (summing to one) with the first element set to zero to exclude same-day transmission, as required by the renewal equation. For more information and tools to handle delay distributions, see the primarycensored package.

seed

An integer specifying the random seed for reproducibility. Default is 12345.

...

Additional arguments passed to the underlying sampling functions:

• When parameter = "obs_cases", arguments are passed to gratia: posterior_samples.

• When parameter = "r" or "Rt", arguments are passed to gratia: fitted_samples.

Value

A data frame in tidy format, where each row represents a posterior draw for a specific date, with the following columns:

• reference_date: The prediction date.

• .response: The predicted value for the target parameter.

• .draw: The index of the posterior draw.

Example output:

  reference_date .response .draw
1     2023-01-01        18     1
2     2023-01-02        13     1
3     2023-01-03        21     1
4     2023-01-01        11     2
5     2023-01-02        19     2
6     2023-01-03        24     2

Details

Prediction dates can be defined in four ways:

1. Default Date Range: By using only the fit object, predictions are made across the full date range in the original model.

2. Using horizon: Extends predictions up to horizon days beyond the last date in the model fit.

3. Using min_date and horizon: Predictions start from min_date and extend up to horizon days after the fit’s last date.

4. Using min_date and max_date: Generates predictions for all dates within this specified range, inclusive.

The mean_delay parameter adjusts predictions for the temporal lag between infection and case observation. For example, if mean_delay = 5, the model assumes that observed cases reflect infections that occurred on average five days earlier. This adjustment ensures that estimates of growth rates ("r") and reproduction numbers ("Rt") align with the correct underlying temporal dynamics.

The parameter argument determines the type of predictions:

• "obs_cases": Observed cases, including uncertainty from the model's fit.

• "r": Growth rate, calculated using the centered difference between time steps.

• "Rt": Reproduction number, incorporating delay distributions and convolution.