Renal capacity model

Repository with 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).

⚠️ Please note that the code in this repository is still in development

Installation

This project was created with uv. Although not essential, the instructions will assume you have this installed.

To install the package:

1. Clone the repository to your local machine. Open the repository.
2. Run uv pip install -e .

Setting model configuration

Once installed, set the configuration for your model run in config.py. Note that the default values in config are the national values, which are very large - it will take a long time to run unless you amend this.

Regional users of the model will be provided with a Renal Modelling Input Excel file.

Running the model (experimental version)

National model

Run the model using uv run -m renal_capacity_model.main. This runs a full trial using national values, unless config.py has been amended. Note that the size of the national model is very large and will take several hours to complete.

To run a single model run using the national values, use uv run -m renal_capacity_model.model. Note that this defaults to not initialising the prevalent patients.

Regional model using input Excel file

1. Save your input Excel file on your local machine. We suggest creating a data folder in the root of the renal-capacity-model project directory and saving it there.
2. Run the full trial using uv run -m renal_capacity_model.main --input_filepath path/to/excel_file

Running the model (validation version)

National model

Run the validation version of the national model with uv run python tests/validation/national_validation.py. Ensure that you have not changed any values in config.py to use the default national values.

Regional model using input Excel file

1. Save your input Excel file on your local machine. We suggest creating a data folder in the root of the renal-capacity-model project directory and saving it there.
2. Run the full trial with validation values using uv run -m renal_capacity_model.main --input_filepath path/to/excel_file --validation

Information for developers

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