A primer on working with delay distributions

A brief primer on distributions in R

R and its extension packages provide rich and extensive support for representing and working with probability distributions, and this can be seen from the CRAN probability distributions task view.

Users might already be familiar with some distributions and their related functionality — such as the probability density function, or random number generation — provided in the stats package which is loaded when R is started.

For example, the Gamma distribution’s probability density function (PDF) is represented by stats::dgamma().

# the probability density function at `x` for a Gamma distribution
dgamma(x = seq(10), shape = 5, rate = 1)
#>  [1] 0.01532831 0.09022352 0.16803136 0.19536681 0.17546737 0.13385262
#>  [7] 0.09122619 0.05725229 0.03373716 0.01891664

Using delay distribution densities in cfr

To correct for reporting delays in disease severity estimation, we are primarily interested in the PDF or PMF (probability mass function) of the distribution of reporting delays between cases and known outcomes.

We refer to the R functions providing both the PDF and PMF as the density of the distribution.

The delay distribution density must be passed to functions such as cfr_static(), cfr_time_varying(), or estimate_ascertainment() via the delay_density argument. This can be represented in pseudo-code as

cfr_*(data, delay_density = <DENSITY_FUNCTION>)

Preparing delay distribution density for cfr

Importantly, the cfr functions must receive the delay density in such a way that the density can be calculated over a flexible number of values (the sequence of days in the outbreak data).

For example, by wrapping the density function for a Gamma distribution within another function which fixes the distribution parameters and accepts a vector of numbers, it can be evaluated at any set of values specified by the vector.

# wrap stats::dgamma() in a function
# the Gamma distribution parameters are contained within dens_gamma()
dens_gamma <- function(x) {
  stats::dgamma(x = x, shape = 5, scale = 1)
}

# check over a vector of `x`
dens_gamma(x = seq(10))
#>  [1] 0.01532831 0.09022352 0.16803136 0.19536681 0.17546737 0.13385262
#>  [7] 0.09122619 0.05725229 0.03373716 0.01891664

Passing delay distribution density to cfr functions

delay distribution density functions can be passed, as anonymous functions, to cfr functions as shown with the example data provided with the package Camacho et al. (2014). Parameters for the onset-to-death distribution of Ebola virus disease are taken from Barry et al. (2018).

# load package data
data("ebola1976")

# pass function wrapping dgamma to cfr_static()
cfr_static(
  data = ebola1976,
  delay_density = function(x) dgamma(x, shape = 2.40, scale = 3.33)
)
#>   severity_mean severity_low severity_high
#> 1         0.959        0.842             1

Using other distribution representations

While many R packages provide support for representing probability distributions, we focus on two examples, distributional and distcrete, to show how closures wrapping these could be implemented, while wrapping the parameters from Barry et al. (2018).

Users may wish to use these or similar packages for better management of distributions and parameters. See the CRAN probability distributions task view for more information on distribution packages suitable for different use cases.

# using {distributional} and parameters from Barry et al. 2018
dist_onset_to_death_ebola <- dist_gamma(shape = 2.40, rate = 1.0 / 3.33)

# wrap function and pass it to cfr_static()
# unlist() required as density(<distribution>, x) is a list
cfr_static(
  data = ebola1976,
  delay_density = function(x) unlist(density(dist_onset_to_death_ebola, x))
)
#>   severity_mean severity_low severity_high
#> 1         0.959        0.842             1

# using {distcrete} and parameters from Barry et al. 2018
dist_onset_to_death_ebola <- distcrete(
  name = "gamma", shape = 2.40, scale = 3.33, interval = 1
)

# pass density function to cfr_static()
cfr_static(
  data = ebola1976,
  delay_density = dist_onset_to_death_ebola$d
)
#>   severity_mean severity_low severity_high
#> 1         0.959        0.842             1

Links to epiparameter

While users can pass functions from stats, and can manage distribution parameters using specialised packages and classes, it may be convenient to be able to access parameters reported in the epidemiological literature from a curated library.

The forthcoming epiparameter package aims to be such a library of epidemiological delay distributions. The dedicated <epidist> class is expected to have similar functionality to other distribution classes, allowing easy definition of density functions that can be passed to cfr.

The pseudo-code below shows how this might work.

# NOTE: this is pseudo-code
EPIDIST_OBJECT <- ACCESS_DISTRIBUTION(disease, study)

cfr_*(data = data, delay_density = function(x) density(<EPIDIST_OBJECT> x))