A Python package for the mathematical modeling of infectious diseases via compartmental models. Originally designed for epidemiologists, epispot can be adapted for almost any type of modeling scenario.


The epispot package currently only supports compartmental models, though
we plan to expand the package to work for stochastic agent-based and spatial
models as well. Currently, epispot offers the following:

  • Quick compilation of compartmental models with the following compartments:
    • Susceptible
    • Infected
    • Recovered
    • Removed
    • Exposed
    • Dead
    • Critical
    • Hospitalized
  • Custom-defined compartments for research
  • Built-in graphing and visualization engine
    • Plots model predictions interactively
    • Creates comparisons between models

Due to its diverse range of features, epispot can be used for both research
and experimental modeling. If you would like to add more modeling support, please
see the contributing section.


The epispot package can be installed from PyPI, Anaconda, or be built from the
source. Before reading this guide, it is important to note that there are actually
two different versions of the epispot package. The first of which is the
master package, which will always have a version tag like v#.#.#.
This package is used to release stable versions of epispot. However, during
important events, like the COVID-19 pandemic, the nightly package is used to
publish new features quickly. However, these versions may be unstable.


This is the easiest way to install epispot. Fire up a terminal and type:

pip install epispot

For the nightly version, use

pip install epispot-nightly

Pip will ask you to install numpy and matplotlib as dependencies if you
haven't already. Additionally, it may require you to install fire for the CLI.
These can be installed beforehand with:

pip install numpy
pip install matplotlib
pip install fire


Please note that the nightly version is not available on the conda
package registry. However, it is still possible to install on conda-based
systems with

pip install epispot-nightly

which uses pip from Anaconda to install it.

The standard version of epispot is published to conda using the
conda-forge channel. To install, please use:

conda config --add channels conda-forge
conda install -c conda-forge epispot

Building from the source

This is the hardest way to install epispot and it is recommended that you
use either PyPI or Anaconda to install it instead. However, if you would like
to contribute to the repository, this will be particularly useful.

Clone the repository with:

git clone https://github.com/epispot/epispot  # clone epispot/epispot
cd epispot  # open project
pip install -r requirements.txt  # install package requirements
pip install -r bin/requirements.txt  # Install CLI requirements

Then, build the nightly version with

python setup-nightly.py install

For the stable version, first checkout a
release branch with something like:

git checkout v2.1.1
python setup.py install

Quick Demo

Installing epispot from pip and then compiling a simple SIR model in less than
40 seconds.



The documentation for the epispot package is generated automatically from
the Python source code using Pdoc3. You can view the
documentation for both the nightly and stable builds of epispot

At first, the documentation may seem a bit hard to understand, especially
if you're new to epidemiology. That's why epispot has put together an entire
manual describing some basic concepts you'll need to know to master
epispot. You can view it here.
The GitHub source is available here.


The GitHub repository has a vast array of samples using epispot. You can start
by checking out the explorables/ directory. In it, you'll find many programs
designed for helping you get started with epispot and some hands-on examples.