{"id":22151645,"url":"https://github.com/epiverse-trace/epichains","last_synced_at":"2025-07-26T05:31:29.397Z","repository":{"id":170103824,"uuid":"635510111","full_name":"epiverse-trace/epichains","owner":"epiverse-trace","description":"Methods for simulating and analysing the sizes and lengths of infectious disease transmission chains from branching process models","archived":false,"fork":false,"pushed_at":"2025-06-24T14:57:53.000Z","size":10376,"stargazers_count":6,"open_issues_count":29,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-07-25T23:20:09.233Z","etag":null,"topics":["branching-processes","epidemic-dynamics","epidemic-modelling","epidemic-simulations","epidemiology","epidemiology-models","outbreak-simulator","r-package","r-stats","transmission-chain","transmission-chain-reconstruction"],"latest_commit_sha":null,"homepage":"https://epiverse-trace.github.io/epichains/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"epiverse-trace/bpmodels","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/epiverse-trace.png","metadata":{"files":{"readme":"README.Rmd","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-02T21:12:43.000Z","updated_at":"2025-05-20T16:28:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"8e93e52f-cd81-4ca5-98c5-7823cea9a2f5","html_url":"https://github.com/epiverse-trace/epichains","commit_stats":null,"previous_names":["epiverse-trace/epichains"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/epiverse-trace/epichains","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiverse-trace%2Fepichains","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiverse-trace%2Fepichains/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiverse-trace%2Fepichains/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiverse-trace%2Fepichains/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/epiverse-trace","download_url":"https://codeload.github.com/epiverse-trace/epichains/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/epiverse-trace%2Fepichains/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267120176,"owners_count":24039106,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-26T02:00:08.937Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["branching-processes","epidemic-dynamics","epidemic-modelling","epidemic-simulations","epidemiology","epidemiology-models","outbreak-simulator","r-package","r-stats","transmission-chain","transmission-chain-reconstruction"],"created_at":"2024-12-02T00:34:56.868Z","updated_at":"2025-07-26T05:31:29.383Z","avatar_url":"https://github.com/epiverse-trace.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\nbibliography: vignettes/references.json\nlink-citations: true\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file. --\u003e\n\u003c!-- The code to render this README is stored in .github/workflows/render-readme.yaml --\u003e\n\u003c!-- Variables marked with double curly braces will be transformed beforehand: --\u003e\n\u003c!-- `packagename` is extracted from the DESCRIPTION file --\u003e\n\u003c!-- `gh_repo` is extracted via a special environment variable in GitHub Actions --\u003e\n\n```{r setup, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = file.path(\"man\", \"figures\", \"README-\"),\n  out.width = \"100%\",\n  echo = TRUE\n)\n```\n\n# _{{ packagename }}_: Methods for simulating and analysing the size and length of transmission chains from branching process models \u003cimg src=\"man/figures/logo.svg\" align=\"right\" height=\"130\" /\u003e\n\n\u003c!-- badges: start --\u003e\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![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)\n[![Codecov test coverage](https://codecov.io/gh/{{ gh_repo }}/branch/main/graph/badge.svg)](https://app.codecov.io/gh/{{ gh_repo }}?branch=main)\n[![Lifecycle:\nexperimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)\n[![CRAN status](https://www.r-pkg.org/badges/version/epichains)](https://CRAN.R-project.org/package=epichains)\n[![month-download](https://cranlogs.r-pkg.org/badges/epichains)](https://cran.r-project.org/package=epichains)\n[![total-download](https://cranlogs.r-pkg.org/badges/grand-total/epichains)](https://cran.r-project.org/package=epichains)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13945039.svg)](https://doi.org/10.5281/zenodo.13945039)\n\u003c!-- badges: end --\u003e\n\n_{{ packagename }}_ is an R package to simulate, analyse, and visualize the size \nand length of branching processes with a given offspring distribution. These \nmodels are often used in infectious disease epidemiology, where the chains represent chains of\ntransmission, and the offspring distribution represents the distribution of \nsecondary infections caused by an infected individual. \n\n_{{ packagename }}_ re-implements [bpmodels](https://github.com/epiforecasts/bpmodels/)\nby providing bespoke functions and data structures that allow easy\nmanipulation 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).\n\n_{{ 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/).\n\n## Installation\n\nInstall the released version of the package:\n\n```{r install_cran, include=TRUE,eval=FALSE}\ninstall.packages(\"{{ packagename }}\")\n```\n\nThe latest development version of the _{{ packagename }}_ package can be installed via\n\n```{r install_with_remotes, include=TRUE,eval=FALSE}\n# check whether {remotes} is installed\nif (!require(\"remotes\")) install.packages(\"remotes\")\nremotes::install_github(\"{{ gh_repo }}\")\n```\n\nIf this fails, try using the `pak` R package via\n\n```{r install_with_pak, include=TRUE,eval=FALSE}\n# check whether {pak} is installed\nif (!require(\"pak\")) install.packages(\"pak\")\npak::pak(\"{{ gh_repo }}\")\n```\n\nIf 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.\n\nTo load the package, use\n\n```{r load_pkg, eval=TRUE}\nlibrary(\"{{ packagename }}\")\n```\n\n## Quick start\n\n_{{ packagename }}_ provides three main functions:\n\n* `simulate_chains()`: simulates transmission chains using a simple\nbranching process model that accepts an index number of cases that seed\nthe outbreak, a distribution of offspring per case, and a chain statistic\nto track (size or length/duration). It optionally accepts other population\nrelated inputs such as the population size (defaults to Inf) and percentage\nof the population initially immune (defaults to 0). This function returns\nan object with columns that track information on who infected whom, the\ngeneration of infection and, if a generation time function is specified, the\ntime of infection.\n\n* `simulate_chain_stats()`: provides a performant version of `simulate_chains()`\nthat only tracks and return a vector of realized chain sizes or\nlengths/durations for each index case without details of the infection tree.\n\n* `likelihood()`: calculates the loglikelihood (or likelihood, depending\non the value of `log`) of observing a vector of transmission chain sizes or\nlengths.\n\nThe objects returned by the `simulate_*()` functions can be summarised with\n`summary()`. Running `summary()` on the output of `simulate_chains()` will\nreturn the same output as `simulate_chain_stats()` using the same inputs.\n\nObjects returned from `simulate_chains()` can be aggregated into a\n`\u003cdata.frame\u003e` of cases per time or generation\nwith the function `aggregate()`.\n\nThe simulated `\u003cepichains\u003e` object can be plotted in various ways using\n`plot()`. See the plotting section in `vignette(\"epichains\")` for two\nuse cases.\n\n### Simulation\n\nFor the simulation functionality, let's look at a simple example where we\nsimulate a transmission chain with $20$ index cases, a constant generation time\nof $3$, and a poisson offspring distribution with mean $1$. We are tracking the\nchain \"size\" statistic and will cap all chain sizes at $25$ cases. We will then\nlook at the summary of the simulation, and aggregate it into cases per\ngeneration.\n```{r simulate_chains, eval=TRUE}\nset.seed(32)\n# Simulate chains\nsim_chains \u003c- simulate_chains(\n  n_chains = 20,\n  statistic = \"size\",\n  offspring_dist = rpois,\n  stat_threshold = 25,\n  generation_time = function(n) {\n    rep(3, n)\n  }, # constant generation time of 3\n  lambda = 1 # mean of the Poisson distribution\n)\n# View the head of the simulation\nhead(sim_chains)\n\n# Summarise the simulation\nsummary(sim_chains)\n\n# Aggregate the simulation into cases per generation\nchains_agregegated \u003c- aggregate(sim_chains, by = \"generation\")\n\n# view the time series of cases per generation\nchains_agregegated\n```\n\n### Inference\n\nLet's look at the following example where we estimate the log-likelihood of\nobserving a hypothetical `chain_lengths` dataset.\n```{r likelihood_example, eval=TRUE}\nset.seed(32)\n# randomly generate 20 chain lengths between 1 to 40\nchain_lengths \u003c- sample(1:40, 20, replace = TRUE)\nchain_lengths\n\n# estimate loglikelihood of the observed chain sizes\nlikelihood_eg \u003c- likelihood(\n  chains = chain_lengths,\n  statistic = \"length\",\n  offspring_dist = rpois,\n  lambda = 0.99\n)\n# Print the estimate\nlikelihood_eg\n```\n\nEach of the listed functionalities is demonstrated in detail\nin the [\"Getting Started\" vignette](https://epiverse-trace.github.io/epichains/articles/epichains.html).\n\n## Package websites\n\nThe 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/).\n\n## Package vignettes\n\nThe theory behind the models provided here can be\nfound in the [theory vignette](https://epiverse-trace.github.io/epichains/articles/theoretical_background.html).\n\nWe have also collated a bibliography of branching process applications in \nepidemiology. These can be found in the [literature vignette](https://epiverse-trace.github.io/epichains/articles/branching_process_literature.html).\n\nSpecific use cases of _{{ packagename }}_ can be found in \nthe [online documentation as package vignettes](https://epiverse-trace.github.io/epichains/), under \"Articles\".\n\n## Related R packages\n\nAs far as we know, below are the existing R packages for simulating branching\nprocesses and transmission chains. \n\n\u003cdetails\u003e\n\n\u003csummary\u003eClick to expand\u003c/summary\u003e\n\n* [bpmodels](https://github.com/epiforecasts/bpmodels/): provides methods \nfor analysing the size and length of transmission chains from branching \nprocess models. `{epichains}` supersedes `{bpmodels}`, which has been retired.\n\n* [ringbp](https://github.com/epiforecasts/ringbp): a branching process \nmodel, parameterised to the 2019-nCoV outbreak, and used to quantify \nthe potential effectiveness of contact tracing and isolation of cases.\n\n* [covidhm](https://github.com/biouea/covidhm): code for simulating \nCOVID-19 dynamics in a range of scenarios across a real-world social \nnetwork. The model is conceptually based on `{ringbp}`.\n\n* [epicontacts](https://github.com/reconhub/epicontacts): provides methods\nfor handling, analysing, and visualizing transmission chains and contact-tracing \ndata/linelists.\n\n* [simulist](https://epiverse-trace.github.io/simulist/): uses a branching\nprocess model to simulate individual-level infectious disease outbreak data,\nincluding line lists and contact tracing data. This package is part of the\nEpiverse-TRACE Initiative.\n\n* [superspreading](https://epiverse-trace.github.io/superspreading/): provides\na set of functions to estimate and understand individual-level variation in\ntransmission of infectious diseases from data on secondary cases. These are\nuseful for understanding the role of superspreading in the spread of infectious\ndiseases and for informing public health interventions.\n\n* [earlyR](https://github.com/reconhub/earlyR): estimates the reproduction \nnumber (R), in the early stages of an outbreak. The model requires a \nspecified serial interval distribution, characterised by the mean and \nstandard deviation of the (Gamma) distribution, and data on daily disease \nincidence, including only confirmed and probable cases.\n\n* [projections](https://github.com/reconhub/projections): uses data on daily \nincidence, the serial interval (time between onsets of infectors and \ninfectees) and the reproduction number to simulate plausible epidemic \ntrajectories and project future incidence. It relies on a branching process \nwhere daily incidence follows a Poisson or a Negative Binomial distribution\ngoverned by a force of infection.\n\n* [simulacr](https://github.com/reconhub/simulacr): simulates outbreaks \nfor specified values of reproduction number, incubation period, duration \nof infectiousness, and optionally reporting delays. Outputs a linelist \nstored as a `data.frame` with the class `outbreak`, including information\non transmission chains; the output can be converted to `\u003cepicontacts\u003e`\nobjects for visualisation.\n\n* [outbreakr2](https://github.com/reconhub/outbreaker2): a Bayesian \nframework for integrating epidemiological and genetic data to reconstruct \ntransmission trees of densely sampled outbreaks. It re-implements, \ngeneralises and replaces the model of outbreaker, and uses a modular\napproach which enables fine customisation of priors, likelihoods \nand parameter movements.\n\n* [o2geosocial](https://github.com/alxsrobert/o2geosocial): integrates\ngeographical and social contact data to reconstruct transmission chains. \nIt combines the age group, location, onset date and genotype of cases \nto infer their import status, and their likely infector.\n\n* [nosoi](https://github.com/slequime/nosoi): simulates agent-based \ntransmission chains by taking into account the influence of multiple \nvariables on the transmission process (e.g. dual-host systems \n(such as arboviruses), within-host viral dynamics, transportation, \npopulation structure), alone or taken together, to create complex \nbut relatively intuitive epidemiological simulations.\n\n* [TransPhylo](https://xavierdidelot.github.io/TransPhylo/index.html):\nreconstructs infectious disease transmission using genomic data.\n\u003c/details\u003e\n\n## Reporting bugs \n\nTo report a bug please open an [issue](https://github.com/epiverse-trace/epichains/issues/new/choose).\n\n## Contribute\n\nContributions to {epichains} are welcomed. Please follow the [package contributing guide](https://github.com/epiverse-trace/.github/blob/main/CONTRIBUTING.md).\n\n## Code of conduct\n\nPlease 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). \nBy contributing to this project, you agree to abide by its terms.\n\n## Citing this package\n\n```{r citation, message=FALSE, warning=FALSE}\ncitation(\"epichains\")\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepiverse-trace%2Fepichains","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fepiverse-trace%2Fepichains","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fepiverse-trace%2Fepichains/lists"}