Epydemix, the ABC of Epidemics

Documentation | Website | Tutorials

Epydemix is a Python package for epidemic modeling. It provides tools to create, calibrate, and analyze epidemic models, allowing users to simulate the spread of infectious diseases using different compartmental models, contact layers, and calibration techniques. It is designed to be used in conjunction with the epydemix-data package to load population and contact matrix data.

Installation

You can install epydemix from either PyPI or conda-forge. We recommend using a virtual environment (via conda, mamba, or venv) to avoid dependency conflicts.

Install from PyPI

pip install epydemix

Add pip install epydemix[numba] for a JIT-compiled speedup on the stochastic simulation hot path (optional — epydemix runs fine without it, just slower).

Install from Conda (conda-forge)

conda install -c conda-forge epydemix

To create a fresh environment and install Epydemix:

conda create -n epydemix-env -c conda-forge epydemix
conda activate epydemix-env

Quick Start

Once installed, you can start using epydemix in your Python scripts or Jupyter notebooks. Below an example to get started.

Example: Creating and running a simple SIR model

from epydemix import EpiModel
from epydemix.visualization import plot_quantiles

# Define a basic SIR model
model = EpiModel(
    name="SIR Model",
    compartments=["S", "I", "R"],  # Susceptible, Infected, Recovered
)

# Add transitions: infection and recovery
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 simulations
results = model.run_simulations(
    start_date="2024-01-01",
    end_date="2024-04-10",
    Nsim=100,
)

# Extract and plot quantiles of compartment counts
df_quantiles = results.get_quantiles_compartments()
plot_quantiles(df_quantiles, columns=["I_total", "S_total", "R_total"])

Tutorials

We provide a series of tutorials to help you get started with epydemix.

• Tutorial 1: An Introduction to Model Definition and Simulation
• Tutorial 2: Using Population Data from Epydemix Data
• Tutorial 3: Modeling Non-pharmaceutical Interventions
• Tutorial 4: Model Calibration with ABC (Part 1)
• Tutorial 5: Model Calibration with ABC (Part 2)
• Tutorial 6: Advanced Modeling Features
• Tutorial 7: COVID-19 Case Study
• Tutorial 8: Modeling Multiple Strains
• Tutorial 9: Modeling Vaccinations
• Tutorial 10: Speeding up Simulations and Calibration with Multiprocessing
• Tutorial 11: Using Epistorm-Mix Contact Matrices (sex and race/ethnicity)
• Tutorial 12: Predefined Epidemic Models — Backbones and Modular Extensions

You can run all tutorials directly in Google Colab — just open any notebook in the tutorials folder and click the “Open in Colab” button at the top.

Epydemix Data

epydemix also provides access to a wealth of real-world population and contact matrix data through the epydemix_data module. This dataset allows you to load predefined population structures, including age distribution and contact matrices for over 400 locations globally. You can use this data to create realistic simulations of disease spread in different geographies.

Example of Loading Population Data

from epydemix.population import load_epydemix_population

# Load population data for the United States using the Mistry 2021 contact matrix
population = load_epydemix_population(
    population_name="United_States",
    contacts_source="mistry_2021",
    layers=["home", "work", "school", "community"],
)

# Assign the loaded population to the epidemic model
model.set_population(population)

Epydemix can load data either locally from a folder or directly from online sources, making it easy to simulate a wide range of epidemic models on real population data.

For more information about the available population and contact matrices and to download the data, please visit the dedicated repository.

Agent Framework

Epydemix also ships a CLI for driving simulations programmatically — designed for use by LLM agents and automation pipelines, but equally usable from the shell. It covers discovery, config validation, running, and inspecting results end-to-end. See AGENT.md on the agent-framework branch for the full contract and worked examples.

Citation

The paper describing the development of Epydemix is available here. To reference our work, please use the following citation:

@article{gozzi2025epydemix,
  title={Epydemix: An open-source Python package for epidemic modeling with integrated approximate Bayesian calibration},
  author={Gozzi, Nicol{\'o} and Chinazzi, Matteo and Davis, Jessica T and Gioannini, Corrado and Rossi, Luca and Ajelli, Marco and Perra, Nicola and Vespignani, Alessandro},
  journal={PLOS Computational Biology},
  volume={21},
  number={11},
  pages={e1013735},
  year={2025},
  publisher={Public Library of Science San Francisco, CA USA}
}

License

This project is licensed under the GPL-3.0 License. See the LICENSE file for more details.

Contributors

Contributions are welcome! Please read our Contributing Guide and open issues or pull requests on GitHub. For questions and general discussion, visit our GitHub Discussions.

Changelog

See the CHANGELOG file for details on past releases and updates.

Contact

For questions or issues, please open an issue on GitHub or contact the maintainer at epydemix@isi.it.