In reconhub/simulacr: Outbreak simulation using branching processes

Welcome to the simulacr package!

This package is under development. Do not use it without contacting the authors first.

Installing the package

To install the current stable, CRAN version of the package, type:

install.packages("simulacr")

To benefit from the latest features and bug fixes, install the development, github version of the package using:

devtools::install_github("reconhub/simulacr")

Note that this requires the package devtools installed.

What does it do?

simulacr implements outbreak simulation using branching processes. The main features of the package include:

• simulate_outbreak: the main function, allowing to simulate outbreaks for specified values of reproduction number, incubation period, duration of infectiousness, and optionally reporting delays; it outputs a linelist stored as a data.frame with the class outbreak, including information on transmission chains; the output can be converted to epicontacts objects for visualisation, and plotted using plot(...)

• as_epicontacts: a function to convert outbreak object to epicontact; called implicitely when plotting outbreak objects

• make_disc_gamma: wrapper function to build discretised Gamma distributions easily

• draw_labels: wrapper function to generate random alphanumeric labels

Worked example

This brief example illustrates how we can simulate an outbreak, with different ways of specifying input distributions.

Specifying delay distributions

Distributions can be specified in different ways:

• as a discretised distribution stored as distcrete object, e.g. generated via make_disc_gamma
• as a function with a single argument (the delay) computing probability mass function (pmf) of different delays
• as a vector of $n$ positive numbers, taken to be the pmf of delays of 0:($n$-1)

We illustrate these different options below, with:

• a flat distribution of the incubation time 1-4 days (all other values have a null probability)
• an infectious period defined as a discretised Gamma distribution stored as a distcrete object
• a reporting delay following a Poisson distribution, specified as a function

library("simulacr")

incubation <- c(0, 1, 1, 1, 1) # numbers = unscaled PMF
infectious_period <- make_disc_gamma(10, 7) # distcrete object
reporting <- function(x) dpois(x, 5) # PMF function

Simulating an outbreak

set.seed(1)
x <- simulate_outbreak(R = runif(100, 1, 3), # random values on [1;3]
                       dist_incubation= incubation,
                       dist_infectious_period = infectious_period,
                       dist_reporting = reporting)

The output is a data.frame with the class outbreak, which contains a linelist of cases:

class(x)
dim(x)
head(x)
tail(x)

This object can be plotted using (this will open an interactive graph:

plot(x)

For any work relying on transmission trees, it may be easiest to convert the outbreak object to an epicontacts:

net <- as_epicontacts(x)
net

Simulating contacts

Contacts can be simulated and added to a simulated outbreak, using similar procedures to the one used in simulate_outbreak, with a few differences:

• n_contacts: the numbers of contacts per index case is specified in the same way as the reproduction number R in simulate_outbreaks

• the two distributions relate to the time between onset of the index case and the beginning of secondar exposures (dist_time_to_contact) and the duration of the exposure window (duration) after the first day of contact

## exposure starts 0-2 days post onset
time_to_contact = c(1, 1, 1)

## geom dist for duration of exposure
duration <- function(x) dgeom(x, prob = .9)

x_with_contacts <- simulate_contacts(
    x[1:10, ],
    n_contacts = 1:10, # 1 to 10 contacts
    dist_time_to_contact = time_to_contact,
    dist_duration = duration)

## check output
class(x_with_contacts)
dim(x_with_contacts)
head(x_with_contacts)

plot(x_with_contacts)

Resources

Vignettes

No vignette currently available.

Getting help online

Bug reports and feature requests should be posted on github using the issue system. All other questions should be posted on the RECON forum:
http://www.repidemicsconsortium.org/forum/

Contributions are welcome via pull requests.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

reconhub/simulacr documentation built on Dec. 9, 2020, 7:57 p.m.