unglobalpulse/ungp-settlement-modelling

Agent-based model for simulating the spread of epidemics in refugee and IDP settlements. Adapted from the JUNE framework.

Operational response simulation tool for epidemics within refugee and IDP settlements

This repo contains the relevant code for our individual-based simualtion for epidemics within refugee and internally displaced person (IDP) settlements. See our paper for more details on the model set-up. Our model is based on the JUNE epidemic modelling framework originally applied to simulating the spread of COVID-19 in the UK.

The model presented here is designed to be generalizable to any settlement, however, we initially focus on Kutupalong-Batukhali Expansion Site, part of the refugee settlement in Cox's Bazar, Banghladesh.

If you wish to adapt this to your own setting, we encourage you to do so. If you need any assistance please do get in touch with us (see Contact section below).

When using this work please cite:

@article {AylettBullock2021Operational,
	author = {Aylett-Bullock, Joseph and Cuesta-Lazaro, Carolina and Quera-Bofarull, Arnau and Katta, Anjali and Hoffmann Pham, Katherine and Hoover, Benjamin and Strobelt, Hendrik and Moreno Jimenez, Rebeca and Sedgewick, Aidan and Samir Evers, Egmond and Kennedy, David and Harlass, Sandra and Gidraf Kahindo Maina, Allen and Hussien, Ahmad and Luengo-Oroz, Miguel},
	title = {Operational response simulation tool for epidemics within refugee and IDP settlements: A scenario-based case study of the Cox’s Bazar settlement},
	year = {2021},
	doi = {10.1371/journal.pcbi.1009360},
	URL = {https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1009360},
	journal = {PLoS Comput Biol},
    number = {17},
    volume = {10}
}

Setup

Clone the repo:

git clone https://github.com/UNGlobalPulse/UNGP-settlement-modelling-private 

and install the necessary packages:

pip install -e .

Note: This repo uses june v1.1.2 If you want to use the latest version of JUNE-Private, install this with:

pip install git+https://github.com/IDAS-Durham/JUNE-private.git 

or with ssh

pip install git+ssh://[email protected]/IDAS-Durham/JUNE-private.git

and then install this package locally without the requirements.txt line installing a release version of JUNE.

Data

Your code will now be ready to go, however, in order to run the simulation you will need the relevant data. Two folders are required to be created in order to run this simulation.

The first is the data for the base JUNE model. In the home directory run:

get_june_data.sh

This will create a data folder in <HOME>/data/

You need a second folder with the data for your particular adaptation (in our case, the Cox's Bazar refugee settlement). This should be in <HOME>/camp_data/

The data we use to run the simualtion is all derived from open-source datasets, details of which can be found in our paper. Given the sensitivity of this project we are not open-sourcing this data, however, please get in contact with us if you would like to know more about data access (see Contact section below).

Quickstart

In order to introduce the user to our codebase we have created a walkthrough Notebook:

Notebooks/quickstart camp.ipynb

Documentation

The documentation for this project is in the docs/ folder. Currently, the user needs to build this locally to render the html files. Do to this make sure the relevant sphinx packages are installed:

pip install sphinx
pip install sphinx_rtd_theme

Then you can generate the build/ file:

cd docs/
make clean
make html

The docs can then be viewed in a web browser:

open build/html/index.html

Contributing

Contributions to this project are welcome. Please fork the repository and submit Pull Requests with detailed descriptions of your changes. Please consider whether this change is more appropriate to this repository or the JUNE repository.

Tests

Run the tests with:

cd test_camps
pytest

Note: You currently need the data to be downloaded locally to run these.

License

Epidemiological modeling is a sensitive topic and it is important that models being used to influence public health decision making are able to be reviewed and proped by the community. In the interest of scientific openness and advancement we made this code available under the GPL v3 License.

This code relies on the JUNE epidemic modelling framework which is licensed under GPL v3.

Contact

For questions regarding this project please contact: joseph[at]unglobalpulse.org

TODO

• Synthesise testing data such that pytest can be run on GitHub Actions for better CI workflow
• Update camp_scripts/full_run_parse.py for new version update

ungp-settlement-modelling's Issues

Make camps a separate package

Currently we are putting new source code in the june/ folder. This makes it quite hard to remerge with the original branch. We should have a separate folder (module) called camps, in which we put all specific code for camps. We can modifiy the june source code if it's for changes that are general.

The same should apply for tests.

Adding age and sex probabilities to configs for activities

Based on data collected on how often people go to get aid and who goes, as well as who goes and how often to communal centres, we need to add information to the relevant config files.

Config files for these activities can be found here:

https://github.com/JosephPB/JUNE/tree/master/configs/defaults/groups/leisure

We need to input data for:

• General communal space attendance: https://github.com/JosephPB/JUNE/blob/master/configs/defaults/groups/leisure/communal.yaml
• Female friendly communal space attendance: https://github.com/JosephPB/JUNE/blob/master/configs/defaults/groups/leisure/female_communal.yaml
• Distribution center attendance: https://github.com/JosephPB/JUNE/blob/master/configs/defaults/groups/leisure/distribution_centers.yaml

What is there currently is possibly overdetailed. You could do something as simple as this:

https://github.com/JosephPB/JUNE/blob/master/configs/defaults/groups/leisure/pumplatrines.yaml

Let me know if you need help

Merge error with isolation unit run

According to @florpi, the last major master merge broke the isolation units

Adding aid worker 'box'

In an attempt to incorporate aid-workers into the simulation, the following steps could be taken:

• Create 'box' outside the camp which simulates aid worker living and interactions
• Work out the relevant workers in incorporate, e.g.: distribution center workers, those making household-to-household visits
• Implement the subgroup structure in relevant locations to incorporate workers

Shelters

Currently we assume it's household lives in a separate physical space, so no interactions happen between people in different households in the household space (apart from household visits).

Given that ~75% of the population share a shelter, we should have a new Shelter class that contains two subgroups (two households, 75% of the time), or one (25% of the time).

Make household to household visits work with shelters

Currently household to household visits do not work with the new shelter configuration

Travelling between locations

Currently people move around the camp without interacting with those along the way. This could be a reasonable assumption in some places, however, it has been found that many streets and roads in the camp are not wide enough to allow social distancing. We should have some way to randomly interact and transit the virus as people move between locations.

People currently know where they are coming and going to at each time step and so, although we could account for a road network, the simplest thing would be to draw a line between the two places and randomly interact with households along the way.

I think what we could do is define which places people generally travel further to get to and have those locations activate a 'travel' class which account for their movement.