Title:	Baseline Nowcasting for Right-Truncated Epidemiological Data
Version:	0.2.0
Description:	Nowcasting right-truncated epidemiological data is critical for timely public health decision-making, as reporting delays can create misleading impressions of declining trends in recent data. This package provides nowcasting methods based on using empirical delay distributions and uncertainty from past performance. It is also designed to be used as a baseline method for developers of new nowcasting methods. For more details on the performance of the method(s) in this package applied to case studies of COVID-19 and norovirus, see our recent paper at https://wellcomeopenresearch.org/articles/10-614. The package supports standard data frame inputs with reference date, report date, and count columns, as well as the direct use of reporting triangles, and is compatible with 'epinowcast' objects. Alongside an opinionated default workflow, it has a low-level pipe-friendly modular interface, allowing context-specific workflows. It can accommodate a wide spectrum of reporting schedules, including mixed patterns of reference and reporting (daily-weekly, weekly-daily). It also supports sharing delay distributions and uncertainty estimates between strata, as well as custom uncertainty models and delay estimation methods.
License:	MIT + file LICENSE
URL:	https://github.com/epinowcast/baselinenowcast, https://baselinenowcast.epinowcast.org
BugReports:	https://github.com/epinowcast/baselinenowcast/issues
Depends:	R (≥ 4.1.0)
Imports:	cli, checkmate, stats, utils, rlang, purrr
Suggests:	bookdown, ChainLadder, dplyr, tidyr, stringr, lubridate, readr, ggplot2, spelling, rmarkdown, testthat (≥ 3.1.9), usethis, withr, knitr, zoo, glue
Encoding:	UTF-8
Language:	en-GB
LazyData:	true
RoxygenNote:	7.3.3
VignetteBuilder:	knitr
Config/Needs/hexsticker:	hexSticker, sysfonts, ggplot2
Config/Needs/website:	r-lib/pkgdown, epinowcast/enwtheme
NeedsCompilation:	no
Packaged:	2026-01-29 14:19:15 UTC; lshkj18
Author:	Kaitlyn Johnson [aut, cre, cph], Emily Tyszka [aut], Johannes Bracher [aut], Sebastian Funk [aut], Sam Abbott [aut], Tim Taylor [ctb]
Maintainer:	Kaitlyn Johnson <kaitlyn.johnson@lshtm.ac.uk>
Repository:	CRAN
Date/Publication:	2026-02-03 11:10:07 UTC

Internal: Add days to dates

Description

Internal: Add days to dates

Usage

.add_days(dates, delays)

Arguments

Value

Date vector

Internal: Add months to dates

Description

Internal: Add months to dates

Usage

.add_months(dates, delays)

Arguments

Value

Date vector

Internal: Add weeks to dates

Description

Internal: Add weeks to dates

Usage

.add_weeks(dates, delays)

Arguments

Value

Date vector

Internal: Add years to dates

Description

Internal: Add years to dates

Usage

.add_years(dates, delays)

Arguments

Value

Date vector

Apply mask to extract the elements of the matrix that are both true

Description

Apply mask to extract the elements of the matrix that are both true

Usage

.apply_mask(mat, indices_1, indices_2)

Arguments

Value

Matrix of same dimensions of mat with the overlapping TRUE elements only.

Assign number of reference times to delay and uncertainty from the sizes

Description

Assign number of reference times to delay and uncertainty from the sizes

Usage

.assign_allocation_from_ns(
  n_used,
  n_target,
  n_min_delay,
  n_min_retro_nowcasts,
  n_required,
  prop_delay
)

Arguments

Value

List of number of reference times to use for delay and uncertainty

Calculate the updated rows of the expected nowcasted triangle

Description

Calculate the updated rows of the expected nowcasted triangle

Usage

.calc_expectation(index, expectation, delay_prob, delay_cdf_prev, n_rows)

Arguments

Value

Matrix with another set of entries corresponding to the updated values for the specified rows and column

Calculate the number of retrospective nowcast times that can be used after aggregating

Description

Calculate the number of retrospective nowcast times that can be used after aggregating

Usage

.calc_n_retro_nowcast_times(
  list_of_obs,
  n_possible_horizons,
  ref_time_aggregator = identity
)

Arguments

Value

n_iters Integer indicating the number of iterations, or number of retrospective nowcast times, that have sufficient data once aggregated to be used to generate a retrospective point nowcast.

Helper function to calculate various size requirements

Description

Helper function to calculate various size requirements

Usage

.calculate_ns(
  reporting_triangle,
  max_delay,
  scale_factor,
  n_min_retro_nowcasts
)

Arguments

Value

list of the integer sizes

Check target size against number of reference times available and the number required

Description

Check target size against number of reference times available and the number required

Usage

.check_against_requirements(
  n_ref_times,
  n_required,
  n_target,
  n_min_delay,
  n_min_retro_nowcasts,
  scale_factor,
  max_delay
)

Arguments

Value

n_used Integer indicating how many reference times will be used

Check if there are non-zero-values on the LHS of NAs

Description

Check if there are non-zero-values on the LHS of NAs

Usage

.check_lhs_not_only_zeros(mat)

Arguments

Value

Boolean indicating whether or not there are non-zero values on the LHS of the first NA (TRUE = has non-zeros, FALSE = only zeros)

Check if matrix has valid NA pattern

Description

Check if matrix has valid NA pattern

Usage

.check_na_bottom_right(mat)

Arguments

Value

Boolean indicating whether the matrix only contains NAs in the bottom right (TRUE if only in bottom right, FALSE if elsewhere).

Check observations and predictions are compatible

Description

Check observations and predictions are compatible

Usage

.check_obs_and_pred(obs, pred)

Arguments

Value

NULL, invisibly

Combine triangle data.frames

Description

This function ingests a dataframe with case counts indexed by reference dates and report dates for one or more strata and sums all the case counts across the shared set of reference and report dates. Note that this may be a subset of the unique set of reference and report date combinations in the original data.

Usage

.combine_triangle_dfs(data, strata_cols = NULL)

Arguments

Value

result Data.frame with the same column names for reference date, report date, and case count as in data but summed across all strata in the original data.

Compute complete row statistics

Description

Compute complete row statistics

Usage

.compute_complete_row_stats(object, mat, ref_dates)

Arguments

Value

List with most_recent_complete_idx, most_recent_complete_date, most_recent_complete_count, mean_delays, and complete_rows (or NULL if no complete rows).

Compute nowcast requirement statistics

Description

Compute nowcast requirement statistics

Usage

.compute_nowcast_stats(mat)

Arguments

Value

List with dates_need_nowcast and dates_complete.

Compute quantile delay statistics for complete rows

Description

Compute quantile delay statistics for complete rows

Usage

.compute_quantile_delay_stats(object, complete_rows, p = 0.99)

Arguments

Value

Vector of quantile delays for complete rows, or NULL if none.

Compute zero value statistics

Description

Compute zero value statistics

Usage

.compute_zero_stats(mat)

Arguments

Value

List with num_zeros, pct_zeros, and zeros_per_row.

Count rows with negative values

Description

Count rows with negative values

Usage

.count_negative_rows(mat)

Arguments

Value

Integer count of rows with at least one negative value.

Internal: Compute day difference between dates

Description

Internal: Compute day difference between dates

Usage

.diff_days(report_date, reference_date)

Arguments

Value

Numeric vector of delays

Internal: Compute month difference between dates

Description

Internal: Compute month difference between dates

Usage

.diff_months(report_date, reference_date)

Arguments

Value

Numeric vector of delays

Internal: Compute week difference between dates

Description

Internal: Compute week difference between dates

Usage

.diff_weeks(report_date, reference_date)

Arguments

Value

Numeric vector of delays

Internal: Compute year difference between dates

Description

Internal: Compute year difference between dates

Usage

.diff_years(report_date, reference_date)

Arguments

Value

Numeric vector of delays

Display basic triangle information

Description

Internal helper to print common triangle metadata used by both print and summary methods.

Usage

.display_triangle_basics(x, show_dimensions = FALSE)

Arguments

Value

NULL (displays information via cli).

Extract from one matrix only elements that are missing in another

Description

Extract from one matrix only elements that are missing in another

Usage

.extract_predictions(point_nowcast_matrix, reporting_triangle)

Arguments

Value

Matrix containing the elements from point_nowcast_matrix for only the elements that are missing in reporting_triangle

Filter to recent horizons

Description

Filter to recent horizons

Usage

.filter_to_recent_horizons(mat, n_possible_horizons)

Arguments

Value

bottom_matrix Matrix containing the last n_possible_horizons rows of the matrix.

Get formatted reference date range string

Description

Internal helper to format the reference date range for display.

Usage

.format_reference_date_range(x)

Arguments

Value

Character string with formatted date range.

Get triangle dimension information

Description

Internal helper to extract key dimension information from a triangle.

Usage

.get_triangle_info(x)

Arguments

Value

List with components: n_rows, n_cols, max_delay, delays_unit, structure.

Helper for when target exceeds available reference times

Description

Helper for when target exceeds available reference times

Usage

.handle_target_exceeds_avail(
  n_ref_times,
  n_required,
  n_target,
  n_min_delay,
  n_min_retro_nowcasts
)

Arguments

Value

number of reference times to use or NULL, invisibly

Perform the allocation process

Description

Perform the allocation process

Usage

.perform_allocation_process(
  reporting_triangle,
  max_delay,
  scale_factor,
  prop_delay,
  n_min_retro_nowcasts
)

Arguments

Value

list of reference time allocations

Rename required columns

Description

Rename required columns

Usage

.rename_cols(data, old_names)

Arguments

Value

Data.frame with columns renamed

Safe iterator

Description

Safe iterator

Usage

.safelydoesit(fun)

Arguments

Value

Function that returns a list with result and error components. On success: result contains the function output and error is NULL. On failure: result is NULL and error contains the error object.

Split dataframe into a list of dataframes by the entries in the specified columns

Description

Split dataframe into a list of dataframes by the entries in the specified columns

Usage

.split_df_by_cols(long_df, col_names)

Arguments

Value

List of data.frames named by the concatenated entries in col_names

Update reporting_triangle with new matrix data

Description

Internal helper to create a new reporting_triangle from modified matrix data while preserving the original object's metadata (reference dates, delays_unit). This simplifies the pattern of converting to matrix, operating on it, then restoring the reporting_triangle class and attributes.

Usage

.update_triangle_matrix(reporting_triangle, new_matrix, reference_dates = NULL)

Arguments

Value

A new reporting_triangle object with the updated matrix data.

Validate the delay PMF if it is passed in

Description

Validate the delay PMF if it is passed in

Usage

.validate_delay(triangle, delay_pmf)

Arguments

Value

NULL invisibly

Validate triangle to nowcast and delay PMF together Various checks to make sure that the reporting triangle and the delay PMF passed in to apply_delay() are formatted properly and compatible.

Description

Validate triangle to nowcast and delay PMF together Various checks to make sure that the reporting triangle and the delay PMF passed in to apply_delay() are formatted properly and compatible.

Usage

.validate_delay_and_triangle(triangle, delay_pmf)

Arguments

Value

NULL, invisibly

Validate reporting_triangle for delay estimation Domain-specific checks to ensure the reporting triangle is suitable for delay estimation in estimate_delay().

Description

Validate reporting_triangle for delay estimation Domain-specific checks to ensure the reporting triangle is suitable for delay estimation in estimate_delay().

Usage

.validate_for_delay_estimation(triangle, n = nrow(triangle))

Arguments

Value

NULL, invisibly

Helper function to validate allocation parameters

Description

Helper function to validate allocation parameters

Usage

.validate_inputs_allocation(scale_factor, prop_delay, n_min_retro_nowcasts)

Arguments

Value

NULL invisibly

Validate the specified number of reference times meets the minimum requirements

Description

Validate the specified number of reference times meets the minimum requirements

Usage

.validate_inputs_uncertainty(
  n_ref_times,
  n_min_delay,
  n_history_delay,
  n_retrospective_nowcasts,
  n_min_retro_nowcasts = 2
)

Arguments

Value

NULL, invisibly

Validate the inputs to estimate_and_apply_uncertainty() to ensure that the reporting triangle, point nowcast matrix, and specified maximum delay are correct.

Description

Validate the inputs to estimate_and_apply_uncertainty() to ensure that the reporting triangle, point nowcast matrix, and specified maximum delay are correct.

Usage

.validate_multiple_inputs(point_nowcast_matrix, reporting_triangle)

Arguments

Value

NULL, invisibly

Validate reporting_triangle constructor arguments

Description

Internal helper to validate the arguments passed to new_reporting_triangle.

Usage

.validate_rep_tri_args(reporting_triangle_matrix, reference_dates, delays_unit)

Arguments

Validate the reporting triangle data.frame

Description

Checks for duplicate reference date report dates, missing columns, report dates beyond the final reference date, and missing combinations of delays and reports.

Usage

.validate_rep_tri_df(data, delays_unit)

Arguments

Value

NULL, invisibly

Validate each of the strata columns passed to baselinenowcast

Description

Validate each of the strata columns passed to baselinenowcast

Usage

.validate_strata_cols(strata_cols, data)

Arguments

Validate the uncertainty parameters if they are passed in

Description

Validate the uncertainty parameters if they are passed in

Usage

.validate_uncertainty(triangle, uncertainty_params)

Arguments

Value

NULL invisibly

Subset assignment for reporting_triangle objects

Description

Assignment method that allows modification of reporting_triangle values while validating the result remains a valid reporting_triangle.

Usage

## S3 replacement method for class 'reporting_triangle'
x[...] <- value

Arguments

Value

The modified reporting_triangle object.

See Also

