Infer infection events dates from delayed observations — deconvolve

This function reconstructs an incidence of infection events from incidence data representing delayed observations. The assumption made is that delayed observations represent the convolution of the time series of infections with a delay distribution. deconvolve_incidence implements a deconvolution algorithm (Richardson-Lucy) to reconstruct a vector of infection events from input data that represents delayed observations.

deconvolve_incidence(
  incidence_data,
  deconvolution_method = "Richardson-Lucy delay distribution",
  delay,
  simplify_output = 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).
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`
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
simplify_output	boolean. Return a numeric vector instead of module output object if output offset is zero?
...	Arguments passed on to `convolve_delays`, `.deconvolve_incidence_Richardson_Lucy` `n_report_time_steps` integer. Length of incidence time series. Use only when providing empirical delay data. `delays` List of delays, with flexible structure. Each delay in the `delays` list 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 `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?

Value

A list with two elements:

A numeric vector named values: the result of the computations on the input data.
An integer named index_offset: the offset, counted in number of time steps, by which the result is shifted compared to an index_offset of 0. 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. Note that the index_offset of the output of the function call accounts for the (optional) index_offset of the input.

If index_offset is 0 and simplify_output = TRUE, the index_offset is dropped and the values element is returned as a numeric vector.

Examples

smoothed_onset_incidence <- smooth_incidence(HK_incidence_data$onset_incidence)
smoothed_case_incidence <- smooth_incidence(HK_incidence_data$case_incidence)

## Deconvolving symptom onset data.
# In case the data to be deconvolved represents noisy observations of symptom
# onset, only the delay distribution of the incubation time needs to be specified
# (time that passes between case incidence and showing of symptoms).

shape_incubation = 3.2
scale_incubation = 1.3
delay_incubation <- list(name="gamma", shape = shape_incubation, scale = scale_incubation)

deconvolved_incidence_1 <- deconvolve_incidence(
  incidence_data = smoothed_onset_incidence,
  delay = delay_incubation
)


## Deconvolving report incidence data.
# In case the data to be deconvolved represents noisy observations of case reports,
# both the delay distribution of the incubation time and the delay distribution
# of the time that passes between symptom onset and the case being reported.

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)

deconvolved_incidence_2 <- deconvolve_incidence(
  incidence_data = smoothed_case_incidence,
  delay = list(delay_incubation, delay_onset_to_report)
)


## Other available formats for specifying delay distributions

# Discretized delay distribution vector
mean_incubation = 5.2
std_incubation = 1.6
delay_distribution_incubation <- list(name="norm",
                                      mean = mean_incubation,
                                      sd = std_incubation)
delay_incubation_vector <- build_delay_distribution(delay_distribution_incubation)

deconvolved_incidence_3 <- deconvolve_incidence(
  incidence_data = smoothed_onset_incidence,
  delay = delay_incubation_vector
)

# Discretized delay distribution matrix
delay_distribution_matrix <- get_matrix_from_empirical_delay_distr(
  HK_delay_data,
  n_report_time_steps = length(smoothed_case_incidence)
)
deconvolved_incidence_4 <- deconvolve_incidence(
  incidence_data = smoothed_case_incidence,
  delay = list(delay_incubation, delay_distribution_matrix)
)

# Dataframe containing empirical delay data
deconvolved_incidence_5 <- deconvolve_incidence(
  incidence_data = smoothed_case_incidence,
  delay = list(delay_incubation, HK_delay_data)
)