kapawlak / pydemic

a python driver for epidemic modeling and inference

pydemic: a python driver for epidemic modeling and inference

The pydemic package comprises a set of tools for modeling the population dynamics of an epidemic and calibrating models to data. pydemic provides implementations of various types of compartmental models, including not only SIR/SEIR models but also the more general Kermack and McKendrick age-of-infection models, which allow transitions between disease states to be described by arbitrary time-delay distributions. More generally, pydemic provides a framework for users to specify custom epidemic models by extending the base classes for reaction-based and non-Markovian simulations.

To evaluate a model's applicability to an actual epidemic, its predictions (e.g., for the rate of new cases or deaths) can be compared to real world data. Parameter inference—the task of calibrating a model's input parameters via likelihood estimation—is supported by pydemic's interfaces to the Markov chain Monte Carlo package emcee and SciPy's global optimization routines.

pydemic provides simple parsers for COVID-19 case data sourced from the COVID Tracking Project and the New York Times. Pull requests that contribute new, robust parsers are welcome!

As an example, we consider our SEIR++ model, which treats the dynamics of infection and subsequent hospitalization. The model includes a large set of parameters that specify the distribution of various time delays (e.g., for the spread of infection, symptom onset, and hospitalization), the severity of infection (i.e., the likelihood of progressing from one stage of the disease to the next), and the time-dependent degree to which interventions mitigate the spread of the disease. We calibrate these parameters by comparing the model's predictions to COVID-19–related hospitalizations and deaths in Illinois. We describe the model and calibration procedure in detail in a recent preprint on the arXiv.

pydemic is in beta. While effort will be made to preserve backwards compatibility with staged deprecation, we cannot guarantee that features will be preserved or that interfaces will not change. However, we will attempt to ensure that backwards-incompatible changes are demarcated by incrementing the major version.

pydemic is fully documented and is licensed under the liberal MIT license. See the docs for citation info.

Getting started

pydemic is available on PyPI and can be installed with pip:

pip install pydemic

Several examples exhibit how to use pydemic:

• The SEIR++ tutorial notebook demonstrates how to set up a simulation object, specify parameters, run the simulation, and visualize the results.
• An example of calibration illustrates how to set up likelihood estimation, run Markov chain Monte Carlo, and plot the posterior probability distribution of model parameters, using the SEIR++ model and public Illinois data from the COVID Tracking Project as an example.