search

SABS-R3-Epidemiology / epiabm

Epidemiological agent-based modelling packages in both python and C++. Published at: https://doi.org/10.5334/jors.449.
BSD 3-Clause "New" or "Revised" License
15 stars 5 forks source link
agent-based-modeling epidemiology

readme

Epiabm

Unit tests (python versions) Unit tests (cpp versions) Documentation Status codecov DOI

General Information

This program implements an agent-based SEIR model with added compartments and spatial complexity. It imitates the Imperial CovidSim model, but aims to simplify and clarify the model by using more user-friendly software practices. It also provides various sub-models (with elements such as age-stratification or spatial distribution removed) for research and pedagogical investigation into the effect of different aspects of the model.

Model Summary

The model contains two main sections: spatial infection mechanisms and within-host disease progression.

For each timestep the code loops through the population and records interactions between infected and susceptible people which may lead to infections. Individuals are allocated a susceptibility based on age and location data and pairs of individuals considered to see whether their interaction leads to infection. The likelihood of a pair interacting is weighted by spatial distance and age factors (as people are more likely to socialise with those of the same age, and children maintain close contact with parents). This incorporates the major spatial variation within the model.

Once an individual becomes exposed, their progression through the various stages of infection is determined by generating a series of random timesteps to mark their movements between infection categories. The possible paths an individual can take are indicated on the schema below.

SEIR model conceptualisation

A more complete overview of our implementation of the Ferguson model is given in the Wiki for this repository.

pyEpiabm

The pyEpiabm backend is written in python, chosen for its readability and user-friendliness. It is not able to cope with large population sizes, but can configure a toy population to explore the functionality of the model and better understand the underlying code. Additionally, toy models may be quicker for model comparison and parameter inference, though care should obviously be taken when scaling up to a full population. We provide a variety of workflows to show the utility of code.

Installation of pyEpiabm

pyEpiabm is not yet available on PyPI, but the module can be pip installed locally. The directory should first be downloaded to your local machine, and can then be installed using the command:

pip install -e .

from the pyEpiabm directory. If you also wish to build the docs locally, this requires additional dependencies, which must be specified:

pip install -e .[docs]

Running a simulation

A number of example simulations are included the in the python_examples directory. The simplest complete workflow for running a simulation is provided in python_examples/basic_example/simulation_flow.py, but all others follow a similar format. Other example simulations include an age_stratified_example, and spatial_example which demonstrate these aspects of the module. gilbraltar_example combines age and spatial stratification using census data from Gibraltar, and can be used to benchmark against CovidSIM.

There are a number of steps to any simulation:

Set Random Seed (Optional)

This allows the random seed to be set for all random modules used in the simulation, to enable reproducible simulations. The recommended approach here is to set one seed at the start of the script (before configuring the population or the simulation objects), so that both are generated according to this seed. It is also possible to set a separate seed for one or other object, by passing population_seed or simulation_seed into their respective parameter dictionaries, however care should be exercised to ensure the two objects are configured sequentially. For example, generating a second population after setting the simulation seed would be done according to simulation_seed not population_seed. Setting the seed is not currently compatible with multi-threaded execution.

Configure Population

Create a population based on the parameters given, from the following list:

Import Population

Alternatively, it is possible to import a population from a .csv file, with the following headings:

File of this format can also be exported using the pyEpiabm.routine.FilePopulationConfig.print_population() method, i.e. for reproducibility or use in further simulations.

Configure Simulation

Configure a simulation with a number of parameters. These are split into three categories:

sim_params (For running the simulation)

file_params (For controlling output location)

inf_history_params (For controlling the infection history output - Default None)

Two lists of sweeps must also be passed to this function - the first will be executed once at the start of the simulation (i.e. to determine the initial infections in the population), while the second list will be ran at every timestep (i.e. to propagate the infection through the population).

pyEpiabm Documentation

Documentation on the python backend (pyEpiabm) is stored on Read The Docs.
The Wiki for this repo also contains more detail on the Ferguson model itself, and where our implementation might differ from that.

cEpiabm

We also provide an efficient and scalable backend in C++, which can run simulations for populations comparable to the UK in a reasonable timeframe. This code may be harder for new users to understand, but the parallels with the python code should be sufficiently informative for those who wish to look deeper into the code.

Set up

Installation of cEpiabm

Cmake is used for installation of the cEpiabm software. The following procedure will compile the code and run all unit tests:

mkdir build_dir
cd build_dir
cmake ../cEpiabm/. -DCMAKE_BUILD_TYPE=Debug
cmake --build . --parallel 2 --target unit_tests
ctest -j2 --output-on-failure

Note that cmake must be installed on your system. The following command can be used on ubuntu systems:

sudo apt-get install cmake cmake-data

We recommend the use of the G++ compiler (version 9 or higher) with cEpiabm. If other compilers are used, users should ensure they include the filesystem library, or include this explicitly by inserting link_libraries(stdc++fs) in CMakeLists.txt.

Compiling cEpiabm Python Bindings

Pybind11 is required for compiling cEpiabm with Python bindings. Pybind11 is added as a git submodule, make sure this submodule is cloned along with the main epiabm repository.

Compiling Python bindings follows similar procedure to compiling the cEpiabm tests:

mkdir build_dir
cd build_dir
cmake ../cEpiabm/. -DCMAKE_BUILD_TYPE=Release -DENABLE_COVERAGE=OFF
cmake --build . --parallel 6 --target epiabm

cEpiabm's python bindings will be compiled to a python module named epiabm, located in build_dir/src/epiabm.cpython-(version info).so.

cEpiabm Documentation

Documentation on the C++ backend (cEpiabm) is stored on Read The Docs.

References

List of resources that may be useful for the project: