Merge pull request #12 from pythonhealthdatascience/dev

Dev

Author: amyheather

.github/workflows/lint.yaml

@@ -0,0 +1,34 @@
+# This file will lint the specified files/directories.
+
+name: lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  lint:
+      runs-on: ubuntu-latest
+      steps:
+
+        - name: Check out repository
+          uses: actions/checkout@v4
+
+        - name: Install python and dependencies
+          uses: actions/setup-python@v4
+          with:
+            python-version: '3.13'
+            cache: 'pip'
+        - run: pip install -r requirements.txt
+
+        - name: Lint model code
+          run: |
+            flake8 ./simulation
+            pylint ./simulation
+
+        - name: Lint tests
+          run: |
+            flake8 ./tests
+            pylint ./tests

.github/workflows/tests.yaml

@@ -1,11 +1,13 @@
-# This file runs the tests in `tests/` with every push to GitHub
+# This file runs the tests in `tests/`
 # They will run in parallel, and run on three operating systems:
 # Ubuntu, Windows and Mac.
 
 name: tests
 
 on:
   push:
+    branches: [main]
+  pull_request:
   workflow_dispatch:
 
 jobs:

.pylintrc

@@ -0,0 +1,4 @@
+[MESSAGES CONTROL]
+disable=
+    too-few-public-methods,
+    too-many-instance-attributes

CITATION.cff

@@ -3,8 +3,7 @@
 
 cff-version: 1.2.0
 title: >-
-  Simple Reproducible Python Discrete-Event Simulation (DES)
-  Template
+  Python DES RAP Template
 message: >-
   If you use this software, please cite it using the
   metadata from this file.
@@ -18,8 +17,8 @@ authors:
 repository-code: >-
   https://github.com/pythonhealthdatascience/rap_template_python_des
 abstract: >-
-  Template reproducible analytical pipeline (RAP) for simple
-  python DES model.
+  A template for creating discrete-event simulation (DES) models in Python
+  within a reproducible analytical pipeline (RAP).
 license: MIT
 # TODO: Manually update with each GitHub release
 version: '0.1.0'

README.md

@@ -1,13 +1,14 @@
 <div align="center">
 
