epydemix

epydemix is a Python package for epidemic modeling. Define a compartmental model in a few lines, run stochastic simulations on real-world populations and contact patterns, and calibrate the model to data with Approximate Bayesian Computation (ABC).

Website · GitHub · Paper · PyPI

  • Any compartmental model: SIR, SEIR and friends are built in, and you can define your own compartments, transitions and transition rules.

  • Real populations: age-structured populations and contact matrices (home, school, work, community) for more than 400 locations, from epydemix-data.

  • Interventions: reduce contacts in a setting or change a parameter over a period.

  • Calibration: ABC-SMC, rejection and top-fraction sampling, then projections from the posterior.

  • Plots: quantile bands, trajectories, posteriors, contact matrices.

Installation

pip install epydemix

or, with conda:

conda install -c conda-forge epydemix

Requires Python 3.8 or later. For faster simulations, pip install "epydemix[numba]" adds an optional JIT-compiled speedup; epydemix runs fine without it, just slower.

Quickstart

from epydemix import EpiModel
from epydemix.visualization import plot_quantiles

# Define a basic SIR model
model = EpiModel(name="SIR Model", compartments=["S", "I", "R"])
model.add_transition(source="S", target="I", params=(0.3, "I"), kind="mediated")
model.add_transition(source="I", target="R", params=0.1, kind="spontaneous")

# Run 100 stochastic simulations
results = model.run_simulations(start_date="2024-01-01", end_date="2024-04-10", Nsim=100)

# Median and 90% interval of each compartment over time
df_quantiles = results.get_quantiles_compartments()
plot_quantiles(df_quantiles, columns=["I_total", "S_total", "R_total"])
Median and 90% interval of S, I and R over time

To try it without installing anything, open the first tutorial in Colab.

Contents

User guide

  • Building a model: compartments, transitions, parameters that vary in time or by age group, predefined models, custom transition rules

  • Populations and contacts: loading a real population and its contact matrices, or building your own

  • Running simulations: running simulations, initial conditions, reproducibility and getting the results out

  • Interventions: reducing contacts and changing parameters over a period

  • Calibration: fitting a model to data with ABC and projecting forward

  • Plotting: the built-in plots

Learn

  • Tutorials: twelve worked notebooks, from a first model to a COVID-19 case study

Reference