baselinenowcast (version 0.2.0)

baselinenowcast.reporting_triangle: Create a dataframe of nowcast results from a single reporting triangle

Description

This function ingests a single reporting_triangle object and generates a nowcast in the form of a baselinenowcast_df object.

This function implements a nowcasting workflow for a single reporting triangle:

1. allocate_reference_times() - Allocate the reference times used for delay and uncertainty estimation

2. estimate_delay() - Estimate a reporting delay PMF

3. apply_delay() - Generate a point nowcast using the delay PMF

4. estimate_and_apply_uncertainty() - Generate a probabilistic nowcast from a point nowcast and reporting triangle

This function will by default estimate the delay from the reporting_triangle and estimate uncertainty using past retrospective nowcast errors on that reporting_triangle to generate probabilistic nowcasts, which are samples from the predictive distribution of the estimated final case count at each reference date. Alternatives include passing in a separate delay_pmf or uncertainty_params. This method specifically computes a nowcast for a single reporting triangle. See documentation for the arguments of this function which can be used to set the model specifications (things like number of reference times for delay and uncertainty estimation, the observation model, etc.).

Usage

# S3 method for reporting_triangle
baselinenowcast(
  data,
  scale_factor = 3,
  prop_delay = 0.5,
  output_type = c("samples", "point"),
  draws = 1000,
  uncertainty_model = fit_by_horizon,
  uncertainty_sampler = sample_nb,
  delay_pmf = NULL,
  uncertainty_params = NULL,
  preprocess = preprocess_negative_values,
  validate = TRUE,
  ...
)

Value

Data.frame of class baselinenowcast_df

Arguments

data

reporting_triangle class object to be nowcasted. The matrix must contain missing observations in the form of NAs in order to generate an output from this function.

scale_factor

Numeric value indicating the multiplicative factor on the maximum delay to be used for estimation of delay and uncertainty. Default is 3.

prop_delay

Numeric value <1 indicating what proportion of all reference times in the reporting triangle to be used for delay estimation. Default is 0.5.

output_type

Character string indicating whether the output should be samples ("samples") from the estimate with full uncertainty or whether to return the point estimate ("point"). Default is "samples". If "point"estimates are specified, the minimum number of reference times needed is the number needed for delay estimation, otherwise, if "samples" are specified, at least 2 additional reference times are required for uncertainty estimation.

draws

Integer indicating the number of probabilistic draws to include if output_type is "samples". Default is 1000.

uncertainty_model

Function that ingests a matrix of observations and a matrix of predictions and returns a vector that can be used to apply uncertainty using the same error model. Default is fit_by_horizon with arguments of obs matrix of observations and pred the matrix of predictions that fits each column (horizon) to a negative binomial observation model by default. The user can specify a different fitting model by replacing the fit_model argument in fit_by_horizon.

uncertainty_sampler

Function that ingests a vector or matrix of predictions and a vector of uncertainty parameters and generates draws from the observation model. Default is sample_nb which expects arguments pred for the vector of predictions and uncertainty parameters for the corresponding vector of uncertainty parameters, and draws from a negative binomial for each element of the vector.

delay_pmf

Vector of delays assumed to be indexed starting at the first delay column in the reporting triangle. Default is NULL, which will estimate the delay from the reporting triangle in data. See estimate_delay() for more details.

uncertainty_params

Vector of uncertainty parameters ordered from horizon 1 to the maximum horizon. Default is NULL, which will result in computing the uncertainty parameters from the reporting triangle data. See estimate_uncertainty() for more details.

preprocess

Function to apply to the reporting triangle before estimation, or NULL to skip preprocessing. Default is preprocess_negative_values(), which handles negative values by redistributing them to earlier delays. Set to NULL if you want to preserve negative values. Custom preprocess functions must accept a validate parameter (defaults to TRUE) to enable validation optimisation in internal function chains.

validate

Logical. If TRUE (default), validates the object. Set to FALSE only when called from functions that already validated.

...

Additional arguments passed to estimate_uncertainty() and sample_nowcast().

See Also

Main nowcasting interface functions assert_baselinenowcast_df(), baselinenowcast(), baselinenowcast.data.frame(), baselinenowcast_df-class, new_baselinenowcast_df()

Examples

# Filter to recent data and truncate to reasonable max_delay for faster
# example
data_as_of_df <- syn_nssp_df[syn_nssp_df$report_date <= "2026-04-01", ]
rep_tri <- as_reporting_triangle(data = data_as_of_df) |>
  truncate_to_delay(max_delay = 25) |>
  tail(n = 40)
nowcast_df <- baselinenowcast(rep_tri, draws = 100)
nowcast_df