Merge pull request #36 from pythonhealthdatascience/dev

Dev

Author: amyheather

README.md

@@ -6,6 +6,8 @@
 [![licence](https://img.shields.io/badge/Licence-MIT-green.svg?labelColor=gray)](https://github.com/pythonhealthdatascience/rap_template_python_des/blob/main/LICENSE)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14622466.svg)](https://doi.org/10.5281/zenodo.14622466)
 [![Tests](https://github.com/pythonhealthdatascience/rap_template_python_des/actions/workflows/tests.yaml/badge.svg)](https://github.com/pythonhealthdatascience/rap_template_python_des/actions/workflows/tests.yaml)
+[![Linting](https://github.com/pythonhealthdatascience/rap_template_python_des/actions/workflows/lint.yaml/badge.svg)](https://github.com/pythonhealthdatascience/rap_template_python_des/actions/workflows/lint.yaml)
+[![ORCID: Heather](https://img.shields.io/badge/ORCID_Amy_Heather-0000--0002--6596--3479-brightgreen)](https://orcid.org/0000-0002-6596-3479)
 
 <br>A template for creating **discrete-event simulation (DES)** models in Python within a **reproducible analytical pipeline (RAP)**. <br><br>
 Click on <kbd>Use this template</kbd> to initialise new repository.<br>
@@ -244,7 +246,8 @@ repo/
 ├── lint.sh               # Bash script to lint all .py and .ipynb files at once
 ├── pyproject.toml        # Metadata for local `simulation/` package
 ├── README.md             # This file! Describes the repository
-└── requirements.txt      # Virtual environment (used by GitHub actions)
+├── requirements.txt      # Virtual environment (used by GitHub actions)
+└── run_notebooks.sh      # Bash script to run all .ipynb from the command line
 ```
 
 <br>
@@ -323,7 +326,7 @@ This repository was developed with thanks to several others sources. These are a
 | Amy Heather, Thomas Monks, Alison Harper, Navonil Mustafee, Andrew Mayne (2025) On the reproducibility of discrete-event simulation studies in health research: an empirical study using open models (https://doi.org/10.48550/arXiv.2501.13137). | `docs/heather_2025.md` |
 | NHS Digital (2024) RAP repository template (https://github.com/NHSDigital/rap-package-template) (MIT Licence) | `simulation/logging.py`<br>`docs/nhs_rap.md` |
 | Sammi Rosser and Dan Chalk (2024) HSMA - the little book of DES (https://github.com/hsma-programme/hsma6_des_book) (MIT Licence) | `simulation/model.py`<br>`notebooks/choosing_cores.ipynb` |
-| Tom Monks (2025) sim-tools: tools to support the Discrete-Event Simulation process in python (https://github.com/TomMonks/sim-tools) (MIT Licence)<br>Who themselves cite Hoad, Robinson, & Davies (2010). Automated selection of the number of replications for a discrete-event simulation (https://www.jstor.org/stable/40926090). | `simulation/model.py`<br>`simulation/replications.py`<br>`notebooks/choosing_replications.ipynb` |
+| Tom Monks (2025) sim-tools: tools to support the Discrete-Event Simulation process in python (https://github.com/TomMonks/sim-tools) (MIT Licence)<br>Who themselves cite Hoad, Robinson, & Davies (2010). Automated selection of the number of replications for a discrete-event simulation (https://www.jstor.org/stable/40926090), and Knuth. D "The Art of Computer Programming" Vol 2. 2nd ed. Page 216. | `simulation/model.py`<br>`simulation/replications.py`<br>`notebooks/choosing_replications.ipynb` |
 | Tom Monks, Alison Harper and Amy Heather (2025) An introduction to Discrete-Event Simulation (DES) using Free and Open Source Software (https://github.com/pythonhealthdatascience/intro-open-sim/tree/main). (MIT Licence) - who themselves also cite Law. Simulation Modeling and Analysis 4th Ed. Pages 14 - 17. | `simulation/model.py` |
 | Tom Monks (2024) [HPDM097 - Making a difference with health data](https://github.com/health-data-science-OR/stochastic_systems) (MIT Licence). | `notebooks/analysis.ipynb`<br>`notebooks/choosing_replications.ipynb`<br>`notebooks/choosing_warmup.ipynb` |
 | Monks T and Harper A. Improving the usability of open health service delivery simulation models using Python and web apps (https://doi.org/10.3310/nihropenres.13467.2) [version 2; peer review: 3 approved]. NIHR Open Res 2023, 3:48.<br>Who themselves cite a [Stack Overflow](https://stackoverflow.com/questions/59406167/plotly-how-to-filter-a-pandas-dataframe-using-a-dropdown-menu) post. | `notebooks/analysis.ipynb` |

docs/heather_2025.md

@@ -16,7 +16,7 @@ As part of the project STARS (Sharing Tools and Artefacts for Reproducible Simul
 | Control randomness | ✅ | - |
 | **Outputs** |
 | Include code to calculate all required model outputs (⭐) | ✅ | - |
-| Include code to generate the tables, figures, and other reported results (⭐) | N/A | No publication. |
+| Include code to generate the tables, figures, and other reported results (⭐) | ✅ | Includes some examples (in `analysis.ipynb`) where these are generated. |
 
 ## Recommendations to support troubleshooting and reuse
 
@@ -30,7 +30,7 @@ As part of the project STARS (Sharing Tools and Artefacts for Reproducible Simul
 | Comment sufficiently | ✅ | - |
 | Ensure clarity and consistency in the model results tables | ✅ | - |
 | Include run instructions | ✅ | - |
-| State run times and machine specifications | ✅ | In `REAME.md` and `.ipynb` files |
+| State run times and machine specifications | ✅ | In `README.md` and `.ipynb` files. |
 | **Functionality** |
 | Optimise model run time | ✅ | Provides option of parallel processing. |
 | Save outputs to a file | ✅ | Includes some examples (in `analysis.ipynb`) where outputs are saved. |

docs/hsma_changes.md

@@ -233,6 +233,38 @@ if self.env.now > g.warm_up_period:
     )
 ```
 
+## Corrections to the time with the resource
+
+In the HSMA model, `time_with_nurse` is used for tracking resource utilisation. We include this approach, but with two corrections.
+
+**Correction #1**: Towards the end of the simulation, simply recording the sampled time with the nurse will overestimate utilisation, if this would go beyond the simulation end. In which case, we save either the time with the nurse, or the time remaining in the simulation - whichever is smallest.
+
+```
+remaining_time = (
+    self.param.warm_up_period +
+    self.param.data_collection_period) - self.env.now
+self.nurse_time_used += min(
+    patient.time_with_nurse, remaining_time)
+```
+
+**Correction #2**: If a warm-up period is included, the utilisation will be underestimated, as it won't include patients who start their consultation with the nurse in the warm-up and finish it in the data collection period. In these cases, we use an attribute `nurse_time_used_correction` to record the time that would fall in the data collection period, and add this to the `time_with_nurse`.
+
+```
+remaining_warmup = self.param.warm_up_period - self.env.now
+if remaining_warmup > 0:
+    time_exceeding_warmup = (patient.time_with_nurse -
+                                remaining_warmup)
+    if time_exceeding_warmup > 0:
+        self.nurse_time_used_correction += min(
+            time_exceeding_warmup,
+            self.param.data_collection_period)
+
+...
+
+# When resetting values after warm-up end...
+self.nurse_time_used += self.nurse_time_used_correction
+```
+
 ## Extra features
 
 ### Prevent addition of new attributes to the parameter class
@@ -307,6 +339,14 @@ It can also be applied to other results dataframes if desired.
 
 The `SimLogger` class will generate logs which can be saved to a file or printed to a console. This includes information on when patients arrive and are seen. This can be helpful for understanding the simulation or when debugging.
 
+### Selecting the length of the warm-up period
+
+The `choosing_warmup.ipynb` notebook includes a function which can be used to help choose an appropriate length for the warm-up period.
+
+### Selecting the number of replications to use
+
+The `replications.py` contains various functions and classes which can be used to help choose an appropriate number of replications to run, as explored in `choosing_replications.ipynb`.
+
 ### Other minor changes
 
 There are a few smaller changes to the model with minimal impact on function. These include:

docs/nhs_rap.md

@@ -31,7 +31,7 @@ Meeting all of the above requirements, plus:
 | Code is well-organised following [standard directory format](https://nhsdigital.github.io/rap-community-of-practice/training_resources/python/project-structure-and-packaging/). | ✅ | - |
 | [Reusable functions](https://nhsdigital.github.io/rap-community-of-practice/training_resources/python/python-functions/) and/or classes are used where appropriate. | ✅ | - |
 | Code adheres to agreed coding standards (e.g PEP8, [style guide for Pyspark](https://nhsdigital.github.io/rap-community-of-practice/training_resources/pyspark/pyspark-style-guide/)). | ✅ | - |
-| Pipeline includes a testing framework ([unit tests](https://nhsdigital.github.io/rap-community-of-practice/training_resources/python/unit-testing/), [back tests](https://nhsdigital.github.io/rap-community-of-practice/training_resources/python/backtesting/)). | ✅ | `tests/` contains unit and back tests |
+| Pipeline includes a testing framework ([unit tests](https://nhsdigital.github.io/rap-community-of-practice/training_resources/python/unit-testing/), [back tests](https://nhsdigital.github.io/rap-community-of-practice/training_resources/python/backtesting/)). | ✅ | `tests/` contains unit, functional and back tests. |
 | Repository includes dependency information (e.g. [requirements.txt](https://pip.pypa.io/en/stable/user_guide/#requirements-files), [PipFile](https://github.com/pypa/pipfile/blob/main/README.rst), [environment.yml](https://nhsdigital.github.io/rap-community-of-practice/training_resources/python/virtual-environments/conda/)). | ✅ | `environment.yaml` |
 | [Logs](https://nhsdigital.github.io/rap-community-of-practice/training_resources/python/logging-and-error-handling/) are automatically recorded by the pipeline to ensure outputs are as expected. | ✅ | - |
 | Data is handled and output in a [Tidy data format](https://medium.com/@kimrodrikwa/untidy-data-a90b6e3ebe4c). | ✅ | Meets the requirements of tidy data (each variable forms a column, each observation forms a row, each type of observational unit forms a table). |
@@ -47,4 +47,4 @@ Meeting all of the above requirements, plus:
 | Code is fully [packaged](https://packaging.python.org/en/latest/). | ✅ | With thanks to [Joshua Cook](https://joshuacook.netlify.app/posts/2024-07-27_python-data-analysis-org/), whose blog post I used to help me structure this analysis as a package. |
 | Repository automatically runs tests etc. via CI/CD or a different integration/deployment tool e.g. [GitHub Actions](https://docs.github.com/en/actions). | ✅ | `.github/workflows/tests.yaml` |
 | Process runs based on event-based triggers (e.g., new data in database) or on a schedule. | N/A | - |
-| Changes to the RAP are clearly signposted. E.g. a changelog in the package, releases etc. (See gov.uk info on [Semantic Versioning](https://github.com/alphagov/govuk-frontend/blob/main/docs/contributing/versioning.md)). | ✅ | `CHANGELOG.md` and GitHub releases |
+| Changes to the RAP are clearly signposted. E.g. a changelog in the package, releases etc. (See gov.uk info on [Semantic Versioning](https://github.com/alphagov/govuk-frontend/blob/main/docs/contributing/versioning.md)). | ✅ | `CHANGELOG.md` and GitHub releases. |