Metadata-Version: 2.4
Name: nhp-model
Version: 5.2.0
Summary: New Hospital Programme demand model
Author-email: The Strategy Unit <mlcsu.su.datascience@nhs.net>
License: MIT License
        
        Copyright (c) 2025 NHS England
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: <3.14,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: azure-data-tables>=12.7.0
Requires-Dist: azure-identity>=1.12
Requires-Dist: azure-storage-blob>=12.30.0
Requires-Dist: azure-storage-file-datalake>=12.25.0
Requires-Dist: importlib-resources>=7.1.0
Requires-Dist: jsonschema>=4.23.0
Requires-Dist: metalog-jax>=1.0.2
Requires-Dist: numpy>=2.5.0
Requires-Dist: pandas>=3.0.3
Requires-Dist: pyarrow>=24.0.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: scipy>=1.18.0
Requires-Dist: tqdm>=4.68.3
Dynamic: license-file

# The New Hospital Programme Demand Model

<!-- badges: start -->

[![Project Status: Active – The project has reached a stable, usable
state and is being actively
developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![codecov](https://codecov.io/gh/The-Strategy-Unit/nhp_model/branch/main/graph/badge.svg?token=uGmRhc1n9C)](https://codecov.io/gh/The-Strategy-Unit/nhp_model)

<!-- badges: end -->

## Welcome

Welcome to the [New Hospital Programme demand and capacity modelling tool](https://www.strategyunitwm.nhs.uk/new-hospital-programme-demand-model).

<img width="2000" height="1414" alt="Smarter Hospital Planning" src="https://www.strategyunitwm.nhs.uk/sites/default/files/styles/banner/public/Nationally%20consistent%20approach.png"/>

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](https://github.com/The-Strategy-Unit/nhp_inputs), as well as to [explore model outputs](https://github.com/The-Strategy-Unit/nhp_outputs). [An overview of how the different tools interact with each other is available](https://connect.strategyunitwm.nhs.uk/nhp/project_information/project_plan_and_summary/components-overview.html).

The methodology underpinning this model is outlined in this [simple one page explainer](https://connect.strategyunitwm.nhs.uk/nhp_model_explainer/). We have a more technical [project information site](https://connect.strategyunitwm.nhs.uk/nhp/project_information/) 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](https://digital.nhs.uk/services/data-access-request-service-dars/dars-products-and-services/data-set-catalogue/hospital-episode-statistics) data which goes through extensive processing, as detailed in the [nhp_data repository](https://github.com/The-Strategy-Unit/nhp_data).
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](https://github.com/The-Strategy-Unit/nhp_model/issues/347) so that interested parties can run the model locally to see how it works.

Prospective users of the model should [contact the Strategy Unit](mailto:strategy.unit@nhs.net) 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](https://future.nhs.uk/NewHospitalProgrammeDigital/browseFolder?fid=53572528&done=OBJChangesSaved)

### 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](https://github.com/The-Strategy-Unit/nhp_model/issues/419).

The model runs using parameters that are set in a [JSON file](#json-schema).

### Running the model using `uv`

This package is built using [`uv`](https://docs.astral.sh/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 .`
1. 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](https://pytest-regressions.readthedocs.io/en/latest/overview.html) 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:

``` sh
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](https://json-schema.org/understanding-json-schema/about) 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`
