epichains

Methods for simulating and analysing the sizes and lengths of infectious disease transmission chains from branching process models

https://github.com/epiverse-trace/epichains

Keywords

Repository

Methods for simulating and analysing the sizes and lengths of infectious disease transmission chains from branching process models

README.Rmd

---
output: github_document
bibliography: vignettes/references.json
link-citations: true
---







```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = file.path("man", "figures", "README-"),
  out.width = "100%",
  echo = TRUE
)
```

# _{{ packagename }}_: Methods for simulating and analysing the size and length of transmission chains from branching process models 


[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![R-CMD-check](https://github.com/epiverse-trace/epichains/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/epiverse-trace/epichains/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/{{ gh_repo }}/branch/main/graph/badge.svg)](https://app.codecov.io/gh/{{ gh_repo }}?branch=main)
[![Lifecycle:
experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![CRAN status](https://www.r-pkg.org/badges/version/epichains)](https://CRAN.R-project.org/package=epichains)
[![month-download](https://cranlogs.r-pkg.org/badges/epichains)](https://cran.r-project.org/package=epichains)
[![total-download](https://cranlogs.r-pkg.org/badges/grand-total/epichains)](https://cran.r-project.org/package=epichains)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13945039.svg)](https://doi.org/10.5281/zenodo.13945039)


_{{ packagename }}_ is an R package to simulate, analyse, and visualize the size 
and length of branching processes with a given offspring distribution. These 
models are often used in infectious disease epidemiology, where the chains represent chains of
transmission, and the offspring distribution represents the distribution of 
secondary infections caused by an infected individual. 

_{{ packagename }}_ re-implements [bpmodels](https://github.com/epiforecasts/bpmodels/)
by providing bespoke functions and data structures that allow easy
manipulation and interoperability with other Epiverse-TRACE packages, for example, [superspreading](https://github.com/epiverse-trace/superspreading/) and [epiparameter](https://github.com/epiverse-trace/epiparameter/), and potentially some existing packages for handling transmission chains, for example, [epicontacts](https://github.com/reconhub/epicontacts).

_{{ packagename }}_ is developed at the [Centre for the Mathematical Modelling of Infectious Diseases](https://www.lshtm.ac.uk/research/centres/centre-mathematical-modelling-infectious-diseases) at the London School of Hygiene and Tropical Medicine as part of the [Epiverse Initiative](https://data.org/initiatives/epiverse/).

## Installation

Install the released version of the package:

```{r install_cran, include=TRUE,eval=FALSE}
install.packages("{{ packagename }}")
```

The latest development version of the _{{ packagename }}_ package can be installed via

```{r install_with_remotes, include=TRUE,eval=FALSE}
# check whether {remotes} is installed
if (!require("remotes")) install.packages("remotes")
remotes::install_github("{{ gh_repo }}")
```

If this fails, try using the `pak` R package via

```{r install_with_pak, include=TRUE,eval=FALSE}
# check whether {pak} is installed
if (!require("pak")) install.packages("pak")
pak::pak("{{ gh_repo }}")
```

If both of these options fail, please [file an issue](https://github.com/epiverse-trace/epichains/issues) with a full log of the error messages. Here is an [example of an issue reporting an installation failure](https://github.com/epiverse-trace/epichains/issues/262). This will help us to improve the installation process.

To load the package, use

```{r load_pkg, eval=TRUE}
library("{{ packagename }}")
```

## Quick start

_{{ packagename }}_ provides three main functions:

* `simulate_chains()`: simulates transmission chains using a simple
branching process model that accepts an index number of cases that seed
the outbreak, a distribution of offspring per case, and a chain statistic
to track (size or length/duration). It optionally accepts other population
related inputs such as the population size (defaults to Inf) and percentage
of the population initially immune (defaults to 0). This function returns
an object with columns that track information on who infected whom, the
generation of infection and, if a generation time function is specified, the
time of infection.

* `simulate_chain_stats()`: provides a performant version of `simulate_chains()`
that only tracks and return a vector of realized chain sizes or
lengths/durations for each index case without details of the infection tree.

* `likelihood()`: calculates the loglikelihood (or likelihood, depending
on the value of `log`) of observing a vector of transmission chain sizes or
lengths.

The objects returned by the `simulate_*()` functions can be summarised with
`summary()`. Running `summary()` on the output of `simulate_chains()` will
return the same output as `simulate_chain_stats()` using the same inputs.

Objects returned from `simulate_chains()` can be aggregated into a
`` of cases per time or generation
with the function `aggregate()`.

The simulated `` object can be plotted in various ways using
`plot()`. See the plotting section in `vignette("epichains")` for two
use cases.

### Simulation

For the simulation functionality, let's look at a simple example where we
simulate a transmission chain with $20$ index cases, a constant generation time
of $3$, and a poisson offspring distribution with mean $1$. We are tracking the
chain "size" statistic and will cap all chain sizes at $25$ cases. We will then
look at the summary of the simulation, and aggregate it into cases per
generation.
```{r simulate_chains, eval=TRUE}
set.seed(32)
# Simulate chains
sim_chains <- simulate_chains(
  n_chains = 20,
  statistic = "size",
  offspring_dist = rpois,
  stat_threshold = 25,
  generation_time = function(n) {
    rep(3, n)
  }, # constant generation time of 3
  lambda = 1 # mean of the Poisson distribution
)
# View the head of the simulation
head(sim_chains)

# Summarise the simulation
summary(sim_chains)

# Aggregate the simulation into cases per generation
chains_agregegated <- aggregate(sim_chains, by = "generation")

# view the time series of cases per generation
chains_agregegated
```

### Inference

Let's look at the following example where we estimate the log-likelihood of
observing a hypothetical `chain_lengths` dataset.
```{r likelihood_example, eval=TRUE}
set.seed(32)
# randomly generate 20 chain lengths between 1 to 40
chain_lengths <- sample(1:40, 20, replace = TRUE)
chain_lengths

# estimate loglikelihood of the observed chain sizes
likelihood_eg <- likelihood(
  chains = chain_lengths,
  statistic = "length",
  offspring_dist = rpois,
  lambda = 0.99
)
# Print the estimate
likelihood_eg
```

Each of the listed functionalities is demonstrated in detail
in the ["Getting Started" vignette](https://epiverse-trace.github.io/epichains/articles/epichains.html).

## Package websites

The package has two websites: one for [the stable release version on CRAN](https://epiverse-trace.github.io/epichains/), and another for [the version in development](https://epiverse-trace.github.io/epichains/dev/).

## Package vignettes

The theory behind the models provided here can be
found in the [theory vignette](https://epiverse-trace.github.io/epichains/articles/theoretical_background.html).

We have also collated a bibliography of branching process applications in 
epidemiology. These can be found in the [literature vignette](https://epiverse-trace.github.io/epichains/articles/branching_process_literature.html).

Specific use cases of _{{ packagename }}_ can be found in 
the [online documentation as package vignettes](https://epiverse-trace.github.io/epichains/), under "Articles".

## Related R packages

As far as we know, below are the existing R packages for simulating branching
processes and transmission chains. 



Click to expand

* [bpmodels](https://github.com/epiforecasts/bpmodels/): provides methods 
for analysing the size and length of transmission chains from branching 
process models. `{epichains}` supersedes `{bpmodels}`, which has been retired.

* [ringbp](https://github.com/epiforecasts/ringbp): a branching process 
model, parameterised to the 2019-nCoV outbreak, and used to quantify 
the potential effectiveness of contact tracing and isolation of cases.

* [covidhm](https://github.com/biouea/covidhm): code for simulating 
COVID-19 dynamics in a range of scenarios across a real-world social 
network. The model is conceptually based on `{ringbp}`.

* [epicontacts](https://github.com/reconhub/epicontacts): provides methods
for handling, analysing, and visualizing transmission chains and contact-tracing 
data/linelists.

* [simulist](https://epiverse-trace.github.io/simulist/): uses a branching
process model to simulate individual-level infectious disease outbreak data,
including line lists and contact tracing data. This package is part of the
Epiverse-TRACE Initiative.

* [superspreading](https://epiverse-trace.github.io/superspreading/): provides
a set of functions to estimate and understand individual-level variation in
transmission of infectious diseases from data on secondary cases. These are
useful for understanding the role of superspreading in the spread of infectious
diseases and for informing public health interventions.

* [earlyR](https://github.com/reconhub/earlyR): estimates the reproduction 
number (R), in the early stages of an outbreak. The model requires a 
specified serial interval distribution, characterised by the mean and 
standard deviation of the (Gamma) distribution, and data on daily disease 
incidence, including only confirmed and probable cases.

* [projections](https://github.com/reconhub/projections): uses data on daily 
incidence, the serial interval (time between onsets of infectors and 
infectees) and the reproduction number to simulate plausible epidemic 
trajectories and project future incidence. It relies on a branching process 
where daily incidence follows a Poisson or a Negative Binomial distribution
governed by a force of infection.

* [simulacr](https://github.com/reconhub/simulacr): simulates outbreaks 
for specified values of reproduction number, incubation period, duration 
of infectiousness, and optionally reporting delays. Outputs a linelist 
stored as a `data.frame` with the class `outbreak`, including information
on transmission chains; the output can be converted to ``
objects for visualisation.

* [outbreakr2](https://github.com/reconhub/outbreaker2): a Bayesian 
framework for integrating epidemiological and genetic data to reconstruct 
transmission trees of densely sampled outbreaks. It re-implements, 
generalises and replaces the model of outbreaker, and uses a modular
approach which enables fine customisation of priors, likelihoods 
and parameter movements.

* [o2geosocial](https://github.com/alxsrobert/o2geosocial): integrates
geographical and social contact data to reconstruct transmission chains. 
It combines the age group, location, onset date and genotype of cases 
to infer their import status, and their likely infector.

* [nosoi](https://github.com/slequime/nosoi): simulates agent-based 
transmission chains by taking into account the influence of multiple 
variables on the transmission process (e.g. dual-host systems 
(such as arboviruses), within-host viral dynamics, transportation, 
population structure), alone or taken together, to create complex 
but relatively intuitive epidemiological simulations.

* [TransPhylo](https://xavierdidelot.github.io/TransPhylo/index.html):
reconstructs infectious disease transmission using genomic data.


## Reporting bugs 

To report a bug please open an [issue](https://github.com/epiverse-trace/epichains/issues/new/choose).

## Contribute

Contributions to {epichains} are welcomed. Please follow the [package contributing guide](https://github.com/epiverse-trace/.github/blob/main/CONTRIBUTING.md).

## Code of conduct

Please note that the _{{ packagename }}_ project is released with a [Contributor Code of Conduct](https://github.com/epiverse-trace/.github/blob/main/CODE_OF_CONDUCT.md). 
By contributing to this project, you agree to abide by its terms.

## Citing this package

```{r citation, message=FALSE, warning=FALSE}
citation("epichains")
```

Owner

Citation (CITATION.cff)

# --------------------------------------------
# CITATION file created with {cffr} R package
# See also: https://docs.ropensci.org/cffr/
# --------------------------------------------
 
cff-version: 1.2.0
message: 'To cite package "epichains" in publications use:'
type: software
license: MIT
title: 'epichains: Simulating and Analysing Transmission Chain Statistics Using Branching
  Process Models'
version: 0.1.1.9000
doi: 10.32614/CRAN.package.epichains
abstract: Provides methods to simulate and analyse the size and length of branching
  processes with an arbitrary offspring distribution. These can be used, for example,
  to analyse the distribution of chain sizes or length of infectious disease outbreaks,
  as discussed in Farrington et al. (2003) <https://doi.org/10.1093/biostatistics/4.2.279>.
authors:
- family-names: Azam
  given-names: James M.
  email: james.azam@lshtm.ac.uk
  orcid: https://orcid.org/0000-0001-5782-7330
- family-names: Funk
  given-names: Sebastian
  email: sebastian.funk@lshtm.ac.uk
  orcid: https://orcid.org/0000-0002-2842-3406
- family-names: Finger
  given-names: Flavio
  email: flavio.finger@epicentre.msf.org
  orcid: https://orcid.org/0000-0002-8613-5170
repository: https://CRAN.R-project.org/package=epichains
repository-code: https://github.com/epiverse-trace/epichains
url: https://epiverse-trace.github.io/epichains/
contact:
- family-names: Azam
  given-names: James M.
  email: james.azam@lshtm.ac.uk
  orcid: https://orcid.org/0000-0001-5782-7330
keywords:
- branching-processes
- epidemic-dynamics
- epidemic-modelling
- epidemic-simulations
- epidemiology
- epidemiology-models
- outbreak-simulator
- r-package
- r-stats
- transmission-chain
- transmission-chain-reconstruction
references:
- type: software
  title: 'R: A Language and Environment for Statistical Computing'
  notes: Depends
  url: https://www.R-project.org/
  authors:
  - name: R Core Team
  institution:
    name: R Foundation for Statistical Computing
    address: Vienna, Austria
  year: '2025'
  version: '>= 3.6.0'
- type: software
  title: checkmate
  abstract: 'checkmate: Fast and Versatile Argument Checks'
  notes: Imports
  url: https://mllg.github.io/checkmate/
  repository: https://CRAN.R-project.org/package=checkmate
  authors:
  - family-names: Lang
    given-names: Michel
    email: michellang@gmail.com
    orcid: https://orcid.org/0000-0001-9754-0393
  year: '2025'
  doi: 10.32614/CRAN.package.checkmate
- type: software
  title: stats
  abstract: 'R: A Language and Environment for Statistical Computing'
  notes: Imports
  authors:
  - name: R Core Team
  institution:
    name: R Foundation for Statistical Computing
    address: Vienna, Austria
  year: '2025'
- type: software
  title: utils
  abstract: 'R: A Language and Environment for Statistical Computing'
  notes: Imports
  authors:
  - name: R Core Team
  institution:
    name: R Foundation for Statistical Computing
    address: Vienna, Austria
  year: '2025'
- type: software
  title: bookdown
  abstract: 'bookdown: Authoring Books and Technical Documents with R Markdown'
  notes: Suggests
  url: https://pkgs.rstudio.com/bookdown/
  repository: https://CRAN.R-project.org/package=bookdown
  authors:
  - family-names: Xie
    given-names: Yihui
    email: xie@yihui.name
    orcid: https://orcid.org/0000-0003-0645-5666
  year: '2025'
  doi: 10.32614/CRAN.package.bookdown
- type: software
  title: dplyr
  abstract: 'dplyr: A Grammar of Data Manipulation'
  notes: Suggests
  url: https://dplyr.tidyverse.org
  repository: https://CRAN.R-project.org/package=dplyr
  authors:
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
    orcid: https://orcid.org/0000-0003-4757-117X
  - family-names: François
    given-names: Romain
    orcid: https://orcid.org/0000-0002-2444-4226
  - family-names: Henry
    given-names: Lionel
  - family-names: Müller
    given-names: Kirill
    orcid: https://orcid.org/0000-0002-1416-3412
  - family-names: Vaughan
    given-names: Davis
    email: davis@posit.co
    orcid: https://orcid.org/0000-0003-4777-038X
  year: '2025'
  doi: 10.32614/CRAN.package.dplyr
- type: software
  title: epicontacts
  abstract: 'epicontacts: Handling, Visualisation and Analysis of Epidemiological
    Contacts'
  notes: Suggests
  url: https://www.repidemicsconsortium.org/epicontacts/
  repository: https://CRAN.R-project.org/package=epicontacts
  authors:
  - family-names: Campbell
    given-names: Finlay
    email: finlaycampbell93@gmail.com
  - family-names: Jombart
    given-names: Thibaut
    email: thibautjombart@gmail.com
  - family-names: Randhawa
    given-names: Nistara
    email: nrandhawa@ucdavis.edu
  - family-names: Sudre
    given-names: Bertrand
    email: Bertrand.Sudre@ecdc.europa.eu
  - family-names: Nagraj
    given-names: VP
    email: nagraj@nagraj.net
  - family-names: Crellen
    given-names: Thomas
    email: tc13@sanger.ac.uk
  - family-names: Kamvar
    given-names: Zhian N.
    email: zkamvar@gmail.com
  year: '2025'
  doi: 10.32614/CRAN.package.epicontacts
- type: software
  title: ggplot2
  abstract: 'ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics'
  notes: Suggests
  url: https://ggplot2.tidyverse.org
  repository: https://CRAN.R-project.org/package=ggplot2
  authors:
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
    orcid: https://orcid.org/0000-0003-4757-117X
  - family-names: Chang
    given-names: Winston
    orcid: https://orcid.org/0000-0002-1576-2126
  - family-names: Henry
    given-names: Lionel
  - family-names: Pedersen
    given-names: Thomas Lin
    email: thomas.pedersen@posit.co
    orcid: https://orcid.org/0000-0002-5147-4711
  - family-names: Takahashi
    given-names: Kohske
  - family-names: Wilke
    given-names: Claus
    orcid: https://orcid.org/0000-0002-7470-9261
  - family-names: Woo
    given-names: Kara
    orcid: https://orcid.org/0000-0002-5125-4188
  - family-names: Yutani
    given-names: Hiroaki
    orcid: https://orcid.org/0000-0002-3385-7233
  - family-names: Dunnington
    given-names: Dewey
    orcid: https://orcid.org/0000-0002-9415-4582
  - family-names: Brand
    given-names: Teun
    name-particle: van den
    orcid: https://orcid.org/0000-0002-9335-7468
  year: '2025'
  doi: 10.32614/CRAN.package.ggplot2
- type: software
  title: knitr
  abstract: 'knitr: A General-Purpose Package for Dynamic Report Generation in R'
  notes: Suggests
  url: https://yihui.org/knitr/
  repository: https://CRAN.R-project.org/package=knitr
  authors:
  - family-names: Xie
    given-names: Yihui
    email: xie@yihui.name
    orcid: https://orcid.org/0000-0003-0645-5666
  year: '2025'
  doi: 10.32614/CRAN.package.knitr
- type: software
  title: lubridate
  abstract: 'lubridate: Make Dealing with Dates a Little Easier'
  notes: Suggests
  url: https://lubridate.tidyverse.org
  repository: https://CRAN.R-project.org/package=lubridate
  authors:
  - family-names: Spinu
    given-names: Vitalie
    email: spinuvit@gmail.com
  - family-names: Grolemund
    given-names: Garrett
  - family-names: Wickham
    given-names: Hadley
  year: '2025'
  doi: 10.32614/CRAN.package.lubridate
- type: software
  title: rmarkdown
  abstract: 'rmarkdown: Dynamic Documents for R'
  notes: Suggests
  url: https://pkgs.rstudio.com/rmarkdown/
  repository: https://CRAN.R-project.org/package=rmarkdown
  authors:
  - family-names: Allaire
    given-names: JJ
    email: jj@posit.co
  - family-names: Xie
    given-names: Yihui
    email: xie@yihui.name
    orcid: https://orcid.org/0000-0003-0645-5666
  - family-names: Dervieux
    given-names: Christophe
    email: cderv@posit.co
    orcid: https://orcid.org/0000-0003-4474-2498
  - family-names: McPherson
    given-names: Jonathan
    email: jonathan@posit.co
  - family-names: Luraschi
    given-names: Javier
  - family-names: Ushey
    given-names: Kevin
    email: kevin@posit.co
  - family-names: Atkins
    given-names: Aron
    email: aron@posit.co
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
  - family-names: Cheng
    given-names: Joe
    email: joe@posit.co
  - family-names: Chang
    given-names: Winston
    email: winston@posit.co
  - family-names: Iannone
    given-names: Richard
    email: rich@posit.co
    orcid: https://orcid.org/0000-0003-3925-190X
  year: '2025'
  doi: 10.32614/CRAN.package.rmarkdown
- type: software
  title: spelling
  abstract: 'spelling: Tools for Spell Checking in R'
  notes: Suggests
  url: https://ropensci.r-universe.dev/spelling
  repository: https://CRAN.R-project.org/package=spelling
  authors:
  - family-names: Ooms
    given-names: Jeroen
    email: jeroenooms@gmail.com
    orcid: https://orcid.org/0000-0002-4035-0289
  - family-names: Hester
    given-names: Jim
    email: james.hester@rstudio.com
  year: '2025'
  doi: 10.32614/CRAN.package.spelling
- type: software
  title: testthat
  abstract: 'testthat: Unit Testing for R'
  notes: Suggests
  url: https://testthat.r-lib.org
  repository: https://CRAN.R-project.org/package=testthat
  authors:
  - family-names: Wickham
    given-names: Hadley
    email: hadley@posit.co
  year: '2025'
  doi: 10.32614/CRAN.package.testthat
- type: software
  title: truncdist
  abstract: 'truncdist: Truncated Random Variables'
  notes: Suggests
  repository: https://CRAN.R-project.org/package=truncdist
  authors:
  - family-names: Novomestky
    given-names: Frederick
    email: fn334@nyu.edu
  - family-names: Nadarajah
    given-names: Saralees
    email: saralees.nadarajah@manchester.ac.uk
  year: '2025'
  doi: 10.32614/CRAN.package.truncdist

GitHub Events

Issues and Pull Requests

Last synced: 10 months ago

Packages