Reporting triangle construction and validation [.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Subset reporting_triangle objects

Description

Extract or replace parts of a reporting_triangle object while preserving its attributes.

Usage

## S3 method for class 'reporting_triangle'
x[...]

Arguments

Value

A reporting_triangle object with the subset data

See Also

Reporting triangle construction and validation [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Allocate training volume based on combination of defaults and user-specified values for training volume for delay and uncertainty estimation.

Description

Given the reporting triangle and optionally the user-specified scale factor on the max delay to be used as total reference times and the proportion of those reference times to be used for delay estimation, allocate reference times to the number used for delay estimation and the number used as retrospective nowcasts for uncertainty estimation.

This function implements an algorithm which:

• if the specified number of reference times (scale_factor x ⁠max delay⁠) is less than or equal to the number of reference times available in the reporting triangle, split reference times between delay and uncertainty according to prop_delay, ensuring that the minimum requirements for delay and uncertainty estimation are met.

• if the specified number of reference times is greater than the number of reference times available in the reporting triangle, use all the reference times available and satisfy the minimum requirement for delay estimation and then split the remainder according to the specified prop_delay, ensuring that the minimum reference times for delay and uncertainty estimation are fulfilled.

• the function errors if the minimum requirements for delay and uncertainty estimation are not possible from the number of reference times in the reporting triangle.

Usage

allocate_reference_times(
  reporting_triangle,
  scale_factor = 3,
  prop_delay = 0.5,
  n_min_retro_nowcasts = 2,
  validate = TRUE
)

Arguments

Value

list of n_history_delay and n_retrospective_nowcasts

See Also

High-level workflow wrapper functions estimate_and_apply_delay(), estimate_and_apply_delays(), estimate_and_apply_uncertainty(), estimate_uncertainty_retro()

Examples

# Create a reporting triangle from package data
data_as_of <- syn_nssp_df[syn_nssp_df$report_date <= "2026-04-01", ]
rep_tri <- as_reporting_triangle(data_as_of) |>
  truncate_to_delay(max_delay = 25)

# Use the defaults (scale_factor = 3, prop_delay = 0.5)
ref_time_allocation_default <- allocate_reference_times(rep_tri)
ref_time_allocation_default

# Modify to use less volume and redistribute
ref_time_allocation_alt <- allocate_reference_times(
  reporting_triangle = rep_tri,
  scale_factor = 2,
  prop_delay = 0.6
)
ref_time_allocation_alt

Apply the delay to generate a point nowcast

Description

Generate a point estimate of a completed reporting square (or rectangle) from a reporting triangle that we want to complete with a nowcast and a delay PMF. Each element is computed by taking the product of the expected number of total cases assigned to a reference time $t$ and the proportion of those cases reported on delay $d$. The formula to obtain the expected number of total cases as a function of the reporting delay and previous observations was derived elsewhere. This code was adapted from code written (under an MIT license) by the Karlsruhe Institute of Technology RESPINOW German Hospitalization Nowcasting Hub. Modified from: https://github.com/KITmetricslab/RESPINOW-Hub/blob/7cce3ae2728116e8c8cc0e4ab29074462c24650e/code/baseline/functions.R#L55 #nolint

Usage

apply_delay(reporting_triangle, delay_pmf, validate = TRUE)

Arguments

Value

point_nowcast_matrix Matrix of the same number of rows and columns as the rep_mat_to_nowcast but with the missing values filled in as point estimates

Examples

# Example 1: Standard usage with example dataset
delay_pmf <- estimate_delay(example_reporting_triangle)
point_nowcast_matrix <- apply_delay(
  reporting_triangle = example_reporting_triangle,
  delay_pmf = delay_pmf
)
print(point_nowcast_matrix)

# Example 2: Using delay PMF with negative entries from downward corrections
delay_pmf_negative <- c(0.7, 0.4, -0.15, 0.05)
nowcast_with_corrections <- apply_delay(
  reporting_triangle = example_downward_corr_rt,
  delay_pmf = delay_pmf_negative
)
# The nowcast includes negative predictions at delay 2,
# correctly reflecting expected downward corrections
print(nowcast_with_corrections)

Apply reporting structure to generate a single retrospective reporting triangle

Description

This function applies a reporting structure to a truncated reporting triangle by setting observations to NA row by row from the bottom up based on the specified structure. It is the singular version of apply_reporting_structures().

Usage

apply_reporting_structure(
  truncated_reporting_triangle,
  structure = 1,
  validate = TRUE
)

Arguments

Value

A single retrospective reporting triangle matrix with NAs in the appropriate positions.

See Also

Retrospective data generation functions apply_reporting_structures(), truncate_to_row(), truncate_to_rows()

Examples

# Standard triangular structure (default)
rep_tri <- apply_reporting_structure(example_reporting_triangle)
rep_tri

# Ragged structure with 2 columns per delay period
rep_ragged <- apply_reporting_structure(example_reporting_triangle, 2)
rep_ragged

# Custom structure with explicit column counts
rep_custom <- apply_reporting_structure(example_reporting_triangle, c(1, 2))
rep_custom

Apply reporting structures to generate retrospective reporting triangles

Description

This function applies a reporting structure to a list of truncated reporting triangles by setting observations to NA row by row from the bottom up based on the specified structure. This generates the reporting triangles that would have been available at each retrospective time point. It operates on each element in the list in order (from most recent retrospective nowcast time to oldest retrospective nowcast time).

Usage

apply_reporting_structures(
  truncated_reporting_triangles,
  structure = 1,
  validate = TRUE
)

Arguments

Value

reporting_triangles List of retrospective reporting triangles, generated by removing the bottom right observations from the truncated reporting triangle matrices.

See Also

Retrospective data generation functions apply_reporting_structure(), truncate_to_row(), truncate_to_rows()

Examples

# Generate retrospective triangles from truncated triangles
trunc_rts <- truncate_to_rows(example_reporting_triangle, n = 2)
retro_rts <- apply_reporting_structures(trunc_rts)

# With custom structure
retro_rts_custom <- apply_reporting_structures(
  trunc_rts,
  structure = 2
)
retro_rts_custom

Convert reporting_triangle to data.frame

Description

Convert reporting_triangle to data.frame

Usage

## S3 method for class 'reporting_triangle'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data.frame with columns reference_date, report_date, delay, count

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Convert reporting triangle to data frame
df <- as.data.frame(example_reporting_triangle)
head(df)

Convert reporting_triangle to plain matrix

Description

Returns a plain matrix representation of a reporting_triangle object, removing the reporting_triangle class and custom attributes while preserving row and column names.

Usage

## S3 method for class 'reporting_triangle'
as.matrix(x, ...)

Arguments

Value

A plain matrix without reporting_triangle class or attributes.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Convert reporting_triangle to plain matrix
plain_mat <- as.matrix(example_downward_corr_rt)
class(plain_mat) # "matrix" "array"

Convert reporting_triangle to ChainLadder triangle format

Description

This function converts a reporting_triangle object to a triangle object from the ChainLadder package. ChainLadder is a mature package for claims reserving in general insurance that provides statistical methods for analysing reporting triangles, including the chain ladder technique, bootstrap methods, and diagnostic tools. Converting to ChainLadder format enables use of these specialized methods alongside baselinenowcast's nowcasting functionality.

Usage

as_ChainLadder_triangle(x, ...)

Arguments

Details

This function converts the reporting triangle to ChainLadder's triangle format using ChainLadder::as.triangle(). The ChainLadder package must be installed to use this function.

Once converted, you can use any ChainLadder methods such as:

• ChainLadder::MackChainLadder() for the Mack chain ladder method

• ChainLadder::BootChainLadder() for bootstrap chain ladder

• Standard plotting and summary methods

Note that some ChainLadder methods may require preprocessing for sparse triangles with many zeros, which can occur in syndromic surveillance data.

To convert back to a reporting_triangle object, use as_reporting_triangle.triangle().

Value

A ChainLadder triangle object (class "triangle" and "matrix"), with rows representing origin periods (reference dates) and columns representing development periods (delays).

See Also

• as_reporting_triangle.triangle() for converting back

• ChainLadder package documentation

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Create a reporting triangle from synthetic NSSP data
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)

# Convert to ChainLadder triangle format
cl_triangle <- as_ChainLadder_triangle(rep_tri)
print(cl_triangle)

# Visualize the reporting triangle structure
plot(cl_triangle)

Create a reporting_triangle object

Description

Create a reporting_triangle object

Usage

as_reporting_triangle(data, delays_unit = "days", ...)

Arguments

Value

A reporting_triangle object

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Create a reporting triangle from a data.frame
data_as_of_df <- syn_nssp_df[
  syn_nssp_df$report_date <= "2026-04-01" &
    (syn_nssp_df$report_date - syn_nssp_df$reference_date) <= 25,
]
rt <- as_reporting_triangle(data = data_as_of_df)
rt

Create a reporting_triangle object from a data.frame

Description

This method takes a data.frame containing case counts indexed by reference date and report date and creates a reporting_triangle object. See as_reporting_triangle.matrix() for other data input options.

Usage

## S3 method for class 'data.frame'
as_reporting_triangle(
  data,
  delays_unit = "days",
  reference_date = "reference_date",
  report_date = "report_date",
  count = "count",
  ...
)

Arguments

Value

A reporting_triangle object

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Filter to reasonable max_delay for faster example
data_as_of_df <- syn_nssp_df[
  syn_nssp_df$report_date <= "2026-04-01" &
    (syn_nssp_df$report_date - syn_nssp_df$reference_date) <= 25,
]
as_reporting_triangle(data = data_as_of_df)

Create a reporting_triangle from a matrix

Description

This method takes a matrix in the format of a reporting triangle, with rows as reference dates and columns as delays and elements as incident case counts and creates a reporting_triangle object. See as_reporting_triangle.data.frame() for creating from data frames.

Usage

## S3 method for class 'matrix'
as_reporting_triangle(data, delays_unit = "days", reference_dates = NULL, ...)

Arguments

Value

A reporting_triangle object

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

rep_tri_mat <- matrix(
  c(
    1, 3, 5, 7, 9,
    4, 7, 8, 0, NA,
    9, 10, 0, NA, NA,
    3, 0, NA, NA, NA,
    6, NA, NA, NA, NA
  ),
  nrow = 5,
  byrow = TRUE
)

reference_dates <- seq(
  from = as.Date("2025-01-01"),
  to = as.Date("2025-01-05"),
  by = "day"
)

# max_delay is inferred from matrix dimensions (4 in this case)
rep_tri <- as_reporting_triangle(
  data = rep_tri_mat,
  reference_dates = reference_dates
)
rep_tri

Convert ChainLadder triangle to reporting_triangle format

Description

This S3 method converts a ChainLadder triangle object to a reporting_triangle object, enabling use of baselinenowcast's nowcasting methods.

Usage

## S3 method for class 'triangle'
as_reporting_triangle(data, delays_unit = "days", reference_dates = NULL, ...)

Arguments

Details

This method converts a ChainLadder triangle back to baselinenowcast's reporting_triangle format. If reference_dates is not provided, the function will attempt to extract dates from the triangle's row names.

The ChainLadder package must be installed to use this function.

The conversion uses as_reporting_triangle.matrix() internally after extracting the matrix from the ChainLadder triangle object.

Value

A reporting_triangle object. See reporting_triangle for details on the structure.

See Also

• as_ChainLadder_triangle() for converting to ChainLadder

• as_reporting_triangle.matrix() for the underlying method

• as_reporting_triangle.data.frame() for creating from data frames

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Create a reporting triangle
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)

# Convert to ChainLadder triangle
cl_triangle <- as_ChainLadder_triangle(rep_tri)

# Convert back to reporting_triangle (seamless round-trip)
# max_delay is inferred from the ChainLadder triangle dimensions
rep_tri_2 <- as_reporting_triangle(data = cl_triangle)
print(rep_tri_2)

Assert validity of baselinenowcast_df objects

Description

Assert validity of baselinenowcast_df objects

Usage

assert_baselinenowcast_df(data)

Arguments

Value

Returns NULL invisibly. Throws an error if validation fails.

See Also

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

Examples

# Create a valid baselinenowcast_df object
valid_df <- data.frame(
  reference_date = as.Date("2024-01-01") + 0:4,
  pred_count = c(10, 15, 12, 18, 20),
  draw = 1,
  output_type = "point"
)
class(valid_df) <- c("baselinenowcast_df", "data.frame")

# Validate the object
assert_baselinenowcast_df(valid_df)

Validate each item in the reporting triangle

Description

Assert delays_unit is valid

Usage

assert_delays_unit(delays_unit)

Arguments

Value

NULL, invisibly. Stops execution with error if validation fails.

Assert validity of reporting_triangle objects

Description

Assert validity of reporting_triangle objects

Usage

assert_reporting_triangle(data, validate = TRUE)

Arguments

Value

Returns NULL invisibly. Throws an error if validation fails.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Validate an example reporting triangle
assert_reporting_triangle(example_reporting_triangle)

