chain_sim | R Documentation |
chain_sim()
is a stochastic simulator for generating
transmission chain data with key inputs such as the offspring distribution
and serial interval distribution.
chain_sim(
n,
offspring,
stat = c("size", "length"),
infinite = Inf,
tree = FALSE,
serial,
t0 = 0,
tf = Inf,
...
)
n |
Number of simulations to run. |
offspring |
Offspring distribution: a character string corresponding to
the R distribution function (e.g., "pois" for Poisson, where
|
stat |
String; Statistic to calculate. Can be one of:
|
infinite |
A size or length above which the simulation results
should be set to |
tree |
Logical. Should the transmission tree be returned? Defaults
to |
serial |
The serial interval generator function; the name of a
user-defined named or anonymous function with only one argument |
t0 |
Start time (if serial interval is given); either a single value
or a vector of length |
tf |
End time (if serial interval is given). |
... |
Parameters of the offspring distribution as required by R. |
chain_sim()
either returns a vector or a data.frame. The output is
either a vector if serial
is not provided, which automatically sets
tree = FALSE
, or a data.frame
, which means that serial
was
provided as a function. When serial
is provided, it means
tree = TRUE
automatically. However, setting tree = TRUE
would require providing a function for serial
.
Either:
A vector of sizes/lengths (if tree == FALSE
OR serial
interval function not specified, since that implies
tree == FALSE
), or
a data frame with
columns n
(simulation ID), time
(if the serial interval is given) and
(if tree == TRUE
), id
(a unique ID within each simulation for
each individual element of the chain), ancestor
(the ID of the
ancestor of each element), and generation
.
serial
):In epidemiology, the generation interval is the duration between successive infectious events in a chain of transmission. Similarly, the serial interval is the duration between observed symptom onset times between successive cases in a transmission chain. The generation interval is often hard to observe because exact times of infection are hard to measure hence, the serial interval is often used instead. Here, we use the serial interval to represent what would normally be called the generation interval, that is, the time between successive cases.
serial
in chain_sim()
serial
must be specified as a named or
anonymous/inline/unnamed function # nolint
with one argument.
If serial
is specified, chain_sim()
returns times of
infection as a column in the output. Moreover, specifying a function
for serial
implies tree = TRUE
and a tree of
infectors (ancestor
) and infectees (id
) will be generated in the output.
For example, assuming we want to specify the serial interval
generator as a random log-normally distributed variable with
meanlog = 0.58
and sdlog = 1.58
, we could define a named function,
let's call it "serial_interval", with only one argument representing the
number of serial intervals to sample:
serial_interval <- function(n){rlnorm(n, 0.58, 1.38)}
,
and assign the name of the function to serial in chain_sim()
like so
chain_sim(..., serial = serial_interval)
,
where ...
are the other arguments to chain_sim()
. Alternatively, we
could assign an anonymous function to serial in the chain_sim()
call
like so chain_sim(..., serial = function(n){rlnorm(n, 0.58, 1.38)})
,
where ...
are the other arguments to chain_sim()
.
Sebastian Funk, James M. Azam
# Specifying no `serial` and `tree == FALSE` (default) returns a vector
set.seed(123)
chain_sim(n = 5, offspring = "pois", stat = "size", lambda = 0.5,
tree = FALSE)
# Specifying `serial` without specifying `tree` will set `tree = TRUE`
# internally.
# We'll first define the serial function
set.seed(123)
serial_interval <- function(n) {
rlnorm(n, meanlog = 0.58, sdlog = 1.58)
}
chain_sim(
n = 5, offspring = "pois", lambda = 0.5, stat = "length",
infinite = 100,
serial = serial_interval
)
# Specifying `serial` and `tree = FALSE` will throw a warning saying that
# `tree` was set to `TRUE` internally.
set.seed(123)
## Not run:
try(chain_sim(
n = 10, serial = function(x) 3, offspring = "pois", lambda = 2,
infinite = 10, tree = FALSE
))
## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.