Package epispot
epispot v2
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.
Features
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.
Installation
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.
PyPI
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
Anaconda
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
Using epispot in a Python REPL to create the well-known SIR model (in less than three lines of code):
Documentation
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 here.
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.
Usage/Examples
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.
Badges
Statuses
Pipeline | Status |
---|---|
Travis CI | |
CodeCov | |
PyPI main | |
PyPI nightly | |
Security |
Feedback
If you have any feedback, please
- Create a discussion on GitHub
- Create an issue if you've found a bug
- Submit a PR if you want to add a new feature
- Contact a CODEOWNER
Contributing
Contributions are always welcome! See CONTRIBUTING.md for instructions on how to get started, including environment setup and instructions to build from the source. Please note also that epispot has many guides dedicated to certain types of contributions. Please see
- DOCUMENTATION.md for documentation additions
- SECURITY.md for epispot's security policy
Citation
If you plan on using epispot in your project, please abide by the GPLv3 license. This requires that any changes you make to epispot must be open-sourced under the GPLv3 license as well and that you give credit to the author, which you can do by citing the project in your research, linking back to the original repository, or mentioning the author @quantum9innovation.
For research, you can also use epispot's DOI to reference the project:
The recommended citation for epispot is:
quantum9innovation (2021, April 2). epispot/epispot: (Version 2.1.0). Zenodo. http://doi.org/10.5281/zenodo.4624423
Related Work
There are many related projects to epispot, although we believe that epispot has greater extensibility than many of these other projects. Additionally, epispot is quite portable (graphs can be used as web components/displayed as images/etc.). However, below we would like to acknowledge a few projects that may be better suited to certain use cases:
- EpiJS by @Quantalabs is a disease modeling package for Javascript
- covasim by the Institute for Disease Modeling offers agent-based stochastic models which epispot unfortunately does not support as of yet
- CovsirPhy by @lisphilar offers greater support for loading and analyzing real COVID-19 data, which epispot strives to add soon
Authors
Please see our CODEOWNERS file for authors. Because epispot is an open-source project, different pieces of our code have different authors. However, if citing epispot or using it in another project, you can put @quantum9innovation as the lead author.
Acknowledgements
Idea & Inspiration
The original idea for epispot came from a 3Blue1Brown video on basic infectious disease dynamics and an interactive article in the Washington Post. This in turn inspired the very basic infectious disease dynamics simulated here. However, what finally set the package into motion was a series of articles by Henry Froese, available on Medium here, along with their corresponding interactive notebooks.
Code Development & Maintenance
The epispot project is built on open source code and is itself open-source. The initial core development was fueled by @quantum9innovation and much of the codebase was maintained by @Quantalabs. Additionally, thank you to all of epispot's open-source contributors!
Dependencies
The epispot team also relies on the following open-source projects as dependencies:
- NumPy (GitHub), the fundamental package for scientific computing with Python
- Matplotlib (GitHub), plotting with Python
- Google Fire (Github), a library for automatically generating command line interfaces (CLIs) from absolutely any Python object.
External Code Management Tools
For code maintenance, epispot uses various tools including:
- Coverage.py (PyPI) for code coverage report generation
- Pdoc3 (GitHub) for automatic documentation generation
- GitBook (Website) for documentation hosting
- CodeCov (Website) for code coverage report analysis
- LGTM (Website) for CodeQL analysis
- DeepSource (Website) for static code analysis
- GitLocalize (Website) for localization of documentation
- Zenodo (Website) for automatic DOI & citations
Expand source code
"""
.. include:: ../README.md
<!--
Documentation available at:
https://epispot.github.io/epispot/en/v3.0.0-alpha-3
-->
"""
def _dependency_check():
"""Checks dependencies"""
try:
import numpy
except ImportError: # pragma: no cover
raise ImportError('In order to integrate `epispot` models, '
'`numpy` is a required dependency.\n'
'Install with either:\n'
' $ pip install epispot\n'
' $ conda install epispot')
try:
import matplotlib # lgtm [py/import-and-import-from]
except ImportError: # pragma: no cover
raise ImportError('In order to display plots, `matplotlib` is '
'a required dependency.\n'
'Install with either:\n'
' $ pip install matplotlib\n'
' $ conda install matplotlib')
# imports
import warnings
import random
# dependencies
_dependency_check() # check for uninstalled dependencies
del _dependency_check
import numpy as np
from matplotlib import pyplot as plt
from matplotlib import colors
# local
from . import comps
from . import models
from . import pre
from . import fitters
from . import plots
# helper funcs
def _check_versions():
"""Checks for version conflicts"""
pass
def _check_install(): # pragma: no cover
"""Checks for installation errors"""
pass
def _check_updates():
"""Checks for updates"""
pass
def sanity_check():
"""
Sanity check to check for basic installation errors,
version conflicts, upgrades, etc.
**Run this if you experience any problems with epispot and before
submitting any issues**
"""
# check for installation errors
if not source or not version: # pragma: no cover
_check_install()
# check for version conflicts
import sys
if (sys.version_info[0] < 3) or \
(sys.version_info[0] == 3 and sys.version_info[1] < 7):
raise RuntimeError('Epispot requires Python 3.7 or later') # pragma: no cover
_check_versions()
# check for updates
_check_updates()
# version info
version = '3.0.0-alpha-3'
"""
Epispot's version info (updated every release)\n
Check version information with:
```
>>> print(epispot.version)
```
Version information is also available through the `__version__`
property, included for legacy support.
"""
__version__ = version # alias for version
stable = False
"""
Build stability:
- True ⇒ main package (stable)
- False ⇒ nightly package (possibly unstable)
"""
# metadata
source = 'https://www.github.com/epispot/epispot'
"""URL to VCS source"""
raw = f'https://raw.githubusercontent.com/epispot/epispot/v{version}/'
"""URL to raw VCS source (must append file path)"""
docs = f'https://epispot.github.io/epispot/en/v{version}/'
"""Project documentation (version-specific)"""
issues = 'https://www.github.com/epispot/epispot/issues'
"""Bug tracker"""
Sub-modules
epispot.comps
-
The
epispot.comps
module is a collection of compartments used to initialize theModel
object to create a compartmental model. Each of these … epispot.fitters
-
This module contains all available fitting algorithms. These operate separately from the
Model
class … epispot.models
-
The
epispot.models
classes store different types of epidemiological models in a compact form useful for integration. Models can be differentiated, … epispot.params
-
The
epispot.params
module stores various parameter distributions and estimations, many of which have been pulled from the literature. These … epispot.plots
-
This sub-package is responsible for plotting epispot models of the
Model
class. This is done independently of any other modules and … epispot.pre
-
This module (short for 'pre-compiled') contains models that have already been compiled and can be put to use immediately. Each function returns an …
Global variables
var docs
-
Project documentation (version-specific)
var issues
-
Bug tracker
var raw
-
URL to raw VCS source (must append file path)
var source
-
URL to VCS source
var stable
-
Build stability:
- True ⇒ main package (stable)
- False ⇒ nightly package (possibly unstable)
var version
-
Epispot's version info (updated every release)
Check version information with:
>>> print(epispot.version)
Version information is also available through the
__version__
property, included for legacy support.
Functions
def sanity_check()
-
Sanity check to check for basic installation errors, version conflicts, upgrades, etc.
Run this if you experience any problems with epispot and before submitting any issues
Expand source code
def sanity_check(): """ Sanity check to check for basic installation errors, version conflicts, upgrades, etc. **Run this if you experience any problems with epispot and before submitting any issues** """ # check for installation errors if not source or not version: # pragma: no cover _check_install() # check for version conflicts import sys if (sys.version_info[0] < 3) or \ (sys.version_info[0] == 3 and sys.version_info[1] < 7): raise RuntimeError('Epispot requires Python 3.7 or later') # pragma: no cover _check_versions() # check for updates _check_updates()