Package `epispot`

epispot

epispot v3

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

Notice: The epispot nightly package is now officially deprecated.

The epispot package can be installed from PyPI, Anaconda, or be built from the source. Below are the steps for each installation process:

PyPI

This is the easiest way to install epispot. From a terminal, enter:

pip install epispot

Anaconda

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 and install the dependencies with:

git clone https://github.com/epispot/epispot
cd epispot
pip install -r requirements.txt
pip install -r bin/requirements.txt

Then, build the latest version with:

python setup.py install

For older releases, first checkout a version tag before installing; e.g.:

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):

Demo showing how to create an SEIR model in less than 20 lines of code

Documentation

Right now, documentation for some of the latest releases is quite shaky. The official docs are located at https://epispot.github.io/epispot/ but may be incomplete in many areas.

Examples

The GitHub repository has a vast array of samples using epispot. We are currently working on a tutorial, but for now the documentation is the best place to start.

Badges

PyPI: latest-release

LGTM:

Codecov:

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 are 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 (2022, August 20). epispot/epispot: (Version 3.0.0-rc-1). Zenodo. http://doi.org/10.5281/zenodo.5136721

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 contains the same functionality of epispot but in pure JavaScript, making it more suitable for use in a web browser
covasim by the Institute for Disease Modeling offers agent-based stochastic models as opposed to epispot's compartmental modeling structure
CovsirPhy by @lisphilar offers greater support for loading and analyzing real COVID-19 data instead of running simulations

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 cite @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!

epispot's open-source contributors

Expand source code

"""
.. include:: ../README.md
<!--
Documentation available at:
https://epispot.github.io/epispot/en/v3.0.0-rc-1
-->
"""


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 random
import warnings

# dependencies
import dill
import numpy as np
from matplotlib import colors
from matplotlib import pyplot as plt


# helper funcs
def _check_versions():
    """Checks for version conflicts"""
    pass

def _check_install():  # pragma: no cover
    """Checks for installation errors"""
    raise RuntimeError(
        'It seems that this installation of epispot '
        + 'may have been corrupted.\n'
        + 'Please check for the latest version of epispot listed here:\n'
        + 'https://pypi.org/project/epispot/\n'
    )

def _check_updates():
    """Checks for updates"""
    pass


# global funcs
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()

def cite(bibtex=False):
    """
    Returns the citation string for the package.
    Use `bibtex=True` to return the BibTeX-formatted citation.
    """
    if bibtex:
        return '''@software{q9i_2022_5136721,
  author       = {quantum9innovation},
  title        = {epispot/epispot:},
  month        = aug,
  year         = 2022,
  publisher    = {Zenodo},
  version      = {3.0.0-rc-1},
  doi          = {10.5281/zenodo.5136721},
  url          = {https://doi.org/10.5281/zenodo.5136721}
}'''
    else:
        return 'quantum9innovation (2022, August 20). epispot/epispot: (Version 3.0.0-rc-1). Zenodo. <http://doi.org/10.5281/zenodo.5136721>'


# version info
version = '3.0.0-rc-1'
"""
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 = True
"""
Build stability:

- True ⇒ main package (stable)
- False ⇒ nightly (unreleased) package (possibly unstable)
"""


# local
from . import analysis, comps, estimates, models, params, plots, pre

# 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"""
citation = cite()
"""Static citation string"""

Sub-modules

epispot.analysis: The analysis sub-package contains various utilities for forecasting and processing real-time epidemiological data …
epispot.comps: The epispot.comps module is a collection of compartments used to initialize the Model object to create a compartmental model. Each of these …
epispot.estimates: This sub-package contains various estimates from the literature to be used in conjunction with epispot's models …
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. These parameter distributions are divided into two classes: those …
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 citation

Static citation string

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 (unreleased) 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 cite(bibtex=False)

Returns the citation string for the package. Use bibtex=True to return the BibTeX-formatted citation.

Expand source code

def cite(bibtex=False):
    """
    Returns the citation string for the package.
    Use `bibtex=True` to return the BibTeX-formatted citation.
    """
    if bibtex:
        return '''@software{q9i_2022_5136721,
  author       = {quantum9innovation},
  title        = {epispot/epispot:},
  month        = aug,
  year         = 2022,
  publisher    = {Zenodo},
  version      = {3.0.0-rc-1},
  doi          = {10.5281/zenodo.5136721},
  url          = {https://doi.org/10.5281/zenodo.5136721}
}'''
    else:
        return 'quantum9innovation (2022, August 20). epispot/epispot: (Version 3.0.0-rc-1). Zenodo. <http://doi.org/10.5281/zenodo.5136721>'

def dependency_check()

Checks dependencies

Expand source code

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')

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()

epispot v3

Features

Installation

PyPI

Anaconda

Building from the source

Quick Demo

Documentation

Examples

Badges

Feedback

Contributing

Citation

Related Work

Authors

Acknowledgements

Idea & Inspiration

Code Development & Maintenance

Sub-modules

Global variables

Functions