pyross 1.2.5

PyRoss is a numerical library for inference, forecasts, and optimal control of epidemiological models in Python

PyRoss: inference, forecasts, and optimised control for epidemiological models in Python

About | Installation | Examples | Publications | News | License | Documentation | Events | Wiki

About

PyRoss is a numerical library that offers an integrated platform for inference, prediction and non-pharmaceutical interventions in age- and contact-structured epidemiological compartment models.

The library is designed to be model-agnostic and allows the user to define models in a JSON format. The most common epidemiological models, and several less common ones, come pre-defined with the library. Models can include stages to allow for non-exponentially distributed compartmental residence times. Currently, pre-defined models include ones with multiple disease states (exposed, asymptomatic, symptomatic, etc) and may be further divided by age, and by objective medical states (hospitalized, in ICU, etc).

The library supports models formulated stochastically (as chemical master equations) or deterministically (as systems of differential equations). A hybrid algorithm transits dynamically between these depending on the magnitude of the compartmental fluctuations.

Inference on pre-defined or user-defined models is performed using model-adapted Gaussian processes on the epidemiological manifold or its tangent space. This method allows for latent variable inference and fast computation of the model evidence and the Fisher information matrix. These estimates are convolved with the instrinsic stochasticty of the dynamics to provide Bayesian forecasts of the progress of the epidemic.

Non-pharmaceutical interventions are implemented as modifications of the contact structures of the model. Optimised control of these structures, given cost functions, is possible. This feature is being actively developed to be better integrated with the library.

PyRossGeo is a companion library that supports spatially resolved compartment models with explicit commuting networks. PyRossTSI is another companion library for time since infection models.

The libraries are named after Sir Ronald Ross, doctor, mathematician and poet. In 1898 he made "the great discovery" in his laboratory in Calcutta "that malaria is conveyed by the bite of a mosquito". He won the Nobel Prize in 1902 and laid the foundations of the mathematical modelling of infectious diseases.

The authors are part of The Rapid Assistance in Modelling the Pandemic (RAMP) taskforce at the University of Cambridge. In alphabetical order, we are: Ronojoy Adhikari, Austen Bolitho, Fernando Caballero, Michael Cates, Jakub Dolezal, Tim Ekeh, Jules Guioth, Robert Jack, Julian Kappler, Lukas Kikuchi, Irene Li, Joseph Peterson, Patrick Pietzonka, Benjamin Remez, Paul Rohrbach, Rajesh Singh, and Günther Turk.

Please read the PyRoss paper and PyRoss Wiki before you use PyRoss for your research. Open an issue, in preference to emailing us with queries. Join our Slack channel for discussion. Please follow the Contributor Covenant in all PyRoss fora. Thank you!

Installation

You can take PyRoss for a spin without installation: . Please be patient while Binder loads.

Via Anaconda

Install PyRoss and its dependencies in a pyross environment:

>> git clone https://github.com/rajeshrinet/pyross.git
>> cd pyross
>> make env
>> conda activate pyross
>> make

Via pip

Install the latest PyPI version

>> pip install pyross

From a checkout of this repository

Install PyRoss and required dependencies using

>> git clone https://github.com/rajeshrinet/pyross.git
>> cd pyross
>> pip install -r requirements.txt
>> python setup.py install

Testing

Short test of initialisation and running

make test

Long test of all example notebooks. Optionally can specify path and recursion to test a certain subset of notebooks.

make nbtest -e path=examples/deterministic/

Age structure data: Population Pyramid website

Contact structure data: Projecting social contact matrices in 152 countries using contact surveys and demographic data, Kiesha Prem, Alex R. Cook, Mark Jit, PLOS Computational Biology, (2017)

Examples

PyRoss has model-agnostic, formulation-agnostic intuitive interface. Once a model is instantiated, stochastic, deterministic and hybrid simulations can be performed through the same interface. The example below shows how to set up a deterministic SIR simulation. PyRoss Documentation contains links for more examples.

# Ex1: M=1, SIR
import numpy as np
import pyross

M     = 1                  # the SIR model has no age structure
Ni    = 1000*np.ones(M)    # so there is only one age group
N     = np.sum(Ni)         # and the total population is the size of this age group

beta  = 0.2                # infection rate
gIa   = 0.1                # recovery rate of asymptomatic infectives
gIs   = 0.1                # recovery rate of symptomatic infectives
alpha = 0                  # fraction of asymptomatic infectives
fsa   = 1                  # the self-isolation parameter

Ia0   = np.array([0])      # the SIR model has only one kind of infective
Is0   = np.array([1])      # we take these to be symptomatic
R0    = np.array([0])      # and assume there are no recovered individuals initially
S0    = N-(Ia0+Is0+R0)     # initial susceptibles are obtained from S + Ia + Is + R = N

# there is no contact structure
def contactMatrix(t):   
    return np.identity(M)

# instantiate model
parameters = {'alpha':alpha, 'beta':beta, 'gIa':gIa, 'gIs':gIs, 'fsa':fsa}
model      = pyross.deterministic.SIR(parameters, M, Ni)

# simulate model
Tf, Nt = 160,  160           # duration of simulation and data points
data = model.simulate(S0, Ia0, Is0, contactMatrix, Tf, Nt)

# time series of S, Ia, Is, R
S  = model.S(data)
Ia = model.Ia(data)
Is = model.Is(data)
R  = model.R(data)

Publications

• Inference, prediction and optimization of non-pharmaceutical interventions using compartment models: the PyRoss library, R. Adhikari, Austen Bolitho, Fernando Caballero, Michael E. Cates, Jakub Dolezal, Timothy Ekeh, Jules Guioth, Robert L. Jack, Julian Kappler, Lukas Kikuchi, Hideki Kobayashi, Yuting I. Li, Joseph D. Peterson, Patrick Pietzonka, Benjamin Remez, Paul B. Rohrbach, Rajesh Singh, and Günther Turk, arXiv:2005.09625, Research Gate.
  (Please cite this paper if you use PyRoss in your research).

• Age-structured impact of social distancing on the COVID-19 epidemic in India, Rajesh Singh and R. Adhikari, arXiv:2003.12055, Research Gate.

News

• A partial list of news articles on PyRoss-based research: Zee News | Varsity | The Weekend Leader | The Weather Channel | The Tribune | The Times of India | The Telegraph | The Northlines | The New Indian Express | The Federal | Swarajya | Snoop Tales | Scroll.in | Rediff.com | The Quint | People's Reporter | News Bundle | Newsgram | Nature News | Mathrubhumi | liveMint | India New England News | India Today | Indian Express: Bangla | Indian Blooms | Dainik Bhaskar | CNN | CCN | Business Standard | Asiaville

• Python Trending has tweeted about PyRoss

  PyRoss - Mathematical modelling of infectious disease in Python. https://t.co/VBOmT5kaVT https://t.co/FRvEqWMlPL

  — Python Trending (@pythontrending) March 31, 2020

• Python Weekly has tweeted about PyRoss

  PyRoss - Mathematical modelling of infectious disease in Python. https://t.co/MyTWTM1ItP #Python #Coronavirus #Covid19 pic.twitter.com/gzPNpWf7mK

  — Python Weekly (@PythonWeekly) April 9, 2020

License

We believe that openness and sharing improves the practice of science and increases the reach of its benefits. This code is released under the MIT license. Our choice is guided by the excellent article on Licensing for the scientist-programmer.