MetaWards disease metapopulation modelling
Project description
MetaWards
This is a Python port of the MetaWards package originally written by Leon Danon. This is currently a work in progress and is not intended yet for production use. The port is kept in sync with the original C code, with checks in place to ensure that the two codes give identical results. This improves the robustness of both codes, as it minimises the footprint to bugs that can evade both C and Python.
The aim of this port is to make it easier for others to contribute to the program, to improve robustness by adding in unit and integration test, and to also open up scope for further optimisation and parallelisation.
The package makes heavy use of cython which is used to compile bottleneck parts of the code to C. This enables this Python port to run at approximately the same speed as the original C program.
There is still a lot of work to do, so please bear with us as we work to make this package into a well-documented, easily usable application that will help you to reproduce the model runs and analysis. Apologies in advance if we are slow to respond to any issues - we are working at high speed to get everything ready and aim to have most things completed by the beginning of Easter. We appreciate people want to help. At this stage adding more people won't speed things up, and we now have a team of professional Research Software Engineers working on this package.
Data
The data and input parameters needed to use this package are stored in the MetaWardsData repository. Please make sure that you clone this repository to your computer and supply the full path to that repository to the program when it runs. There are three ways to do this;
-
Set the
METAWARDSDATA
environment variable to point to this directory, e.g.export METAWARDSDATA=$HOME/GitHub/MetaWards
-
Pass the
repository
variable to the input data classes Disease, InputFiles and Parameters -
Or simply make sure you clone into the directory
$HOME/GitHub/MetaWardsData
as this is the default path.
References
These are the references behind the original C code are;
-
"Individual identity and movement networks for disease metapopulations" Matt J. Keeling, Leon Danon, Matthew C. Vernon, Thomas A. House Proceedings of the National Academy of Sciences May 2010, 107 (19) 8866-8870; DOI: 10.1073/pnas.1000416107
-
"A spatial model of CoVID-19 transmission in England and Wales: early spread and peak timing" Leon Danon, Ellen Brooks-Pollock, Mick Bailey, Matt J Keeling medRxiv 2020.02.12.20022566; doi: 10.1101/2020.02.12.20022566
Dependencies
The code requires Python 3.7 or above and depends on pygsl and cython.
You will also need to install the GNU Scientific Library (GSL). On macOS this can be installed using Homebrew:
brew install gsl
On Linux, you can install the libgsl
package, e.g. for Ubuntu:
apt-get install libgsl-dev
The pygsl
Python package also requires numpy
, which isn't installed
automatically as a dependency if you install pygsl
using pip.
Only the gsl_rng.binomial
function is used from GSL, so it is likely
that this requirement will soon be dropped. The link to GSL forces us
to use a GPL3 license for this Python package. Once we have replaced
the binomial function we will re-evaluate the license under which this
code is distributed.
Installation
You can install the code from source by typing;
git clone https://github.com/metawards/MetaWards
cd MetaWards
CYTHONIZE=1 python setup.py install
(assuming that python
is version 3.7 or above)
You can run tests using pytest, e.g.
METAWARDSDATA="/path/to/MetaWardsData" pytest tests
You can also install via pip
using
pip install metawards
Running
You can either load and use the Python classes directly, or you can
run the metawards
front-end command line program that is automatically installed.
metawards --help
will print out all of the help for the program. For example;
metawards --input tests/data/ncovparams.csv --seed 15324 --nsteps 30
This will duplicate the run of the MetaWards C program that is bundled in this repository that was run using;
./original/metawards 15324 tests/data/ncovparams.csv 0 1.0
The original C code, command line and expected output are in the original directory that is bundled in this repo.
Running an ensemble
We will be integrating this Python port with multiprocessing and dask to enable multiple models and seeds to be run in parallel over distributed resources. The aim is to have this parallel code working by the beginning of Easter.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for metawards-0.4.0-cp37-cp37m-macosx_10_9_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | be27969cfab2857bb3835b809a1bd1e2eb02b5854f1190b0e41134ef83916e1a |
|
MD5 | bd90418b491c00971599f78fd8530475 |
|
BLAKE2b-256 | 6d201ab1836f13b80d5730ac14edb812049d0d519a98405e5fd824fa18d4c9e3 |