The New Hospital Programme Demand Model

Welcome

Welcome to the New Hospital Programme demand and capacity modelling tool.

This repository contains the model code but there are several other repositories which contain useful tools to explore the data underpinning and set the parameters for the model, as well as to explore model outputs. An overview of how the different tools interact with each other is available.

The methodology underpinning this model is outlined in this simple one page explainer. We have a more technical project information site which includes further details about the model and the data that the model was built on.

Running the model

For external users

Although all the code is available openly, it is challenging to run the model if you do not have access to the data and infrastructure at the Strategy Unit.

We use national Hospital Episode Statistics data which goes through extensive processing, as detailed in the nhp_data repository. Some of the types of potentially mitigable activity rely on having access to the full national dataset, not just a local dataset. Without this data and infrastructure, your data will not be correctly formatted to run in the model.

We are working on providing synthetic data so that interested parties can run the model locally to see how it works.

Prospective users of the model should contact the Strategy Unit to enquire about using the model on our existing infrastructure.

Please note that it is important that the parameters of the model are set with great care and with proper support. It is important also that healthcare system partners are appropriately involved in parameter setting. For a description of the full process and support provision that is necessary to ensure the model functions well please see the NHS Futures workspace

For internal users with full access to correctly formatted data

Assuming you have your data in the correct format, store it in the data folder. Further details on the correct formatting for the data to follow.

The model runs using parameters that are set in a JSON file.

Running the model using uv

This package is built using uv. If you have uv installed, run the model using: uv run -m nhp.model path/to/params.json -d path/to/data

Running the model without uv

1. Install the nhp_model package using pip install .
2. Run the model using: python -m nhp.model path/to/params.json -d path/to/data

Deployment

The model is deployed to Azure Container Registry and GitHub Container Registry on pull requests, tagging the container as nhp_model:dev, and on releases its deployed to nhp_model:v*.*.* and nhp_model:latest.

Testing

The model has unit, integration, and e2e tests defined. The unit tests run on GitHub Actions whenever we create PRs. We also derive our code coverage from unit tests alone.

Integration and e2e tests require the synthetic dataset to be downloaded, which is currently not released publicly. If you have access to this data, you can run the VS Code task "Download synth data". These tests use pytest-regressions to capture the results of running the model against the current synthetic data.

Any time the model changes, or the synthetic data changes, these tests will need to regenerate snapshots. You can do this with:

uv run pytest -m "e2e or integration" --force-regen

You should see the snapshot files (e.g. .csv and .yml) updated in your git working tree. This can be a useful way to test the impact of changes to the model by reviewing the git diffs.

All tests must be marked with one of the markers:

• @pytest.mark.unit
• @pytest.mark.integration
• @pytest.mark.e2e

If you create a new test and do not mark it, or add more than one of these markers, then pytest discovery will fail and indicate the test which is violating this rule.

JSON Schema

Parameters for the model are set in JSON format; an example can be seen in src/nhp/model/params/params-sample.json. As the model develops, requirements for this JSON file change over time. We use JSON schema to manage changes to the parameters file. From model v3.5 onwards, these are deployed to GitHub pages, following this pattern:

• on merge to main, the schema is deployed to https://the-strategy-unit.github.io/nhp_model/dev/params-schema.json
• on release of new model version vX.X, the schema is deployed to https://the-strategy-unit.github.io/nhp_model/vX.X/params-schema.json