Estimate Re from incidence and estimate uncertainty with block-bootstrapping — get_block_bootstrapped

An estimation of the effective reproductive number through time is made on the original incidence data. Then, the same estimation is performed on a number of bootstrap samples built from the original incidence data. The estimate on the original data is output along with confidence interval boundaries built from the distribution of bootstrapped estimates.

get_block_bootstrapped_estimate(
  incidence_data,
  N_bootstrap_replicates = 100,
  smoothing_method = "LOESS",
  deconvolution_method = "Richardson-Lucy delay distribution",
  estimation_method = "EpiEstim sliding window",
  uncertainty_summary_method = "original estimate - CI from bootstrap estimates",
  combine_bootstrap_and_estimation_uncertainties = FALSE,
  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).
N_bootstrap_replicates	integer. Number of bootstrap samples.
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`
uncertainty_summary_method	string. One of the following options: 'NONE' if no summary of bootstrap estimates is required 'original estimate - CI from bootstrap estimates'. The confidence interval is built using bootstrapped estimates and centered around the original estimates. 'bagged mean - CI from bootstrap estimates'. The confidence interval is built using bootstrapped estimates and centered around the mean of bootstrapped estimates and original estimates.
combine_bootstrap_and_estimation_uncertainties	boolean. If TRUE, the uncertainty interval reported is the union of the highest posterior density interval from the Re estimation with the confidence interval from the boostrapping of time series of observations.
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`.

Value

Effective reproductive estimates through time with confidence interval boundaries. If output_Re_only is FALSE, then transformations made on the input observations during calculations are output as well.

Examples

## Basic usage of get_block_bootstrapped_estimate
# (Only 10 bootstrap replicates are generated to keep the code fast. In practice,
# use more.)

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 <- get_block_bootstrapped_estimate(
  HK_incidence_data$case_incidence,
  N_bootstrap_replicates = 10,
  delay = list(delay_incubation, delay_onset_to_report)
)


## Advanced usage of get_block_bootstrapped_estimate
# (Only 10 bootstrap replicates are generated to keep the code fast. In practice,
# use more.)


# 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 <- get_block_bootstrapped_estimate(
  HK_incidence_data$case_incidence,
  N_bootstrap_replicates = 10,
  delay = list(delay_incubation, HK_delay_data),
  ref_date = HK_incidence_data$date[1],
  estimation_method = 'EpiEstim piecewise constant',
  interval_length = 7,
  uncertainty_summary_method = 'bagged mean - CI from bootstrap estimates',
  mean_Re_prior = 1.25
)

# Incorporating prior knowledge over the disease. Here, we assume the mean of the
# serial interval to be 5 days, and the deviation is assumed to be 2.5 days. The
# delay between symptom onset and case confirmation is passed as empirical data.

Re_estimate_3 <- get_block_bootstrapped_estimate(
  HK_incidence_data$case_incidence,
  N_bootstrap_replicates = 10,
  delay = list(delay_incubation, HK_delay_data),
  ref_date = HK_incidence_data$date[1],
  mean_serial_interval = 5,
  std_serial_interval = 2.5
)