Estimate Re from incidence data

This pipe function combines a smoothing step using (to remove noise from the original observations), a deconvolution step (to retrieve infection events from the observed delays), and an Re estimation step wrapping around estimate_R.

estimate_Re_from_noisy_delayed_incidence(
  incidence_data,
  smoothing_method = "LOESS",
  deconvolution_method = "Richardson-Lucy delay distribution",
  estimation_method = "EpiEstim sliding window",
  delay,
  import_incidence_data = NULL,
  ref_date = NULL,
  time_step = "day",
  output_Re_only = TRUE,
  ...
)

Arguments

incidence_data

An object containing incidence data through time. It can either be:

  • A list with two elements:

    1. A numeric vector named values: the incidence recorded on consecutive time steps.

    2. An integer named index_offset: the offset, counted in number of time steps, by which the first value in values is shifted compared to a reference time step This parameter allows one to keep track of the date of the first value in values without needing to carry a date column around. A positive offset means values are delayed in the future compared to the reference values. A negative offset means the opposite.

  • A numeric vector. The vector corresponds to the values element descrived above, and index_offset is implicitely zero. This means that the first value in incidence_data is associated with the reference time step (no shift towards the future or past).
smoothing_method

string. Method used to smooth the original incidence data. Available options are:
deconvolution_method

string. Method used to infer timings of infection events from the original incidence data (aka deconvolution step). Available options are:
estimation_method

string. Method used to estimate reproductive number values through time from the reconstructed infection timings. Available options are:
delay

Single delay or list of delays. Each delay can be one of:

  • a list representing a distribution object

  • a discretized delay distribution vector

  • a discretized delay distribution matrix

  • a dataframe containing empirical delay data
import_incidence_data

NULL or argument with the same requirements as incidence_data. If not NULL, this argument represents records of imported cases and incidence_data represents local cases only.
ref_date

Date. Optional. Date of the first data entry in incidence_data
time_step

string. Time between two consecutive incidence datapoints. "day", "2 days", "week", "year"... (see seq.Date for details)
output_Re_only

boolean. Should the output only contain Re estimates? (as opposed to containing results for each intermediate step)
...

Arguments passed on to .smooth_LOESS, .deconvolve_incidence_Richardson_Lucy, .estimate_Re_EpiEstim_sliding_window, .estimate_Re_EpiEstim_piecewise_constant

data_points_incl

integer. Size of the window used in the LOESS algorithm. The span parameter passed to loess is computed as the ratio of data_points_incl and the number of time steps in the input data.

degree

integer. LOESS degree. Must be 0, 1 or 2.

initial_Re_estimate_window

integer. In order to help with the smoothing, the function extends the data back in time, padding with values obtained by assuming a constant Re. This parameter represents the number of timesteps in the beginning of incidence_input to take into account when computing the average initial Re.

delay_distribution

numeric square matrix or vector.

threshold_chi_squared

numeric scalar. Threshold for chi-squared values under which the R-L algorithm stops.

max_iterations

integer. Maximum threshold for the number of iterations in the R-L algorithm.

verbose

Boolean. Print verbose output?

estimation_window

Use with estimation_method = "EpiEstim sliding window" Positive integer value. Number of data points over which to assume Re to be constant.

import_incidence_input

NULL or module input object. List with two elements:

  1. A numeric vector named values: the incidence recorded on consecutive time steps.

  2. An integer named index_offset: the offset, counted in number of time steps, by which the first value in values is shifted compared to a reference time step This parameter allows one to keep track of the date of the first value in values without needing to carry a date column around. A positive offset means values are delayed in the future compared to the reference values. A negative offset means the opposite.

If not NULL, this data represents recorded imported cases. And then incidence_input represents only local cases.

minimum_cumul_incidence

Numeric value. Minimum number of cumulated infections before starting the Re estimation. Default is 12 as recommended in Cori et al., 2013.

mean_serial_interval

Numeric positive value. mean_si for estimate_R

std_serial_interval

Numeric positive value. std_si for estimate_R

mean_Re_prior

Numeric positive value. mean prior for estimate_R

output_HPD

Boolean. If TRUE, return the highest posterior density interval with the output.

interval_ends

Use with estimation_method = "EpiEstim piecewise constant" Integer vector. Optional argument. If provided, interval_ends overrides the interval_length argument. Each element of interval_ends specifies the right boundary of an interval over which Re is assumed to be constant for the calculation. Values in interval_ends must be integer values corresponding with the same numbering of time steps as given by incidence_input. In other words, interval_ends and incidence_input, use the same time step as the zero-th time step.

interval_length

Use with estimation_method = "EpiEstim piecewise constant" Positive integer value. Re is assumed constant over steps of size interval_length.

Value

Time series of effective reproductive number estimates through time. If ref_date is provided then a date column is included with the output.

Details

The smoothing step uses the LOESS method by default. The deconvolution step uses the Richardson-Lucy algorithm by default. The Re estimation uses the Cori method with a sliding window by default.

Examples

## Basic usage of estimate_Re_from_noisy_delayed_incidence
shape_incubation = 3.2
scale_incubation = 1.3
delay_incubation <- list(name="gamma", shape = shape_incubation, scale = scale_incubation)

shape_onset_to_report = 2.7
scale_onset_to_report = 1.6
delay_onset_to_report <- list(name="gamma",
                              shape = shape_onset_to_report,
                              scale = scale_onset_to_report)

Re_estimate_1 <- estimate_Re_from_noisy_delayed_incidence(
  incidence_data = HK_incidence_data$case_incidence,
  delay = list(delay_incubation, delay_onset_to_report)
)

## Advanced usage of estimate_Re_from_noisy_delayed_incidence
# Incorporating prior knowledge over Re. Here, Re is assumed constant over a time
# frame of one week, with a prior mean of 1.25.
Re_estimate_2 <- estimate_Re_from_noisy_delayed_incidence(
  incidence_data = HK_incidence_data$case_incidence,
  delay = list(delay_incubation, delay_onset_to_report),
  estimation_method = "EpiEstim piecewise constant",
  interval_length = 7,
  mean_Re_prior = 1.25
)

# Incorporating prior knowledge over the disease. Here, the mean of the serial
# interval is assumed to be 5 days, and the standard deviation is assumed to be
# 2.5 days.
Re_estimate_3 <- estimate_Re_from_noisy_delayed_incidence(
  incidence_data = HK_incidence_data$case_incidence,
  delay = list(delay_incubation, delay_onset_to_report),
  mean_serial_interval = 5,
  std_serial_interval = 1.25
)

# Incorporating prior knowledge over the epidemic. Here, it is assumed that Re
# changes values 4 times during the epidemic, so the intervals over which Re is
# assumed to be constant are passed as a parameter.
last_interval_index <- length(HK_incidence_data$case_incidence)
Re_estimate_4 <- estimate_Re_from_noisy_delayed_incidence(
  incidence_data = HK_incidence_data$case_incidence,
  delay = list(delay_incubation, delay_onset_to_report),
  estimation_method = "EpiEstim piecewise constant",
  interval_ends = c(50, 75, 100, 160, last_interval_index)
)