PyRoss is a numerical library for inference, forecasts, and optimal control of epidemiological models in Python
Project description
PyRoss: inference, forecasts, and optimised control for epidemiological models in Python
About  Blog  Installation  Examples  Publications  News  License  Documentation  Events  Wiki
About
PyRoss is a numerical library that offers an integrated platform for inference, forecasts and nonpharmaceutical interventions in structured epidemiological compartment models.
Compartment models of arbitrary complexity can be userdefined through Python dictionaries. The most common epidemiological models, and several less common ones, come predefined with the library. Models can include stages to allow for nonexponentially distributed compartmental residence times. Currently, predefined 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 compartment framework supports models for disease surveillance and quarantine and a variety of other processes of epidemiological relevance.
Generative processes can be formulated stochastically (as Markov population processes) or deterministically (as systems of differential equations). Population processes are sampled exactly by the DoobGillespie algorithm or approximately by the tauleaping algorithm while differential equations are integrated by both fixed and adaptive timestepping. A hybrid algorithm transits dynamically between these depending on the magnitude of the compartmental fluctuations.
Bayesian inference on predefined or userdefined models is performed using modeladapted Gaussian processes derived from functional limit theorems for Markov population process. Generative models are fitted to data through the surveillance model allowing for possibily unobserved compartments. The MAP estimates of parameters and their standard errors can be obtained rapidly by optimising, obviating the need for expensive Markov chain Monte Carlo. This enables the fast evaluation of the model evidence, through which competing models may be objectively compared and their forecasts combined by Bayesian model averaging. Forecasts of disease progression, then, can be fully Bayesian, convolving uncertainties in data, parameters and models. The sensitivity of these forecasts is estimated through the Fisher information matrix.
Nonpharmaceutical 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.
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.
From a checkout of this repository
Install PyRoss and an extended list of dependencies using
>> git clone https://github.com/rajeshrinet/pyross.git
>> cd pyross
>> pip install r requirements.txt
>> python setup.py install
Install PyRoss and an extended list of dependencies, via Anaconda, in an environment named pyross
:
>> 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
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 modelagnostic, formulationagnostic 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 with three agegroups.
# Ex1: M=3, SIR import numpy as np import pyross import matplotlib.pyplot as plt model_spec = { "classes" : ["S", "I"], "S" : { "constant" : [ ["k"] ], "infection" : [ ["I", "beta"] ] }, "I" : { "linear" : [ ["I", "gamma"] ], "infection" : [ ["I", "beta"] ] } } parameters = { 'beta' : 0.1, 'gamma' : 0.1, 'k' : 1, } M=3; Ni=1000*np.ones(M); N=np.sum(Ni) # Initial conditions as an array x0 = np.array([ 999, 1000, 1000, # S 1, 0, 0, # I ]) # Or initial conditions as a dictionary I0 = [10, 10, 10] S0 = [n20 for n in Ni] x0 = { 'S' : S0, 'I' : I0 } CM = np.array([ [1, 0.5, 0.1], [0.5, 1, 0.5], [0.1, 0.5, 1 ] ], dtype=float) def contactMatrix(t): return CM # duration of simulation and data file Tf = 160; Nf=Tf+1; model = pyross.deterministic.Spp(model_spec, parameters, M, Ni) # simulate model data = model.simulate(x0, contactMatrix, Tf, Nf) # plot the data and obtain the epidemic curve S = np.sum(model.model_class_data('S', data), axis=1) I = np.sum(model.model_class_data('I', data), axis=1) R = np.sum(model.model_class_data('R', data), axis=1) t = data['t'] fig = plt.figure(num=None, figsize=(10, 8), dpi=80, facecolor='w', edgecolor='k') plt.rcParams.update({'font.size': 22}) plt.fill_between(t, 0, S/N, color="#348ABD", alpha=0.3) plt.plot(t, S, '', color="#348ABD", label='$S$', lw=4) plt.fill_between(t, 0, I/N, color='#A60628', alpha=0.3) plt.plot(t, I, '', color='#A60628', label='$I$', lw=4) plt.fill_between(t, 0, R/N, color="dimgrey", alpha=0.3) plt.plot(t, R, '', color="dimgrey", label='$R$', lw=4) plt.legend(fontsize=26); plt.grid() plt.autoscale(enable=True, axis='x', tight=True) plt.ylabel('Compartment value') plt.xlabel('Days');
Read more in the examples folders.
Publications

Efficient Bayesian inference of fully stochastic epidemiological models with applications to COVID19, Yuting I. Li, Günther Turk, Paul B. Rohrbach, Patrick Pietzonka, Julian Kappler, Rajesh Singh, Jakub Dolezal, Timothy Ekeh, Lukas Kikuchi, Joseph D. Peterson, Hideki Kobayashi, Michael E. Cates, R. Adhikari, Robert L. Jack, arXiv:2010.11783, 2020  ResearchGate

Efficient and flexible methods for time since infection models, Joseph D. Peterson, R. Adhikari, arXiv:2010.10955, 2020

Inference, prediction and optimization of nonpharmaceutical 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, 2020  ResearchGate.

Agestructured impact of social distancing on the COVID19 epidemic in India, Rajesh Singh and R. Adhikari, arXiv:2003.12055, 2020  ResearchGate.
News

A partial list of news articles on PyRossbased 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 scientistprogrammer.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Filename, size  File type  Python version  Upload date  Hashes 

Filename, size pyross1.3.4cp37cp37mmacosx_10_7_x86_64.whl (7.7 MB)  File type Wheel  Python version cp37  Upload date  Hashes View 
Filename, size pyross1.3.4.tar.gz (3.2 MB)  File type Source  Python version None  Upload date  Hashes View 
Hashes for pyross1.3.4cp37cp37mmacosx_10_7_x86_64.whl
Algorithm  Hash digest  

SHA256  17454572baadb8c42cc026b73181fef0a37ef4213c4de65784e02fa2a50e25a4 

MD5  32b981ae0ce26924755cd17ab5c283df 

BLAKE2256  ec6d006563b6124ff31dc73efb4c938560b66d81c2e3f3c1fb18e570ff2d9c5d 