Generate a nowcast

Description

This function ingests data to be nowcasted and generates a a baselinenowcast_df which contains a probabilistic or point estimate of the final case counts at each reference date in the data. See baselinenowcast.reporting_triangle() for details on the input requirements.

Usage

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,
  ...
)

Arguments

Value

Data.frame of class baselinenowcast_df

See Also

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

Examples

# Generate a point nowcast from a reporting triangle
nowcast <- baselinenowcast(
  example_reporting_triangle,
  output_type = "point"
)
nowcast

# Generate probabilistic nowcast with samples
baselinenowcast(
  example_reporting_triangle,
  output_type = "samples",
  draws = 100
)

Create a dataframe of nowcast results from a dataframe of cases indexed by reference date and report date

Description

This function ingests a data.frame with the number of incident cases indexed by reference date and report date for one or multiple strata, which define the unit of a single nowcast (e.g. age groups or locations). It returns a data.frame containing nowcasts by reference date for each strata, which are by default estimated independently. This function will by default estimate uncertainty using past retrospective nowcast errors and generate probabilistic nowcasts, which are samples from the predictive distribution of the estimated final case count at each reference date.

This function implements the full nowcasting workflow on multiple reporting triangles, generating estimates of the delay and uncertainty parameters for all strata using estimates from across strata if specified.

1. estimate_delay() - Estimate a delay PMF across strata if strata_sharing contains "delay"

2. estimate_uncertainty_retro() - Estimates uncertainty parameters across strata if strata_sharing contains "uncertainty"

3. as_reporting_triangle() - Generates a reporting triangle object from a data.frame

4. baselinenowcast.reporting_triangle() - Generates point or probabilistic nowcasts depending on output_type for each strata.

@detail 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.). The function expects that each strata in the dataframe has the same maximum delay. If sharing estimates across all strata, the shared estimates will be made using the shared set of reference and report dates across strata.

Usage

## S3 method for class 'data.frame'
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,
  max_delay = NULL,
  delays_unit = "days",
  strata_cols = NULL,
  strata_sharing = "none",
  preprocess = preprocess_negative_values,
  ...
)

Arguments

Value

Data.frame of class baselinenowcast_df

See Also

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

Examples

# Filter data to exclude most recent report dates and limit to 75
# reference dates
max_ref_date <- max(germany_covid19_hosp$reference_date)
min_ref_date <- max_ref_date - 74
covid_data_to_nowcast <- germany_covid19_hosp[
  germany_covid19_hosp$report_date < max_ref_date &
    germany_covid19_hosp$reference_date >= min_ref_date,
]
nowcasts_df <- baselinenowcast(covid_data_to_nowcast,
  max_delay = 25,
  strata_cols = c("age_group", "location"),
  draws = 100
)
nowcasts_df

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 class '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,
  ...
)

Arguments

Value

Data.frame of class baselinenowcast_df

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

Nowcast Data.frame Object

Description

A baselinenowcast_df object which contains point or probabilistic nowcasts alongside reference dates and any additional metadata, in tidy data format. Nowcasts are presented aggregated across delays, by reference date.

Value

A baselinenowcast_df object. This is a data.frame subclass containing nowcast results. See the Structure section for details on the required columns.

Structure

A baselinenowcast_df is a data.frame with the following columns:

reference_date

Dates corresponding to the reference times of the nowcast.

pred_count

Numeric indicating the estimated total counts aggregated across delays at each reference date.

draw

Integer indexing the sample from the probabilistic nowcast distribution. If output_type = "point", this will be set to 1.

output_type

Character string indicating whether the pred_count represents a probabilistic draw from the observation model indicated by "samples" or whether the pred_count is a point estimate indicated by "point".

See the corresponding reporting_triangle and baselinenowcast() function for more details on the required inputs to generate the object.

See Also

Main nowcasting interface functions assert_baselinenowcast_df(), baselinenowcast(), baselinenowcast.data.frame(), baselinenowcast.reporting_triangle(), new_baselinenowcast_df()

Combine observed data with a single prediction draw

Description

Internally it sums observed counts from the reporting triangle by reference time and adds them to the predicted counts to form a single draw of the nowcast for the final counts by reference time.

Usage

combine_obs_with_pred(
  predicted_counts,
  reporting_triangle,
  ref_time_aggregator = identity,
  delay_aggregator = function(x) rowSums(x, na.rm = TRUE)
)

Arguments

Value

A vector of predicted counts at each reference date, for all reference dates in the input reporting_triangle (or fewer if using ref_time_aggregator)

See Also

Probabilistic nowcast generation functions sample_nb(), sample_nowcast(), sample_nowcasts(), sample_prediction(), sample_predictions()

Examples

# Use example data
reporting_triangle <- apply_reporting_structure(example_reporting_triangle)
pred_counts <- c(10, 20, 30, 40)
combine_obs_with_pred(pred_counts, reporting_triangle)

# Example with rolling sum
if (requireNamespace("zoo", quietly = TRUE)) {
  combine_obs_with_pred(pred_counts,
    reporting_triangle,
    ref_time_aggregator = function(x) zoo::rollsum(x, k = 2, align = "right")
  )
}

Estimate and apply delay from a reporting triangle

Description

This function generates a point nowcast by estimating a delay distribution from the reporting triangle and applying it to complete the triangle. If a delay distribution is specified, this will be used to generate the nowcast, otherwise, a delay distribution will be estimated from the reporting_triangle.

Usage

estimate_and_apply_delay(
  reporting_triangle,
  n = nrow(reporting_triangle),
  delay_pmf = NULL,
  validate = TRUE
)

Arguments

Value

pt_nowcast_matrix A reporting_triangle object of point nowcasts with the same structure as the input

See Also

High-level workflow wrapper functions allocate_reference_times(), estimate_and_apply_delays(), estimate_and_apply_uncertainty(), estimate_uncertainty_retro()

Examples

# Estimate and apply delay using default parameters
pt_nowcast_matrix <- estimate_and_apply_delay(
  reporting_triangle = example_reporting_triangle
)
pt_nowcast_matrix

# Use downward correction example with specific rows for delay estimation
pt_nowcast_matrix <- estimate_and_apply_delay(
  reporting_triangle = example_downward_corr_rt,
  n = 5
)
pt_nowcast_matrix

# Provide a pre-computed delay PMF
delay_pmf <- estimate_delay(
  reporting_triangle = example_reporting_triangle
)
pt_nowcast_matrix <- estimate_and_apply_delay(
  reporting_triangle = example_reporting_triangle,
  delay_pmf = delay_pmf
)
pt_nowcast_matrix

Estimate and apply delays to generate retrospective nowcasts

Description

This function ingests a list of incomplete reporting triangles and generates a list of point nowcast matrices, based on the delay estimated in each triangle or the corresponding delay passed in. It uses the specified n number of reference times to estimate the delay in each retrospective reporting triangle.

Usage

estimate_and_apply_delays(
  retro_reporting_triangles,
  n = min(sapply(retro_reporting_triangles, nrow)),
  delay_pmf = NULL,
  validate = TRUE
)

Arguments

Value

point_nowcast_matrices List of the same number of elements as the input retro_reporting_triangles but with each reporting triangle filled in based on the delay estimated in that reporting triangle.

See Also

High-level workflow wrapper functions allocate_reference_times(), estimate_and_apply_delay(), estimate_and_apply_uncertainty(), estimate_uncertainty_retro()

Examples

# Generate retrospective nowcasts using larger triangle
data_as_of <- syn_nssp_df[syn_nssp_df$report_date <= "2026-04-01", ]
rep_tri <- as_reporting_triangle(data_as_of) |>
  truncate_to_delay(max_delay = 25) |>
  tail(n = 50)
trunc_rts <- truncate_to_rows(rep_tri, n = 2)
retro_rts <- apply_reporting_structures(trunc_rts)
retro_pt_nowcast_mat_list <- estimate_and_apply_delays(retro_rts, n = 30)
retro_pt_nowcast_mat_list[1:2]

# Using a pre-computed delay PMF
delay <- estimate_delay(rep_tri, n = 30)
retro_pt_nowcast_mat_list <- estimate_and_apply_delays(
  retro_rts,
  n = 30,
  delay_pmf = delay
)
retro_pt_nowcast_mat_list[1:2]

Estimate and apply uncertainty to a point nowcast matrix

Description

Generates probabilistic nowcasts by estimating uncertainty parameters from retrospective nowcasts and applying them to a point nowcast matrix.

This function combines:

1. estimate_uncertainty_retro() - Estimates uncertainty parameters using retrospective nowcasts

2. sample_nowcasts() - Applies uncertainty to generate draws

To obtain estimates of uncertainty parameters, use estimate_uncertainty_retro(). For full control over individual steps (e.g., custom matrix preparation, alternative aggregation), use the low-level functions (truncate_to_rows(), apply_reporting_structures(), estimate_and_apply_delays(), estimate_uncertainty()) directly.

