simulate_chain_stats {epichains} | R Documentation |
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
)
Arguments
n_chains |
Number of chains to simulate. |
statistic |
The chain statistic to track as the
stopping criteria for each chain being simulated when
|
offspring_dist |
Offspring distribution: a |
... |
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 |
pop |
Population size; An |
percent_immune |
Percent of the population immune to
infection at the start of the simulation; A |
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.
simulate_chain_stats()
vs simulate_chains()
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(s)
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. doi: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. doi: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. doi: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
)