epichains (version 0.1.1)

simulate_chain_stats: Simulate a vector of transmission chains statistics (sizes/lengths)

Description

It generates a vector of transmission chain sizes or lengths using the same model as simulate_chains() but without tracking details of the individual chains. This function is useful when only the chain sizes or lengths are of interest.

It uses a simple branching process model that simulates independent chains, using an offspring distribution for each chain. Each chain uses a threshold chain size or length as the stopping criterion especially where R0 > 1. The function also optionally accepts population related inputs such as the population size (defaults to Inf) and percentage of the population initially immune (defaults to 0).

Usage

simulate_chain_stats(
  n_chains,
  statistic = c("size", "length"),
  offspring_dist,
  ...,
  stat_threshold = Inf,
  pop = Inf,
  percent_immune = 0
)

Value

An object of class <epichains_summary>, which is a numeric vector of chain sizes or lengths with extra attributes for storing the simulation parameters.

Arguments

n_chains

Number of chains to simulate.

statistic

The chain statistic to track as the stopping criteria for each chain being simulated when stat_threshold is not Inf; A <string>. It can be one of:

• "size": the total number of cases produced by a chain before it goes extinct.

• "length": the total number of generations reached by a chain before it goes extinct.

offspring_dist

Offspring distribution: a <function> like the ones provided by R to generate random numbers from given distributions (e.g., rpois for Poisson). More specifically, the function needs to accept at least one argument, n, which is the number of random numbers to generate. It can accept further arguments, which will be passed on to the random number generating functions. Examples that can be provided here are rpois for Poisson distributed offspring, rnbinom for negative binomial offspring, or custom functions.

...

Parameters of the offspring distribution as required by R.

stat_threshold

A stopping criterion for individual chain simulations; a positive number coercible to integer. When any chain's cumulative statistic reaches or surpasses stat_threshold, that chain ends. It also serves as a censoring limit so that results above the specified value, are set to Inf. Defaults to Inf.

pop

Population size; An <Integer>. Used alongside percent_immune to define the susceptible population. Defaults to Inf.

percent_immune

Percent of the population immune to infection at the start of the simulation; A <numeric> between 0 and 1. Used alongside pop to initialise the susceptible population. Defaults to 0.

<code>simulate_chain_stats()</code> vs <code>simulate_chains()</code>

simulate_chain_stats() is a time-invariant version of simulate_chains(). In particular, it does not track the details of individual transmission events but deals with eventual chain statistics, that is, the statistic realised by a chain after dying out.

It is useful for generating a vector of chain sizes or lengths for a given number of chains, if details of who infected whom and the timing of infection are not of interest.

This function is used in {epichains} for calculating likelihoods in the likelihood() function and for sampling from the borel distribution (See ?epichains::rborel). It is used extensively in the vignette on modelling disease control, where only data on observed chain sizes and lengths are available.

Definition of a transmission chain

A transmission chain as used here is an independent case and all the secondary cases linked to it through transmission. The chain starts with a single case, and each case in the chain generates secondary cases according to the offspring distribution. The chain ends when no more secondary cases are generated.

Calculating chain sizes and lengths

The function simulates the chain size for chain \(i\) at time \(t\), \(I_{t, i}\), as: $$I_{t, i} = \sum_{i}^{I_{t-1}}X_{t, i},$$ and the chain length/duration for chain \(i\) at time \(t\), \(L_{t, i}\), as: $$L_{t, i} = {\sf min}(1, X_{t, i}), $$ where \(X_{t, i}\) is the secondary cases generated by chain \(i\) at time \(t\), and \(I_{0, i} = L_{0, i} = 1\).

The distribution of secondary cases, \(X_{t, i}\) is modelled by the offspring distribution (offspring_dist).

Author

James M. Azam, Sebastian Funk

References

Jacob C. (2010). Branching processes: their role in epidemiology. International journal of environmental research and public health, 7(3), 1186–1204. tools:::Rd_expr_doi("https://doi.org/10.3390/ijerph7031204")

Blumberg, S., and J. O. Lloyd-Smith. 2013. "Comparing Methods for Estimating R0 from the Size Distribution of Subcritical Transmission Chains." Epidemics 5 (3): 131–45. tools:::Rd_expr_doi("https://doi.org/10.1016/j.epidem.2013.05.002").

Farrington, C. P., M. N. Kanaan, and N. J. Gay. 2003. "Branching Process Models for Surveillance of Infectious Diseases Controlled by Mass Vaccination.” Biostatistics (Oxford, England) 4 (2): 279–95. tools:::Rd_expr_doi("https://doi.org/10.1093/biostatistics/4.2.279").

Examples

# Simulate chain sizes with a poisson offspring distribution, assuming an
# infinite population and no immunity.
set.seed(32)
simulate_chain_stats(
  n_chains = 20,
  statistic = "size",
  offspring_dist = rpois,
  stat_threshold = 10,
  lambda = 0.9
)
# Simulate chain sizes with a negative binomial distribution and assuming
# a finite population and 10% immunity.
set.seed(32)
simulate_chain_stats(
  pop = 1000,
  percent_immune = 0.1,
  n_chains = 20,
  statistic = "size",
  offspring_dist = rnbinom,
  stat_threshold = 10,
  mu = 0.9,
  size = 0.36
)