ambforecast: open reproducible forecasts of ambulance incidents, calls and responses

Documentation: https://ambmodels.github.io/ambforecast/

Setup

Dependencies are listed in pyproject.toml. These can be installed using Python 3.13 and your preferred environment manager.

Mamba

mamba create -n ambforecast python=3.13
mamba activate ambforecast
pip install -e .

venv

On Windows:

py -3.13 -m venv .venv
.\venv\Scripts\activate
pip install -e .

On Linux or macOS:

python3.13 -m venv .venv
source .venv/bin/activate
pip install -e .

Poetry

poetry env use 3.13
poetry install
poetry shell

uv

uv venv --python 3.13
source .venv/bin/activate
pip install -e .

Using ambforecast

This repository contains the open-source forecasting code and simple examples showing how to use its main functions.

Making the code open supports transparency, reproducibility, and reuse. It allows others to understand how the forecasts are produced, test and improve the methods, and adapt them for other ambulance services or similar forecasting problems.

The full analysis using real ambulance service data is carried out in the separate private ambforecast-private repository. Private analysis outputs are not included here.

Pre-commit

This repository includes a pre-commit hook that checks for the filename of real (private) data, which should never be used here. That analysis belongs in a separate, private repository. If you've accidentally referenced the real data file name in a staged file, the hook will detect it and block the commit, prompting you to remove it before processing.

To activate this hook after cloning this repository, run:

pre-commit install

Documentation

The documentation is rendered and published on GitHub pages via GitHub actions. You can view it at: https://ambmodels.github.io/ambforecast/

However, if you would like to render it locally, you can run:

great-docs build
great-docs preview

Linting and formatting

This project uses ruff to keep Python code consistent and catch common issues. It's settings are stored in pyproject.toml. Run the following commands from the project root to format Python files (.py) and notebooks (.ipynb). It will automatically fix any linting and formatting issues where possible.

ruff format
ruff check --fix
lintquarto

Citation

If you use this repository, please cite us:

Heather, A., Coulson, L., Irungu, I., & Monks, T. ambforecast: open reproducible forecasts of ambulance incidents, calls and responses [Computer software]. https://github.com/ambmodels/ambdes

Contributors ✨

TODO: Add Irene once receive GitHub username.

Thanks goes to these wonderful people (emoji key):

Amy Heather 💻

Tom Monks 💻

LeeCoulsonNHS 💻 🔣 🤔

Rob Challen 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!

Acknowledgements

This work is part of the STARS project, supported by the Medical Research Council [grant number MR/Z503915/1]

This repository builds on the work reported in:

Monks, T., Harper, A., Allen, M. et al. Forecasting the daily demand for emergency medical ambulances in England and Wales: a benchmark model and external validation. BMC Med Inform Decis Mak 23, 117 (2023). https://doi.org/10.1186/s12911-023-02218-z.

The GitHub repositories from that publication are https://github.com/TomMonks/swast-benchmarking and https://github.com/TomMonks/swast-forecast-tool.