Package `epispot`

epispot

epispot nightly

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.

This is a nightly version of epispot and may contain possibly unstable code.\ Please see usage instructions prior to adding this project as a dependency\ If you prefer to use the stable version of epispot, please see the project on PyPI

Installation

The epispot package can be installed from PyPI, Anaconda, or be built from the source. However, as epispot's nightly versions cannot be released per-commit to the conda packaging registry, using Anaconda means that epispot will have to be installed via the built-in pip installer. Instructions for each platform are listed below.

PyPI

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

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, plotly, and SciencePlots for some nightly experiments. These can be installed beforehand with:

pip install numpy
pip install matplotlib
pip install fire
pip install plotly
pip install SciencePlots

Update the package regularly with:

pip install epispot-nightly --upgrade

Anaconda

Please note that the nightly version is not available on the conda package registry (although we may add it in the future). However, it is still possible to install on conda-based systems with

pip install epispot-nightly

which uses pip from Anaconda to install it. All dependencies are available on the conda package registry (except SciencePlots), but you may prefer to install them via pip to avoid cross-referencing packages installed on different registries.

SciencePlots can be installed using pip with:

pip install SciencePlots

Update the package regularly with:

pip install epispot-nightly --upgrade

If you installed the dependencies on conda instead of pip you may have to update them too after major releases. You can do that with:

conda update numpy
conda update matplotlib
conda update fire
conda update -c conda-forge plotly

Building from the source

This is the hardest way to install epispot-nightly but it can be particularly useful if you plan on helping out with the development process. The main downside of this approach is that you will have to continuously run git pull and then rerun the steps listed below to get the latest version.

Clone the repository with:

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

If you're planning on helping out in the development process, it will be helpful to install a few extra requirements with:

pip install -r requirements-dev.txt

Then, build the nightly version with:

python setup-nightly.py install

If you're working on a patch, you may find it helpful to use

python setup-nightly.py develop

instead because it will greatly simplify the constant reinstallation of the package.

Usage

It is important to note that this package was designed specifically for getting releases out as soon as possible when modeling is important. During the COVID-19 pandemic, this strategy allowed epispot to distribute versions quickly on PyPI; additionally, this package is used to ship alpha releases and other unstable code that is currently being developed in the epispot repository. beta-tagged releases and release candidates will be published on the stable package.

Please also note that security updates are not provided on previous nightly versions. To make sure that your version has no vulnerabilities, upgrade to the latest published version regularly. The latest version of the nightly package is the one that is maintained by our development team.

Getting Started

Make sure you are already familiar with epispot. If not, you can find epispot's auto-generated documentation here. Additionally, we highly recommend reading the epispot manual to get a better understanding of the documentation and how to use epispot.

Statuses

Pipeline	Status
Travis CI
CodeCov
PyPI main
PyPI nightly
Security

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

Thank you to all contributors!

epispot's open-source contributors

Made with contributors-img.

Expand source code

"""
.. include:: ../README-nightly.md
<!-- Documentation available at: https://epispot.github.io/epispot/en/v3.0.0-alpha-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.\nInstall 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.\nInstall 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


def _sanity_check():
    """Pre-defined sanity check to check for installation errors"""

    if not version or not source:  # pragma: no cover
        message = \
        '''
        Version information and/or source for your epispot installation could not be found.
        This likely means
         (1) this version of epispot is deprecated or dated
         (2) your installation of epispot is unstable
        Try reinstalling epispot
         (1) From PyPI:
             $ pip install epispot
         (2) From Anaconda:
             $ conda config --add channels conda-forge
             $ conda install -c conda-forge epispot
         (3) From the GitHub Source:
             $ git clone https://github.com/epispot/epispot
             $ cd epispot
             $ python install setup-nightly.py
        If this fails or has failed before, then revert to epispot's last stable version.
        Again, you can do this via
         (1) PyPI:
             (a) Go to https://pypi.org/project/epispot
             (b) Scroll to the last MAJOR release in the form `a.0.0`
             (c) Install via `$ pip install epispot==a.0.0` -- replace `a` with version #
         (2) GitHub Source:
             (a) Go to https://github.com/epispot/epispot
             (b) Click the 'branches' tab
             (c) Select the last branch with name `vA.0.0` for some version number A
             (d) Install as `.zip`
             (e) Unzip
             (f) Run `$ python install setup.py`
        '''
        raise DeprecationWarning(message)


# version info
version = '3.0.0-alpha-1'
"""
Epispot's version info (updated every nightly release)
Get with:

```
    >>> print(epispot.version)
```
"""

stable = False
"""
Build stability:

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

# metadata
source = 'https://www.github.com/epispot/epispot'
"""URL to GitHub source"""
docs = 'https://epispot.github.io/epispot'
"""Project documentation (not version-specific)"""
issues = 'https://www.github.com/epispot/epispot/issues'
"""Submit new issues or bugs here"""


_sanity_check()  # complete installation
del _sanity_check

Sub-modules

epispot.comps: The compartments module contains pre-built disease compartments for basic modelling and allows for custom user-defined compartments. This module …
epispot.fitters: This module contains all available fitting algorithms. These operate separately from the Model class …
epispot.models: The Model classes help create a model out of various disease compartments. For example, the basic SIR model would be a model consisting of the …
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: The 'pre-compiled' module contains already compiled models which can be put to use immediately. Each function returns an epispot Model object and its …

Global variables

var docs

Project documentation (not version-specific)

var issues

Submit new issues or bugs here

var source

URL to GitHub source

var stable

Build stability:

True → main package (stable)
False → nightly package (possibly unstable)

var version

Epispot's version info (updated every nightly release) Get with:

    >>> print(epispot.version)