Renal capacity model

This repository contains the Python code for the Renal Capacity Model, an open source implementation of the Discrete Event Simulation (DES) Renal Services model created in collaboration with the Midlands Renal Operational Delivery Network (MRODN).

The code in this repository has been geared towards working with input Excel files that are adapted for specific regions in England. To obtain an input Excel file for your region, please contact the Strategy Unit. An example input and output file for a fictional region is provided in the data folder.

The default config contains the values for the national version of the model. However this has not yet been validated and documentation is sparse. We will provide further details on how to run the national version of the model, or adapt the model to be used without an input Excel file, in due course.

How to use this package using an input Excel file

Data preparation

1. Clone a copy of the repository to your local machine.
2. Put your Renal_Modelling_Input_File - REGION.xlsx and Renal_Modelling_Output_File - REGION.xlsx in the data folder.

Your repository structure should look like the below:

.
├── data/
│   ├── Renal_Modelling_Input_File - REGION.xlsx
│   └── Renal_Modelling_Output_File - REGION.xlsx
├── reference/
│   ├── ttgf_cadTx_initialisation.csv
│   ├── ttgf_cadTx.csv
│   └── ...
├── renal_capacity_model/
│   ├── __init__.py
│   ├── config_values.py
│   ├── config.py
│   └── ...
├── tests/
│   └── ...
├── .gitignore
├── ...
├── README.md
└── uv.lock

Running the model using uv

Our preferred tool for dependency management is uv. If using this tool:

1. Run the model using uv run -m renal_capacity_model.main --input_filepath 'data/Renal_Modelling_Input_File - REGION.xlsx'

Running the model without uv

1. Open the repository folder. Install the package using pip install .
2. Run the model using python -m renal_capacity_model.main --input_filepath 'data/Renal_Modelling_Input_File - REGION.xlsx'

Viewing model results

Your results will be saved in a results folder, in a subfolder with the date and time of the model run. For example:

├── results/
    └── 20260101-1201/
        ├── Input - REGION_20260101-1201.xlsx
        └── Output - REGION_20260101-1201.xlsx

Example model run with fictional region

Example input and output files for a fictional region are provided in the data folder. You can run the model using the fictional region input file to see how the model works and what the output looks like. Run the model using uv run -m renal_capacity_model.main --input_filepath 'data/Renal_Modelling_Input_File - Fictional Region.xlsx'.

National model

Run the model at national level using uv run -m renal_capacity_model.main. This runs a full trial using national values, stored in config_values.py. Note that the size of the national model is very large and will take several hours to complete. We also have not yet validated the national version of the model.

Information for developers

Running the model (validation version)

Run the full trial with validation values instead of experimental values using uv run -m renal_capacity_model.main --input_filepath path/to/excel_file --validation. This compares historical data from the UK Renal Registry (UKRR) from 2010-2023 with modelled results using a baseline year of 2010.

Testing

There are two types of tests for the model:

• Unit tests, which run automatically as part of the pytest testing suite. These check the behaviour of the individual elements of code to ensure they behave as expected using strict testing criteria.
• Validation tests, which are excluded from the pytest testing suite. These are manually run and require users to view results and use their own judgment to check validity.

To run the unit tests:

• uv run pytest

Check code unit testing coverage using:

• uv run coverage run -m pytest

View the code unit testing coverage report using:

• uv run coverage report

To run the validation tests:

• uv run tests/validation/validation_test_file.py

Contributing to this repository

We have set up some linting tools to help maintain good coding practices. To use these:

• uv sync --all-extras to install the development-only packages
• uv run pyright to run typing checks with pyright
• uv run ruff check to run linting checks with ruff
• uv run ruff format to run formatting checks with ruff