estimate_Re_from_noisy_delayed_incidence: Estimate Re from incidence data

In covid-19-Re/estimateR: Reproductive number estimation from delayed observations of infections

Estimate Re from incidence data

Description

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.

Usage

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: A numeric vector named values: the incidence recorded on consecutive time steps. 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: 'LOESS', implemented in .smooth_LOESS
deconvolution_method	string. Method used to infer timings of infection events from the original incidence data (aka deconvolution step). Available options are: 'Richardson-Lucy delay distribution', implemented in .deconvolve_incidence_Richardson_Lucy
estimation_method	string. Method used to estimate reproductive number values through time from the reconstructed infection timings. Available options are: 'EpiEstim sliding window', implemented in .estimate_Re_EpiEstim_sliding_window 'EpiEstim piecewise constant', implemented in .estimate_Re_EpiEstim_piecewise_constant
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: A numeric vector named values: the incidence recorded on consecutive time steps. 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.

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.

Value

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

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

covid-19-Re/estimateR documentation built on Sept. 14, 2024, 5:49 a.m.