Usage

estimate_and_apply_uncertainty(
  point_nowcast_matrix,
  reporting_triangle,
  n_history_delay,
  n_retrospective_nowcasts,
  structure = get_reporting_structure(reporting_triangle),
  draws = 1000,
  delay_pmf = NULL,
  uncertainty_model = fit_by_horizon,
  uncertainty_sampler = sample_nb,
  validate = TRUE,
  ...
)

Arguments

Value

nowcast_draws_df Dataframe containing draws of combined observations and probabilistic predictions at each reference time.

See Also

High-level workflow wrapper functions allocate_reference_times(), estimate_and_apply_delay(), estimate_and_apply_delays(), estimate_uncertainty_retro()

Examples

# Use package data truncated to appropriate size
data_as_of <- syn_nssp_df[syn_nssp_df$report_date <= "2026-04-01", ]
triangle <- as_reporting_triangle(data_as_of) |>
  truncate_to_delay(max_delay = 25)

pt_nowcast_matrix <- estimate_and_apply_delay(
  reporting_triangle = triangle,
  n = 75
)
# Use 75 reference times for delay estimation and 40 for uncertainty
nowcast_draws_df <- estimate_and_apply_uncertainty(
  pt_nowcast_matrix,
  triangle,
  n_history_delay = 75,
  n_retrospective_nowcasts = 40,
  draws = 100
)
head(nowcast_draws_df)

Estimate a delay distribution from a reporting triangle

Description

Provides an estimate of the reporting delay as a function of the delay, based on the reporting triangle and the number of reference date observations to be used in the estimation. This point estimate of the delay is computed empirically, using an iterative algorithm starting from the most recent observations. Use truncate_to_delay() if you want to limit the maximum delay before estimation. This code was adapted from code written (under an MIT license) by the Karlsruhe Institute of Technology RESPINOW German Hospitalization Nowcasting Hub. Modified from: https://github.com/KITmetricslab/RESPINOW-Hub/blob/7cce3ae2728116e8c8cc0e4ab29074462c24650e/code/baseline/functions.R#L55 #nolint

Usage

estimate_delay(
  reporting_triangle,
  n = nrow(reporting_triangle),
  validate = TRUE
)

Arguments

Value

Vector indexed at 0 of length ncol(reporting_triangle) with columns indicating the point estimate of the empirical probability mass on each delay.

See Also

Delay distribution estimation functions preprocess_negative_values()

Examples

# Example 1: Standard usage
delay_pmf <- estimate_delay(
  reporting_triangle = example_reporting_triangle
)
delay_pmf

# Example 2: Using data with downward corrections (negatives preserved)
# Low-level functions process triangles as-is without preprocessing
delay_pmf_negative <- estimate_delay(
  reporting_triangle = example_downward_corr_rt,
  n = 5
)
delay_pmf_negative

# Example 3: Preprocess explicitly before estimation if needed
preprocessed_triangle <- preprocess_negative_values(example_downward_corr_rt)
delay_pmf_preprocessed <- estimate_delay(
  reporting_triangle = preprocessed_triangle,
  n = 5
)
delay_pmf_preprocessed

Estimate uncertainty parameters

Description

This function ingests a list of point nowcast matrices and a corresponding list of truncated reporting matrices and uses both to estimate a vector of uncertainty parameters from the observations and estimates at each horizon, starting at 0 up until the max delay number of horizons.

Usage

estimate_uncertainty(
  point_nowcast_matrices,
  truncated_reporting_triangles,
  retro_reporting_triangles,
  n = length(point_nowcast_matrices),
  uncertainty_model = fit_by_horizon,
  ref_time_aggregator = identity,
  delay_aggregator = function(x) rowSums(x, na.rm = TRUE),
  validate = TRUE
)

Arguments

Value

uncertainty_params Vector of length of the number of horizons, with each element representing the estimate of the uncertainty parameter for each horizon. The specific parameter type depends on the chosen error model.

See Also

Observation error estimation functions fit_by_horizon(), fit_nb()

Examples

# Use example data to create reporting triangle
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)

# Create retrospective nowcasts
trunc_rts <- truncate_to_rows(rep_tri, n = 2)
retro_rts <- apply_reporting_structures(trunc_rts)
retro_nowcasts <- estimate_and_apply_delays(retro_rts)

# Estimate dispersion parameters using default negative binomial model
disp_params <- estimate_uncertainty(
  point_nowcast_matrices = retro_nowcasts,
  truncated_reporting_triangles = trunc_rts,
  retro_reporting_triangles = retro_rts
)
disp_params

# Estimate dispersion parameters from rolling sum on the reference times
if (requireNamespace("zoo", quietly = TRUE)) {
  disp_params_agg <- estimate_uncertainty(
    point_nowcast_matrices = retro_nowcasts,
    truncated_reporting_triangles = trunc_rts,
    retro_reporting_triangles = retro_rts,
    ref_time_aggregator = function(x) zoo::rollsum(x, k = 2, align = "right")
  )
  disp_params_agg
}

Estimate uncertainty parameters using retrospective nowcasts

Description

Estimates uncertainty parameters for nowcasting by creating a series of retrospective datasets from the input reporting triangle, generating point nowcasts for those datasets, and calibrating uncertainty parameters based on retrospective nowcast performance.

This function chains the retrospective nowcasting workflow:

1. truncate_to_rows() - Create retrospective snapshots

2. apply_reporting_structures() - Generate retrospective reporting triangles

3. estimate_and_apply_delays() - Generate point nowcasts

4. estimate_uncertainty() - Estimate uncertainty parameters

For full probabilistic nowcasts (uncertainty estimation + sampling), use estimate_and_apply_uncertainty().

For more control over individual steps (e.g., custom matrix preparation, alternative aggregation), use the low-level functions directly.

Usage

estimate_uncertainty_retro(
  reporting_triangle,
  n_history_delay,
  n_retrospective_nowcasts,
  structure = get_reporting_structure(reporting_triangle),
  delay_pmf = NULL,
  validate = TRUE,
  ...
)

Arguments

Value

A numeric vector of uncertainty parameters with length equal to one less than the number of columns in the reporting triangle, with each element representing the estimate of the uncertainty parameter for each horizon. Returns NULL if insufficient data is available for estimation.

See Also

High-level workflow wrapper functions allocate_reference_times(), estimate_and_apply_delay(), estimate_and_apply_delays(), estimate_and_apply_uncertainty()

Examples

# Create a reporting triangle from syn_nssp_df
data_as_of <- syn_nssp_df[syn_nssp_df$report_date <= "2026-04-01", ]
rep_tri <- as_reporting_triangle(data_as_of) |>
  truncate_to_delay(max_delay = 25)

uncertainty_params <- estimate_uncertainty_retro(
  rep_tri,
  n_history_delay = 30,
  n_retrospective_nowcasts = 10
)
uncertainty_params

Example reporting triangle with downward corrections

Description

A reporting_triangle object demonstrating how to handle systematic downward corrections in reporting data. This represents a realistic case where data quality reviews at delay 2 consistently identify false positives or reclassify cases, producing negative values at that specific delay.

Usage

example_downward_corr_rt

Format

A reporting_triangle object with 8 reference dates and 4 delays:

reporting_triangle_matrix

8x4 matrix with negative values at delay 2

reference_dates

8 dates starting from 2024-01-01

delays_unit

"days"

Details

Use this example to understand:

• How to work with negative corrections in delay distributions

• The impact of preprocessing negative values on delay estimation

• How PMFs and CDFs behave with systematic downward corrections

See Also

• example_reporting_triangle for a clean example without corrections

• baselinenowcast.reporting_triangle() specifically the preprocess argument for a description of how to remove negative values if desired.

Example datasets example_reporting_triangle, germany_covid19_hosp, syn_nssp_df, syn_nssp_line_list

Examples

# View the example triangle with downward corrections
example_downward_corr_rt

# Estimate delay with and without preprocessing
delay_raw <- estimate_delay(example_downward_corr_rt, n = 5)
delay_processed <- estimate_delay(
  preprocess_negative_values(example_downward_corr_rt),
  n = 5
)

# Compare the resulting PMFs
delay_raw
delay_processed

Simple example reporting triangle for demonstrations

Description

A basic reporting_triangle object demonstrating standard structure with complete early reference times and progressively incomplete recent times. Useful for simple examples and tests.

Usage

example_reporting_triangle

Format

A reporting_triangle object with 5 reference dates and 4 delays:

reporting_triangle_matrix

5x4 matrix with counts

reference_dates

5 dates starting from 2024-01-01

delays_unit

"days"

Details

This is a simple, clean example without complications like negative values or unusual structures. Ideal for:

• Package examples demonstrating basic functionality

• Unit tests for standard cases

• Vignettes introducing nowcasting concepts

Use example_downward_corr_rt for examples with data quality corrections.

See Also

• example_downward_corr_rt for downward corrections example