-# Simple Reproducible Python<br>Discrete-Event Simulation (DES) Template
+# Python DES RAP Template
 
 [![python](https://img.shields.io/badge/-Python_3.13-306998?logo=python&logoColor=white)](https://www.python.org/)
 [![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)
 
-A simple template for creating DES models in Python, within a **reproducible analytical pipeline (RAP)** <br>
+<br>A template for creating **discrete-event simulation (DES)** models in Python<br>
+within a **reproducible analytical pipeline (RAP)**. <br><br>
 Click on <kbd>Use this template</kbd> to initialise new repository.<br>
 A `README` template is provided at the **end of this file**.
 
@@ -41,9 +42,9 @@ This repository provides a template for building discrete-event simulation (DES)
 ♻️ **Reproducible:** This template is designed to function as a RAP. It adheres to reproducibility recommendations from:
 
 * ["Levels of RAP" framework](https://nhsdigital.github.io/rap-community-of-practice/introduction_to_RAP/levels_of_RAP/) from the NHS RAP Community of Practice (`docs/nhs_rap.md`).
-* Recommendations from [Heather et al. 2025](TODO:ADDLINK) "*On the reproducibility of discrete-event simulation studies in health research: an empirical study using open models*" (`docs/heather_2025.md`).
+* Recommendations from [Heather et al. 2025](https://doi.org/10.48550/arXiv.2501.13137) "*On the reproducibility of discrete-event simulation studies in health research: an empirical study using open models*" (`docs/heather_2025.md`).
 
-🚀 **Extendable:** This template adapts from and complements material from Sammi Rosser and Dan Chalk (2024) ["HSMA - the little book of DES"](https://github.com/hsma-programme/hsma6_des_book). The book includes additional advanced features that can be used to extend the model in this template, including:
+🚀 **Extendable:** This template adapts from Sammi Rosser and Dan Chalk (2024) ["HSMA - the little book of DES"](https://github.com/hsma-programme/hsma6_des_book). The book includes additional advanced features that can be used to extend the model in this template, including:
 
 * Multiple activities
 * Branching paths
@@ -149,6 +150,12 @@ To run tests, ensure environment is active and located in main directory (i.e. p
 pytest
 ```
 
+To run tests in parallel -
+
+```
+pytest -n auto
+```
+
 The repository contains a GitHub action `tests.yaml` which will automatically run tests with new commits to GitHub. This is continuous integration, helping to catch bugs early and keep the code stable. It will run the tests on three operating systems: Ubuntu, Windows and Mac.
 
 If you have changed the model behaviour, you may wish to amend, remove or write new tests.
@@ -184,10 +191,12 @@ This section describes the purposes of each class in the simulation.
     * `generate_patient_arrivals()` to handle patient creation, then sending them on to `attend_clinic()`.
     * `interval_audit()` to record utilisation and wait times at specified intervals during the simulation.
 
-**Trial Class Usage:**
+**Runner Class Usage:**
+
+Having set up `experiment = Runner()`...
 
-* **Single Run:** Use `trial.run_single()` to execute a single model run.
-* **Multiple Runs:** Use `trial.run_trial()` to perform multiple replications of the model.
+* **Single Run:** Use `experiment.run_single()` to execute a single model run.
+* **Multiple Runs:** Use `experiment.run_reps()` to perform multiple replications of the model.
 
 <br>
 
@@ -210,6 +219,7 @@ repo/
 ├── simulation/           # Local package containing code for the DES model
 ├── tests/                # Unit and back testing of the DES model
 ├── .gitignore            # Untracked files
+├── .pylintrc             # Pylint settings
 ├── CHANGELOG.md          # Describes changes between releases
 ├── CITATION.cff          # How to cite the repository
 ├── CONTRIBUTING.md       # Contribution instructions
@@ -230,6 +240,8 @@ The overall run time will vary depending on how the template model is used. A fe
 * `choosing_parameters.ipynb` - 22s
 * `generate_exp_results.ipynb` - 0s
 
+<!--TODO: Add test times -->
+
 These times were obtained on an Intel Core i7-12700H with 32GB RAM running Ubuntu 24.04.1 Linux. 
 
 <br>

docs/heather_2025.md

@@ -1,6 +1,6 @@
 # Reproducibility recommendations from Heather et al. 2025
 
-As part of the project STARS (Sharing Tools and Artefacts for Reproducible Simulations), a series of computational reproducibility assessments were conducted by Heather et al. 2025 (**TODO: add DOI of pre-print**). From these, several recommendations were shared to support reproducibility of healthcare discrete-event simulation (DES) models. These are copied below. Those marked with a star (⭐) were identified as having the greatest impact in Heather et al. 2025.
+As part of the project STARS (Sharing Tools and Artefacts for Reproducible Simulations), a series of computational reproducibility assessments were conducted by [Heather et al. 2025](https://doi.org/10.48550/arXiv.2501.13137). From these, several recommendations were shared to support reproducibility of healthcare discrete-event simulation (DES) models. These are copied below. Those marked with a star (⭐) were identified as having the greatest impact in Heather et al. 2025.
 
 ## Recommendations to support reproduction
 

docs/hsma_changes.md

@@ -132,9 +132,9 @@ param.patient_inter = 10
 model = Model(param)
 ```
 
-## Saving trial results
+## Saving replication results
 
-To save trial-level results in the HSMA models, an empty dataframe is initialised during the __init__ method of the `Trial` class.
+To save results from each run in the HSMA models, an empty dataframe is initialised during the __init__ method of the `Trial` class (equivalent to the `Runner` class in this template).
 
 ```
 self.df_trial_results = pd.DataFrame()
@@ -164,7 +164,7 @@ In the template, results are instead saved as a dictionary into a list as the ru
 Also, some of the calculations have been performed directly during the `run_single()` method, instead of from a seperate method `calculate_run_results()`. This is to help simplify the code, as it makes clear how each metric was calculated in one place, rather than needing to refer elsewhere.
 
 ```
-trial_results = {
+run_results = {
     'run_number': run,
     'scenario': self.param.scenario_name,
     'arrivals': len(patient_results),
@@ -176,7 +176,7 @@ trial_results = {
 
 ...
 
-self.trial_results_df = pd.DataFrame(trial_results_list)
+self.run_results_df = pd.DataFrame(run_results_list)
 ```
 
 ## Extra features

docs/nhs_rap.md

@@ -15,7 +15,7 @@ RAP fundamentals offering resilience against future change.
 | Data produced by code in an open-source language (e.g., Python, R, SQL). | ✅ | Python |
 | Code is version controlled (see [Git basics](https://nhsdigital.github.io/rap-community-of-practice/training_resources/git/introduction-to-git/) and [using Git collaboratively](https://nhsdigital.github.io/rap-community-of-practice/training_resources/git/using-git-collaboratively/) guides). | ✅ | [GitHub](https://github.com/pythonhealthdatascience/rap_template_python_des/) |
 | Repository includes a README.md file (or equivalent) that clearly details steps a user must follow to reproduce the code (use [NHS Open Source Policy section on Readmes](https://github.com/nhsx/open-source-policy/blob/main/open-source-policy.md#b-readmes) as a guide). | ✅ | - |
-| Code has been [peer reviewed](https://nhsdigital.github.io/rap-community-of-practice/implementing_RAP/workflow/code-review/). | ❌ | **TODO: Have code peer reviewed, record on GitHub - this would typically be through working on branches and then reviewing code in a pull request before it is merged into the already approved code. Could create empty branch.** |
+| Code has been [peer reviewed](https://nhsdigital.github.io/rap-community-of-practice/implementing_RAP/workflow/code-review/). | ✅ | Peer reviewed by Tom Monks |
 | Code is [published in the open](https://nhsdigital.github.io/rap-community-of-practice/implementing_RAP/publishing_code/how-to-publish-your-code-in-the-open/) and linked to & from accompanying publication (if relevant). | ✅ & N/A | Shared openly. No publication. |
 
 ## 🥈 Silver