EpiBranch.jl
EpiBranch.jl is a Julia package for asking how an outbreak grows from a few introduced cases, and what isolation, contact tracing or vaccination would do to it. It simulates outbreaks as branching processes, calculates exact results where they exist (extinction probability, the distribution of chain sizes, the share of transmission caused by the most infectious cases), and fits these models to outbreak data.
With it you can:
simulate outbreaks under isolation, contact tracing and quarantine, ring or mass vaccination and post-exposure prophylaxis, and estimate how often these contain an outbreak;
give cases an incubation period, an age, or a clinical course (symptom onset, reporting, hospital admission, recovery or death);
produce line lists and contact tables shaped like those from a real outbreak;
estimate R and the dispersion k from offspring counts, chain sizes or chain lengths, by maximum likelihood or in a Bayesian model;
model transmission between types of host (for example age groups), over contact networks or within households, the last two through companion packages.
If you are new to Julia, Julia for R users explains the syntax used in these pages, and the Glossary defines the terms.
Where it comes from
EpiBranch brings together what five R packages do:
ringbp: whether isolation and contact tracing contain an outbreak;
simulist: simulated line lists and contact tracing data;
epichains: transmission chain sizes and lengths, and their likelihoods;
superspreading: exact results for overdispersed transmission;
pepbp: post-exposure prophylaxis.
To these it adds multi-type transmission (for example between age groups, or between hosts who transmit more and hosts who transmit less), and one set of functions that works on the same model for simulation, exact calculation and likelihood.
How a case transmits
Each case draws a number of potential secondary cases from the offspring distribution: the people it would infect if nothing intervened. Each potential infection then gets a time from the generation time distribution. Isolation, quarantine, vaccination, a contact's reduced susceptibility or a finite population can each prevent it, and the infection happens only if none of them does (survival analysis calls these competing risks). With none of these in the model, every potential secondary case is infected; the mean of the offspring distribution is then R.
Generation times and the number of secondary cases
By default each generation time is drawn independently of how many secondary cases the case has. A generation time that depends on the case, for example on its own incubation period as in incubation_linked_generation_time, is also possible.
Design describes how the package is organised, and Extending EpiBranch shows how to add your own intervention, and Adding a transmission model how to add a process of your own.
Quick start
This estimates how often isolation and contact tracing contain an outbreak of a pathogen with R = 2.5 and strong superspreading (k = 0.16). Times are in days.
using EpiBranch
using Distributions
using StableRNGs
# Symptomatic cases isolate on average 2 days after onset, for 7 days
iso = Isolation(onset_to_isolation_delay = Exponential(2.0), duration = 7.0)
# Each contact of an isolated case is traced with probability 0.5, on average
# 1.5 days after the case isolates, and quarantined for 7 days
ct = ContactTracing(
probability = 0.5, isolation_to_trace_delay = Exponential(1.5),
action = Quarantine(duration = 7.0)
)
# R = 2.5, dispersion k = 0.16. Generation time LogNormal with mean 1.6 and
# sd 0.5 on the log scale (a mean of about 5.6 days); incubation period
# LogNormal(1.5, 0.5) (a mean of about 5.1 days).
model = ModelSpec(BranchingProcess(NegBin(2.5, 0.16), LogNormal(1.6, 0.5));
interventions = [iso, ct],
attributes = clinical_presentation(incubation_period = LogNormal(1.5, 0.5)),
)
rng = StableRNG(42) # a fixed random seed, like set.seed() in R
results = simulate(model, 500; max_cases = 5000, rng = rng)
containment_probability(results)0.92This simulates 500 outbreaks, each starting from one index case and stopped once it reaches 5000 cases. The containment probability is the proportion in which transmission stopped before that cap. The Getting started tutorial goes through each step.
Installation
The installation guide shows how to install EpiBranch and the household and network packages.