• as_reporting_triangle() to create reporting triangles

Example datasets example_downward_corr_rt, germany_covid19_hosp, syn_nssp_df, syn_nssp_line_list

Examples

# View the example triangle
example_reporting_triangle

# Use in nowcasting - requires complete rows for delay estimation
estimate_delay(example_reporting_triangle, n = 6)

Helper function that fits its each column of the matrix (horizon) to an observation model.

Description

Helper function that fits its each column of the matrix (horizon) to an observation model.

Usage

fit_by_horizon(obs, pred, fit_model = fit_nb)

Arguments

Value

Vector of uncertainty parameters of the same length as the number of columns in the obs matrix.

See Also

Observation error estimation functions estimate_uncertainty(), fit_nb()

Examples

obs <- matrix(
  c(
    5, 6, 2,
    1, 4, 2,
    8, 4, 2
  ),
  nrow = 3,
  byrow = TRUE
)
pred <- matrix(
  c(
    4.2, 5.2, 1.8,
    0.7, 3.5, 3.4,
    7.3, 4.1, 1.2
  ),
  nrow = 3,
  byrow = TRUE
)
disp <- fit_by_horizon(obs = obs, pred = pred)
disp

Fit a negative binomial to a vector of observations and expectations

Description

Takes in a vector of observations and a vector of expectations and performs a MLE estimator to estimate the dispersion parameter of a negative binomial. This code was adapted from code written (under an MIT license) by the Karlsruhe Institute of Technology RESPINOW German Hospitalization Nowcasting Hub. Modified from: https://github.com/KITmetricslab/RESPINOW-Hub/blob/7fab4dce7b559c3076ab643cf22048cb5fb84cc2/code/baseline/functions.R#L404 #nolint

Usage

fit_nb(x, mu)

Arguments

Value

the maximum likelihood estimate of the dispersion

See Also

Observation error estimation functions estimate_uncertainty(), fit_by_horizon()

Examples

obs <- c(4, 8, 10)
pred <- c(3.1, 7.2, 11)
disp <- fit_nb(obs, pred)
disp

Incident COVID-19 hospitalisations indexed by the date of positive test (reference date) and report date from Germany in 2021 and 2022.

Description

Incident COVID-19 hospitalisations indexed by the date of positive test (reference date) and report date from Germany in 2021 and 2022.

Usage

germany_covid19_hosp

Format

A data.frame with 140,630 rows and 6 columns.

reference_date

Date of first positive COVID-19 test formatted in ISO8601 standards as YYYY-MM-DD.

location

Character string indicating the location of the case counts

age_group

Character string indicating the age group of the case counts.

delay

Integer specifying the delay, in days, between the reference date and the report date

count

Integer indicating the number of cases indexed by reference and report date.

report_date

Date of case report, formatted in ISO8601 standards as YYYY-MM-DD.

Source

This data comes directly from the preprocessed data in the German COVID-19 Nowcast Hub from https://github.com/KITmetricslab/hospitalization-nowcast-hub/blob/main/data-truth/COVID-19/COVID-19_hospitalizations_preprocessed.csv. #nolint It contains incident case counts by age group in Germany.

See Also

Example datasets example_downward_corr_rt, example_reporting_triangle, syn_nssp_df, syn_nssp_line_list

Compute delays between report dates and reference dates

Description

Computes delays between report dates and reference dates using the specified time unit. This is the inverse operation of get_report_dates().

Usage

get_delays_from_dates(report_dates, reference_dates, delays_unit)

Arguments

Value

Numeric vector of delays.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Compute delays in days
ref_date <- as.Date("2024-01-01")
report_date <- as.Date("2024-01-08")
get_delays_from_dates(report_date, ref_date, "days") # 7

# Compute delays in weeks
report_date_weeks <- as.Date("2024-01-15")
get_delays_from_dates(report_date_weeks, ref_date, "weeks") # 2

Get delays unit from a reporting triangle

Description

Get delays unit from a reporting triangle

Usage

get_delays_unit(x)

Arguments

Value

Character string indicating the delays unit.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

delays_unit <- get_delays_unit(example_reporting_triangle)
delays_unit

Get maximum delay from reporting_triangle

Description

Get maximum delay from reporting_triangle

Usage

get_max_delay(x, non_zero = FALSE)

Arguments

Value

Maximum delay (integer), or -1 if all zero when non_zero = TRUE

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Get maximum delay from triangle structure
max_delay <- get_max_delay(example_reporting_triangle)
max_delay

# Get maximum delay with non-zero observations
max_delay_nz <- get_max_delay(example_reporting_triangle, non_zero = TRUE)
max_delay_nz

Get mean delay for each row of reporting_triangle

Description

Get mean delay for each row of reporting_triangle

Usage

get_mean_delay(x)

Arguments

Value

Vector of mean delays for each reference date (numeric)

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

mean_delays <- get_mean_delay(example_reporting_triangle)
mean_delays

Get quantile delay for each row of reporting_triangle

Description

Get quantile delay for each row of reporting_triangle

Usage

get_quantile_delay(x, p = 0.99)

Arguments

Value

Vector of quantile delays for each reference date (integer). Returns NA for rows with no observations.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Get 99th percentile delay for each reference date
quantile_delays_99 <- get_quantile_delay(example_reporting_triangle)
quantile_delays_99

# Get median delay
median_delays <- get_quantile_delay(example_reporting_triangle, p = 0.5)
median_delays

Get reference dates from reporting_triangle

Description

Get reference dates from reporting_triangle

Usage

get_reference_dates(x)

Arguments

Value

Vector of Date objects

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

ref_dates <- get_reference_dates(example_reporting_triangle)
head(ref_dates)

Compute report dates from reference dates and delays

Description

Adds delays to reference dates using unit-aware date arithmetic.

Usage

get_report_dates(reference_dates, delays, delays_unit)

Arguments

Value

Date vector of report dates.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Compute report dates with days
ref_date <- as.Date("2024-01-01")
get_report_dates(ref_date, 7, "days") # 2024-01-08

# Compute report dates with weeks
get_report_dates(ref_date, 2, "weeks") # 2024-01-15

Get reporting structure from a reporting triangle

Description

Returns an integer or vector specifying the reporting structure, which indicates how the reporting triangle is organized. This structure tells apply_reporting_structure() how to create new reporting triangles with the same reporting pattern.

Usage

get_reporting_structure(reporting_triangle)

Arguments

Value

Integer or vector specifying the reporting structure. If integer, divides columns evenly by that integer (with last possibly truncated). If vector, the sum must not be greater than or equal to the number of columns. Default is 1 (standard triangular structure). If there are no NAs, will return 0.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Get structure from example triangle
structure <- get_reporting_structure(example_reporting_triangle)
structure

Get first rows of a reporting_triangle

Description

Get first rows of a reporting_triangle

Usage

## S3 method for class 'reporting_triangle'
head(x, n = 6L, ...)

Arguments

Value

First rows as a reporting_triangle.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Get first 3 rows
head(example_reporting_triangle, n = 3)

Check if an object is a reporting_triangle

Description

Check if an object is a reporting_triangle

Usage

is_reporting_triangle(x)

Arguments

Value

Logical indicating whether the object is a reporting_triangle.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Combine data from a nowcast dataframe, strata, and reference dates

Description

Combines data from a nowcast dataframe, a named list of the strata associated with the nowcast dataframe, and a vector of reference dates corresponding to the time column in the baselinenowcast_df

Usage

new_baselinenowcast_df(baselinenowcast_df, reference_dates, output_type)

Arguments

Value

An object of class baselinenowcast_df

See Also

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

Class constructor for reporting_triangle objects

Description

Creates a new reporting_triangle object from a matrix.

Usage

new_reporting_triangle(reporting_triangle_matrix, reference_dates, delays_unit)

Arguments

Value

An object of class reporting_triangle

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Preprocess negative values in the reporting triangle

Description

Takes in a reporting triangle and returns it with negative values of reporting handled by redistributing them to earlier delays (from longer delay to shorter). This is useful when dealing with reporting corrections that can result in negative incremental counts.

When negative values are detected, they are set to zero and the negative amount is subtracted from the count at the next earlier delay (moving from right to left in each row). This process continues until either the negative value is fully absorbed or the first delay is reached.

This code was adapted from code written (under an MIT license) by the Karlsruhe Institute of Technology RESPINOW German Hospitalization Nowcasting Hub. Modified from https://github.com/KITmetricslab/RESPINOW-Hub/blob/main/code/baseline/functions.R #nolint

Usage

preprocess_negative_values(reporting_triangle, validate = TRUE)

Arguments

Details

Use this function when:

• Your data contains reporting corrections that result in negative counts

• You want to preserve the total count while handling negatives

• You need a delay distribution that sums to 1 or a CDF that is weakly increasing

Do not use this function when:

• Your data naturally has negative PMF entries (e.g., from differencing)

• You want to preserve the original structure including negatives

• You are working with corrections that should be reflected as negative probabilities

Value

A reporting_triangle object with negative values handled via redistribution to earlier delays.

See Also

Delay distribution estimation functions estimate_delay()

Examples

# Using example dataset with negative values from corrections
# Preprocess to handle negatives
preprocessed <- preprocess_negative_values(example_downward_corr_rt)
preprocessed

Print a reporting_triangle object

Description

Print a reporting_triangle object

Usage

## S3 method for class 'reporting_triangle'
print(x, n_rows = 10, n_cols = 10, ...)

Arguments

Value

Invisibly returns the object.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Reporting Triangle Object

Description

A reporting_triangle object contains the data and metadata needed for nowcasting.

Value

A reporting_triangle object. This is a matrix subclass containing case counts indexed by reference date (rows) and delay (columns). See the Structure section for details on the object format.

Structure

A reporting_triangle is a matrix with class c("reporting_triangle", "matrix"):

• Rows: Reference dates

• Columns: Delays (0, 1, 2, ...)

• Entries: Incident cases at each reference date and delay

• Row names: Reference dates as character

• Column names: Delays as character

Attributes:

• delays_unit: Character ("days", "weeks", "months", "years")

Reference dates are stored as row names and can be extracted using get_reference_dates(). The maximum delay can be obtained using get_max_delay(). The structure can be computed using get_reporting_structure(). See the corresponding as_reporting_triangle.matrix() and as_reporting_triangle.data.frame() functions for more details on the required input formats to generate the object.

Working with reporting triangles

Reporting triangle objects provide:

Inspection and display:

• print(): Informative display with metadata

• summary(): Statistics including completion, delays, and zeros

• head(), tail(): Extract first or last rows

• Standard matrix operations: rowSums(), colSums()

Subsetting and modification:

