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.

To install the latest version of epydemix from PyPI, use the following command in a terminal or command prompt—ideally within a virtual environment to avoid dependency conflicts:

pip install epydemix

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

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"])

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

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.

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.

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

@article{gozzi2025epydemix,
	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},
	title = {Epydemix: An open-source Python package for epidemic modeling with integrated approximate Bayesian calibration},
	elocation-id = {2025.05.07.25327151},
	year = {2025},
	doi = {10.1101/2025.05.07.25327151},
	publisher = {Cold Spring Harbor Laboratory Press},
	URL = {https://www.medrxiv.org/content/early/2025/05/08/2025.05.07.25327151},
	eprint = {https://www.medrxiv.org/content/early/2025/05/08/2025.05.07.25327151.full.pdf},
	journal = {medRxiv}
}

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

For questions or issues, please open an issue on GitHub or contact the maintainer at [email protected].