The Water Access model is a tool that simulates global access to freshwater sources by walking or cycling in the event of global catastrophic infrastructure loss (CIL). The output of the model can be used to identify areas at various resolutions (global, continental, country, district, and 5-arcminute zonal) which will be at highest risk of water insecurity in a catastrophe. This model can be useful for researchers, developers, and disaster response teams who are interested in understanding the potential impact of CIL on water access. The model is implemented in Python and its outputs have the potential to be integrated into other analysis and visualization tools (e.g., QGIS).
To install the Water Access package, we recommend setting up a virtual environment using mamba (faster) or conda. This will ensure that the package and its dependencies are isolated from other projects on your machine, which can prevent conflicts and make it easier to manage your dependencies. Here are the steps to follow:
- Create a virtual environment using either conda by running the command
mamba env create -f environment.yml. This will create an environment called "water-access". A virtual environment is like a separate Python environment, which you can think of as a separate "room" for your project to live in, it's own space which is isolated from the rest of the system, and it will have it's own set of packages and dependencies, that way you can work on different projects with different versions of packages without interfering with each other.
Input data is stored with Git LFS. Install LFS and run git lfs pull after cloning.
git lfs install
git lfs pull
mamba env create -f environment.yml
mamba activate water-access
pip install -e .For Jupyter notebooks, register a kernel:
python -m ipykernel install --user --name=water-accessIf imports fail in the notebook kernel, rerun pip install -e . from the repository root.
- Alternatively, you may wish to run the notebook in an IDE such as Visual Studio Code (instructions here)
├── data/ Input data (GIS, lookup tables, processed)
├── docs/ Full reproduction workflow
├── gcp/ Optional cloud deployment for large Monte Carlo runs
├── results/ Model outputs (CSVs, parquets, plots)
├── scripts/ Notebooks and processing scripts
├── src/ Core model code
└── tests/ Unit tests
Run scripts/key_results.ipynb and scripts/distribution_plots.ipynb to generate key tables and plots from the summary CSVs in results/.
- Run
scripts/run_monte_carlo.py— Monte Carlo simulations (resource-intensive; parameter ranges are defined at the top of the script). - Run
scripts/key_results.ipynbandscripts/distribution_plots.ipynbto analyze the new outputs.
For a single deterministic run (no Monte Carlo), use src/gis_global_module.py.
For large runs on Google Cloud Spot VMs, see gcp/gcp-setup.md.
Step-by-step instructions to reproduce the full analysis pipeline (including QGIS map outputs) are in docs/README.md.