• [ and ⁠[<-⁠: Extract or assign values with automatic validation

• Subsetting preserves class and attributes when result is a matrix

Package functions:

• estimate_and_apply_delay(): Estimate delay and generate point nowcast

• estimate_delay(): Extract delay distribution from triangle

• apply_delay(): Apply delay distribution for nowcasting

• truncate_to_row(): Remove most recent rows

• preprocess_negative_values(): Handle reporting corrections

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Create a reporting triangle from data
data <- syn_nssp_df[syn_nssp_df$report_date <= "2026-04-01", ]
rep_tri <- as_reporting_triangle(data = data)

# Use with low-level functions
filled <- estimate_and_apply_delay(rep_tri)
delay_pmf <- estimate_delay(rep_tri)
nowcast <- apply_delay(rep_tri, delay_pmf)

# Direct matrix operations
total_by_date <- rowSums(rep_tri, na.rm = TRUE)
total_by_delay <- colSums(rep_tri, na.rm = TRUE)

# Subsetting and inspection
recent <- tail(rep_tri, n = 10)
summary(rep_tri)

Sample from negative binomial model given a set of predictions

Description

Sample from negative binomial model given a set of predictions

Usage

sample_nb(pred, uncertainty_params)

Arguments

Value

sampled_pred Object of the same dimensions as pred representing a single draw from the negative binomial distribution with the specified ⁠uncertainty params⁠.

See Also

Probabilistic nowcast generation functions combine_obs_with_pred(), sample_nowcast(), sample_nowcasts(), sample_prediction(), sample_predictions()

Examples

pred <- c(3.2, 4.6)
sampled_preds <- sample_nb(pred,
  uncertainty_params = c(50, 100)
)
sampled_preds

Generate a single draw of a nowcast combining observed and predicted values

Description

Generate a single draw of a nowcast combining observed and predicted values

Usage

sample_nowcast(
  point_nowcast_matrix,
  reporting_triangle,
  uncertainty_params,
  uncertainty_sampler = sample_nb,
  ref_time_aggregator = identity,
  delay_aggregator = function(x) rowSums(x, na.rm = TRUE)
)

Arguments

Value

Vector of predicted counts at each reference date based on combining the observed counts and the predicted counts for the unobserved elements. Returns values for all reference dates in the input reporting_triangle (or fewer if using ref_time_aggregator).

See Also

Probabilistic nowcast generation functions combine_obs_with_pred(), sample_nb(), sample_nowcasts(), sample_prediction(), sample_predictions()

Examples

# Generate point nowcast and uncertainty params from example data
data_as_of <- syn_nssp_df[syn_nssp_df$report_date <= "2026-04-01", ]
rep_tri <- as_reporting_triangle(data_as_of) |>
  truncate_to_delay(max_delay = 5) |>
  tail(n = 10)
point_nowcast_matrix <- estimate_and_apply_delay(rep_tri, n = 10)
reporting_triangle <- apply_reporting_structure(rep_tri)
uncertainty_params <- estimate_uncertainty_retro(
  rep_tri,
  n_history_delay = 8,
  n_retrospective_nowcasts = 2
)
nowcast_draw <- sample_nowcast(
  point_nowcast_matrix,
  reporting_triangle,
  uncertainty_params
)
nowcast_draw

Generate multiple draws of a nowcast combining observed and predicted values

Description

Generate multiple draws of a nowcast combining observed and predicted values

Usage

sample_nowcasts(
  point_nowcast_matrix,
  reporting_triangle,
  uncertainty_params,
  draws = 1000,
  ...
)

Arguments

Value

Dataframe containing information for multiple draws with columns for the reference date (reference_date), the predicted counts (pred_count), and the draw number (draw). Returns predictions for all reference dates in the input reporting_triangle (or fewer if using ref_time_aggregator).

See Also

Probabilistic nowcast generation functions combine_obs_with_pred(), sample_nb(), sample_nowcast(), sample_prediction(), sample_predictions()

Examples

# Generate point nowcast and uncertainty params from example data
data_as_of <- syn_nssp_df[syn_nssp_df$report_date <= "2026-04-01", ]
rep_tri <- as_reporting_triangle(data_as_of) |>
  truncate_to_delay(max_delay = 5) |>
  tail(n = 10)
point_nowcast_matrix <- estimate_and_apply_delay(rep_tri, n = 10)
reporting_triangle <- apply_reporting_structure(rep_tri)
uncertainty_params <- estimate_uncertainty_retro(
  rep_tri,
  n_history_delay = 8,
  n_retrospective_nowcasts = 2
)
nowcast_draws <- sample_nowcasts(
  point_nowcast_matrix,
  reporting_triangle,
  uncertainty_params,
  draws = 5
)
nowcast_draws

Get a draw of only the predicted elements of the nowcast vector

Description

Get a draw of only the predicted elements of the nowcast vector

Usage

sample_prediction(
  point_nowcast_matrix,
  reporting_triangle,
  uncertainty_params,
  uncertainty_sampler = sample_nb,
  ref_time_aggregator = identity,
  delay_aggregator = function(x) rowSums(x, na.rm = TRUE)
)

Arguments

Value

Matrix of predicted draws at each reference date, for all reference dates in the input point_nowcast_matrix (or fewer if using ref_time_aggregator).

See Also

Probabilistic nowcast generation functions combine_obs_with_pred(), sample_nb(), sample_nowcast(), sample_nowcasts(), sample_predictions()

Examples

# Generate point nowcast and uncertainty params from example data
data_as_of <- syn_nssp_df[syn_nssp_df$report_date <= "2026-04-01", ]
rep_tri <- as_reporting_triangle(data_as_of) |>
  truncate_to_delay(max_delay = 5) |>
  tail(n = 10)
point_nowcast_matrix <- estimate_and_apply_delay(rep_tri, n = 10)
reporting_triangle <- apply_reporting_structure(rep_tri)
uncertainty_params <- estimate_uncertainty_retro(
  rep_tri,
  n_history_delay = 8,
  n_retrospective_nowcasts = 2
)
nowcast_pred_draw <- sample_prediction(
  point_nowcast_matrix,
  reporting_triangle,
  uncertainty_params
)
nowcast_pred_draw

# Get draws on the rolling sum
if (requireNamespace("zoo", quietly = TRUE)) {
  nowcast_pred_draw_agg <- sample_prediction(
    point_nowcast_matrix,
    reporting_triangle,
    uncertainty_params,
    ref_time_aggregator = function(x) zoo::rollsum(x, k = 2, align = "right")
  )
  nowcast_pred_draw_agg
}

Get a dataframe of multiple draws of only the predicted elements of the nowcast vector

Description

Get a dataframe of multiple draws of only the predicted elements of the nowcast vector

Usage

sample_predictions(
  point_nowcast_matrix,
  reporting_triangle,
  uncertainty_params,
  draws = 1000,
  ...
)

Arguments

Value

Dataframe containing the predicted point nowcast vectors indexed by predicted count (pred_count), reference date (reference_date), and the draw index (draw). Returns predictions for all reference dates in the input reporting_triangle (or fewer if using ref_time_aggregator).

See Also

Probabilistic nowcast generation functions combine_obs_with_pred(), sample_nb(), sample_nowcast(), sample_nowcasts(), sample_prediction()

Examples

# Generate point nowcast and uncertainty params from example data
data_as_of <- syn_nssp_df[syn_nssp_df$report_date <= "2026-04-01", ]
rep_tri <- as_reporting_triangle(data_as_of) |>
  truncate_to_delay(max_delay = 5) |>
  tail(n = 10)
point_nowcast_matrix <- estimate_and_apply_delay(rep_tri, n = 10)
reporting_triangle <- apply_reporting_structure(rep_tri)
uncertainty_params <- estimate_uncertainty_retro(
  rep_tri,
  n_history_delay = 8,
  n_retrospective_nowcasts = 2
)
nowcast_pred_draws <- sample_predictions(
  point_nowcast_matrix,
  reporting_triangle,
  uncertainty_params,
  draws = 5
)
nowcast_pred_draws

# Get nowcast pred draws over rolling sum
if (requireNamespace("zoo", quietly = TRUE)) {
  nowcast_pred_draws_rolling_df <- sample_predictions(
    point_nowcast_matrix,
    reporting_triangle,
    uncertainty_params,
    draws = 5,
    ref_time_aggregator = function(x) zoo::rollsum(x, k = 2, align = "right")
  )
  nowcast_pred_draws_rolling_df
}

Summarize a reporting_triangle object

Description

Summarize a reporting_triangle object

Usage

## S3 method for class 'reporting_triangle'
summary(object, ...)

Arguments

Value

Invisibly returns the object.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Display summary statistics
summary(example_reporting_triangle)

A synthetic dataset containing the number of incident cases indexed by reference date and report date. While data of this form could be from any source, this data is meant to represent the output of pre-processing the syn_nssp_line_list dataset, which is a synthetic patient-level line list data from the United State's National Syndromic Surveillance System (NSSP).

Description

A synthetic dataset containing the number of incident cases indexed by reference date and report date. While data of this form could be from any source, this data is meant to represent the output of pre-processing the syn_nssp_line_list dataset, which is a synthetic patient-level line list data from the United State's National Syndromic Surveillance System (NSSP).

Usage

syn_nssp_df

Format

A data.frame with 3795 rows and 3 columns.

reference_date

Date the primary event occurred (e.g. date of hospital admissions, specimen collection date, symptom onset), formatted in ISO8601 standards as YYYY-MM-DD.

report_date

Date the event was reported into the surveillance system, formatted as YYYY-MM-DD.

count

Number of incident events (e.g. cases) occurring on the specified reference date and reported on the report date.

Source

Created for package demonstration, made to look like the output after preprocessing the line-list data to obtain the number of incidence cases of a specific syndromic surveillance definition, indexed by the date of admission (reference date) and the date of the diagnoses being reported to the surveillance system (report date) (e.g. a reporting triangle in long format).

See Also

Example datasets example_downward_corr_rt, example_reporting_triangle, germany_covid19_hosp, syn_nssp_line_list

A synthetic dataset resembling line-list (each row is a patient) data from the United States' National Syndromic Surveillance System (NSSP) accessed via the Essence platform. All entries are synthetic, formatted to look as close to the real raw data as possible.

Description

For an example of how to produce a nowcast from this data, see vignette("nssp_nowcast").

Usage

syn_nssp_line_list

Format

A data.frame with 25 rows and 8 columns.

C_Processed_BioSenseID

Unique identifier for each patient

CCDDParsed

Character string indicating primary symptoms and corresponding diagnoses codes.

DischargeDiagnosisMDTUpdates

Character string formatted as a dictionary with indices and corresponding time stamps formatted as YYYY-MM-DD HH:MM:SS.

DischargeDiagnosisUpdates

Character string formatted as a dictionary with indices and corresponding diagnoses codes pertaining to this diagnosis associated with that event.

HasBeenAdmitted

Numeric indicating whether the patient was admitted (0 for no, 1 for admission).

C_Visit_Date_Time

Date-time indicating the time stamp of the the patient registering in the emergency department, in YYYY-MM-DD HH:MM:SS format.

c_race

Character string indicating the race/ethnicity of the patient.

sex

Character string indicating the sex of the patient.

Source

Created for package demonstration to provide an example of how to pre-process this dataset to obtain a reporting triangle. This is made to look like the data that one would pull directly an API to access patient-level line-list data.

See Also

Example datasets example_downward_corr_rt, example_reporting_triangle, germany_covid19_hosp, syn_nssp_df

Get last rows of a reporting_triangle

Description

Get last rows of a reporting_triangle

Usage

## S3 method for class 'reporting_triangle'
tail(x, n = 6L, ...)

Arguments

Value

Last rows as a reporting_triangle.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), truncate_to_delay(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Get last 3 rows
tail(example_reporting_triangle, n = 3)

Truncate reporting triangle to a specific maximum delay

Description

Creates a new reporting_triangle with columns filtered to include only delays from 0 to the specified maximum delay. This is useful when you want to limit the delay distribution used for estimation.

Usage

truncate_to_delay(x, max_delay)

Arguments

Value

A new reporting_triangle object with delays 0 through max_delay.

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_quantile(), validate_reporting_triangle()

Examples

# Truncate to delays 0-2
rt_short <- truncate_to_delay(example_downward_corr_rt, max_delay = 2)
get_max_delay(rt_short) # Returns 2

Truncate reporting_triangle to quantile-based maximum delay

Description

Automatically determines an appropriate maximum delay based on when a specified proportion of cases have been reported (CDF cutoff). This is useful for reducing computational burden when most cases are reported within a shorter delay window.

Usage

truncate_to_quantile(x, p = 0.99)

Arguments

Value

A reporting_triangle object truncated to the maximum quantile delay, or the original object if no truncation is needed

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), validate_reporting_triangle()

Examples

data_as_of_df <- syn_nssp_df[syn_nssp_df$report_date <= "2026-04-01", ]
# Create triangle, max_delay is automatically computed
rep_tri <- suppressMessages(as_reporting_triangle(data = data_as_of_df))

# Check the maximum delay in the triangle
ncol(rep_tri)

# Truncate to 99th percentile of reporting
rep_tri_trunc <- truncate_to_quantile(rep_tri, p = 0.99)
ncol(rep_tri_trunc)

# More aggressive truncation
rep_tri_trunc90 <- truncate_to_quantile(rep_tri, p = 0.90)
ncol(rep_tri_trunc90)

Truncate reporting triangle by removing a specified number of the last rows

Description

Removes the last t rows from a reporting triangle to simulate what would have been observed at an earlier reference time.

Usage

truncate_to_row(reporting_triangle, t, validate = TRUE)

Arguments

Value

trunc_rep_tri A reporting_triangle object with t fewer rows than the input. The class and metadata are preserved with updated reference dates.

See Also

Retrospective data generation functions apply_reporting_structure(), apply_reporting_structures(), truncate_to_rows()

Examples

# Generate single truncated triangle
trunc_rep_tri <- truncate_to_row(example_reporting_triangle, t = 1)
trunc_rep_tri

Truncate reporting triangle by removing bottom rows

Description

Generates a list of retrospective reporting triangles by successively removing rows from the bottom of the original triangle. Each truncated triangle represents what would have been observed at an earlier reference time. This function truncates row(s) of the reporting triangle, removing the most recent observations (starting from the bottom of the reporting triangle).

Usage

truncate_to_rows(
  reporting_triangle,
  n = nrow(reporting_triangle) - sum(is.na(rowSums(reporting_triangle))) - 1,
  validate = TRUE
)

Arguments

Value

trunc_rep_tri_list List of n truncated reporting_triangle objects with as many rows as available given the truncation, and the same number of columns as the input reporting_triangle.

See Also

Retrospective data generation functions apply_reporting_structure(), apply_reporting_structures(), truncate_to_row()

Examples

# Generate multiple truncated triangles
truncated_rts <- truncate_to_rows(example_reporting_triangle, n = 2)
truncated_rts[1:2]

Validate a reporting_triangle object

Description

Validate a reporting_triangle object

Usage

validate_reporting_triangle(data)

Arguments

Value

The validated object (invisibly) or throws error

See Also

Reporting triangle construction and validation [.reporting_triangle(), [<-.reporting_triangle(), as.data.frame.reporting_triangle(), as.matrix.reporting_triangle(), as_ChainLadder_triangle(), as_reporting_triangle(), as_reporting_triangle.data.frame(), as_reporting_triangle.matrix(), as_reporting_triangle.triangle(), assert_reporting_triangle(), get_delays_from_dates(), get_delays_unit(), get_max_delay(), get_mean_delay(), get_quantile_delay(), get_reference_dates(), get_report_dates(), get_reporting_structure(), head.reporting_triangle(), is_reporting_triangle(), new_reporting_triangle(), print.reporting_triangle(), reporting_triangle-class, summary.reporting_triangle(), tail.reporting_triangle(), truncate_to_delay(), truncate_to_quantile()