Merge pull request #34 from pythonhealthdatascience/dev

Dev

Author: amyheather

CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Dates formatted as YYYY-MM-DD as per [ISO standard](https://www.iso.org/iso-8601-date-and-time-format.html).
 
+## v1.0.0 - 2026-02-11
+
+Stable release, with minor changes from 0.2.0 including quality assurance documentation, bash script simplification, and a security fix.
+
+### Added
+
+* Add `docs/quality_assurance.md`.
+
+### Changed
+
+* Simplified `run_notebooks.sh`.
+
+### Fixed
+
+* Upgraded `nbconvert` (security issue with 7.16.6 - upgraded to 7.17.0).
+
 ## v0.2.0 - 2025-11-06
 
 This release has some small additions (e.g., data dictionary, coverage), alongside lots of refactoring and changes (e.g., parameters in JSON, using `DistributionRegistry`, renaming repository, using updated version of `sim-tools`).

CITATION.cff

@@ -25,5 +25,5 @@ abstract: >-
   Reproducible analytical pipeline (RAP) for python discrete-event simulation
   (DES) implementing the Stroke Capacity Planning Model from Monks et al. 2016.
 license: MIT
-version: '0.2.0'
-date-released: '2025-11-06'
+version: '1.0.0'
+date-released: '2026-02-11'

README.md

@@ -125,7 +125,7 @@ From this repository:
 
 <details><summary><b>Run time and machine specification</b></summary>
 
-The run time for this analysis (`notebooks/analysis.ipynb`) is 10 seconds. This was on an Intel Core i7-12700H, 32GB RAM, Ubuntu 24.04.1.
+The run time for this analysis (`notebooks/analysis.ipynb`) is 38 seconds. This was on an Intel Core i7-12700H, 32GB RAM, Ubuntu 24.04.1.
 
 The other notebooks generate results for tests and illustrate other functionality (e.g. importing parameters from csv, running with logs), and these just take a second or two.
 

docs/quality_assurance.md

@@ -0,0 +1,31 @@
+# Quality Assurance (QA)
+
+## Roles and responsibilities
+
+**Analyst:** Amy Heather (developed the model and implemented the analysis).
+
+**Assurer/Approver:** Tom Monks (provided independent review proportionate to a small teaching example).
+
+## QA when scoping the project
+
+Scoping was agreed verbally between analyst and assurer: replicate the stroke capacity model from [Monks et al. 2016](https://doi.org/10.1186/s12913-016-1789-4) using SimPy. No formal written scoping document was produced, which would be expected for larger or higher‑risk work, but was judged unnecessary here.
+
+No explicit QA plan (who, what, how much) was written at the outset; this document provides a retrospective QA summary and lessons learned for future projects.
+
+## QA when designing the analysis
+
+The analytical approach was simply to replicate the model as described, without introducing any new structural design choices for the model itself. Any decisions were limited to code organisation, which was intentionally implemented as a modular package.
+
+Verification and validation strategy was not agreed in advance but was developed iteratively during the analysis as issues and checks were identified.
+
+Design decisions were not recorded in a separate design document; for future models, capturing key decisions in a short design or analysis‑plan file would be preferable.
+
+## QA when performing the analysis
+
+Verification and validation activities were carried out during development, and checked in a [summary GitHub issue](https://github.com/pythonhealthdatascience/pydesrap_stroke/issues/27) (serving as part of the QA log). Checks were proportionate to purpose of the model (replication, and as an example for training materials).
+
+Assurance of code and workflows was ensured by following the [STARS Reproducibility Recommendations](https://doi.org/10.1080/17477778.2025.2552177) and the [NHS Levels of RAP Framework](https://nhsdigital.github.io/rap-community-of-practice/introduction_to_RAP/levels_of_RAP/).
+
+Code is documented with docstrings and comments to aid understanding and reuse. User and technical documentation are currently provided via the [DES RAP Book](https://github.com/pythonhealthdatascience/des_rap_book). To avoid duplication of this material, the repository does not have it's own standalone user instructions or detailed technical description of the model structure, which would be expected for a model in practice.
+
+GitHub issues act as an informal QA plan and log; for future projects, a more explicit QA project board and short summary of decisions and changes would strengthen the audit trail.

docs/heather_2025.md …stars_reproducibility_recommendations.mddocs/heather_2025.md renamed to docs/stars_reproducibility_recommendations.md docs/heather_2025.md renamed to docs/stars_reproducibility_recommendations.md

@@ -1,6 +1,10 @@
-# Reproducibility recommendations from Heather et al. 2025
+# STARS Reproducibility Recommendations
 
-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.
+As part of the project STARS (Sharing Tools and Artefacts for Reproducible Simulations), a series of computational reproducibility assessments were conducted and described in:
+
+> Heather, A., Monks, T., Harper, A., Mustafee, N., & Mayne, A. (2025). On the reproducibility of discrete-event simulation studies in health research: an empirical study using open models. Journal of Simulation. https://doi.org/10.1080/17477778.2025.2552177.
+
+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 the paper.
 
 ## Recommendations to support reproduction
 

environment.yaml

@@ -5,7 +5,7 @@ dependencies:
   - ipykernel=6.29.5
   - jinja2=3.1.5
   - joblib=1.4.2
-  - nbconvert=7.16.6
+  - nbconvert=7.17.0
   - nbformat=5.10.4
   - nbqa=1.9.0
   - numpy=2.2.2

notebooks/analysis.ipynb

@@ -5641,7 +5641,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Notebook run time: 0m 14s\n"
+      "Notebook run time: 0m 38s\n"
      ]
     }
    ],
@@ -5656,22 +5656,8 @@
   }
  ],
  "metadata": {
-  "kernelspec": {
-   "display_name": "pydesrapstroke",
-   "language": "python",
-   "name": "python3"
-  },
   "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.13.1"
+   "name": "python"
   }
  },
  "nbformat": 4,

notebooks/generate_exp_results.ipynb

@@ -375,7 +375,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Notebook run time: 0m 0s\n"
+      "Notebook run time: 0m 1s\n"
      ]
     }
    ],
@@ -390,22 +390,8 @@
   }
  ],
  "metadata": {
-  "kernelspec": {
-   "display_name": "pydesrapstroke",
-   "language": "python",
-   "name": "python3"
-  },
   "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.13.1"
+   "name": "python"
   }
  },
  "nbformat": 4,

notebooks/logs.ipynb

@@ -88,8 +88,8 @@
       "                                            \u001b[32m'other'\u001b[0m: \u001b[1;35mDiscrete\u001b[0m\u001b[1m(\u001b[0m\u001b[33mvalues\u001b[0m=\u001b[1m[\u001b[0m\u001b[32m'esd'\u001b[0m, \u001b[32m'other'\u001b[0m\u001b[1m]\u001b[0m, \u001b[33mfreq\u001b[0m=\u001b[1m[\u001b[0m\u001b[1;36m0.13\u001b[0m, \u001b[1;36m0.88\u001b[0m\u001b[1m]\u001b[0m\u001b[1m)\u001b[0m,         \n",
       "                                            \u001b[32m'stroke'\u001b[0m: \u001b[1;35mDiscrete\u001b[0m\u001b[1m(\u001b[0m\u001b[33mvalues\u001b[0m=\u001b[1m[\u001b[0m\u001b[32m'esd'\u001b[0m, \u001b[32m'other'\u001b[0m\u001b[1m]\u001b[0m, \u001b[33mfreq\u001b[0m=\u001b[1m[\u001b[0m\u001b[1;36m0.4\u001b[0m, \u001b[1;36m0.6\u001b[0m\u001b[1m]\u001b[0m\u001b[1m)\u001b[0m,          \n",
       "                                            \u001b[32m'tia'\u001b[0m: \u001b[1;35mDiscrete\u001b[0m\u001b[1m(\u001b[0m\u001b[33mvalues\u001b[0m=\u001b[1m[\u001b[0m\u001b[32m'other'\u001b[0m\u001b[1m]\u001b[0m, \u001b[33mfreq\u001b[0m=\u001b[1m[\u001b[0m\u001b[1;36m1.0\u001b[0m\u001b[1m]\u001b[0m\u001b[1m)\u001b[0m\u001b[1m}\u001b[0m\u001b[1m}\u001b[0m\u001b[1m}\u001b[0m,                      \n",
-      "    \u001b[32m'env'\u001b[0m: \u001b[1m<\u001b[0m\u001b[1;95msimpy.core.Environment\u001b[0m\u001b[39m object at \u001b[0m\u001b[1;36m0x73560a6756a0\u001b[0m\u001b[39m>,\u001b[0m                                                      \n",
-      "\u001b[39m    \u001b[0m\u001b[32m'param'\u001b[0m\u001b[39m: <simulation.parameters.Param object at \u001b[0m\u001b[1;36m0x7356cadaeba0\u001b[0m\u001b[1m>\u001b[0m,                                               \n",
+      "    \u001b[32m'env'\u001b[0m: \u001b[1m<\u001b[0m\u001b[1;95msimpy.core.Environment\u001b[0m\u001b[39m object at \u001b[0m\u001b[1;36m0x7e9e65329d30\u001b[0m\u001b[39m>,\u001b[0m                                                      \n",
+      "\u001b[39m    \u001b[0m\u001b[32m'param'\u001b[0m\u001b[39m: <simulation.parameters.Param object at \u001b[0m\u001b[1;36m0x7e9f3c29ef90\u001b[0m\u001b[1m>\u001b[0m,                                               \n",
       "    \u001b[32m'patients'\u001b[0m: \u001b[1m[\u001b[0m\u001b[1m]\u001b[0m,                                                                                                \n",
       "    \u001b[32m'rehab_occupancy'\u001b[0m: \u001b[1;36m0\u001b[0m,                                                                                          \n",
       "    \u001b[32m'run_number'\u001b[0m: \u001b[1;36m0\u001b[0m\u001b[1m}\u001b[0m                                                                                               \n"
@@ -204,7 +204,7 @@
       "                       \u001b[32m'rehab_routing_tia'\u001b[0m: \u001b[1m{\u001b[0m   \u001b[32m'class_name'\u001b[0m: \u001b[32m'DiscreteEmpirical'\u001b[0m,                                 \n",
       "                                                \u001b[32m'params'\u001b[0m: \u001b[1m{\u001b[0m   \u001b[32m'freq'\u001b[0m: \u001b[1m[\u001b[0m\u001b[1;36m1.0\u001b[0m\u001b[1m]\u001b[0m,                                       \n",
       "                                                              \u001b[32m'values'\u001b[0m: \u001b[1m[\u001b[0m   \u001b[32m'other'\u001b[0m\u001b[1m]\u001b[0m\u001b[1m}\u001b[0m\u001b[1m}\u001b[0m\u001b[1m}\u001b[0m,                           \n",
-      "    \u001b[32m'logger'\u001b[0m: \u001b[1m<\u001b[0m\u001b[1;95msimulation.logging.SimLogger\u001b[0m\u001b[39m object at \u001b[0m\u001b[1;36m0x73560a8eb0e0\u001b[0m\u001b[1m>\u001b[0m,                                             \n",
+      "    \u001b[32m'logger'\u001b[0m: \u001b[1m<\u001b[0m\u001b[1;95msimulation.logging.SimLogger\u001b[0m\u001b[39m object at \u001b[0m\u001b[1;36m0x7e9e65587770\u001b[0m\u001b[1m>\u001b[0m,                                             \n",
       "    \u001b[32m'number_of_runs'\u001b[0m: \u001b[1;36m150\u001b[0m,                                                                                         \n",
       "    \u001b[32m'warm_up_period'\u001b[0m: \u001b[1;36m15\u001b[0m\u001b[1m}\u001b[0m                                                                                          \n"
      ]
@@ -1932,7 +1932,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Notebook run time: 0m 0s\n"
+      "Notebook run time: 0m 1s\n"
      ]
     }
    ],
@@ -1947,22 +1947,8 @@
   }
  ],
  "metadata": {
-  "kernelspec": {
-   "display_name": "pydesrapstroke",
-   "language": "python",
-   "name": "python3"
-  },
   "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.13.1"
+   "name": "python"
   }
  },
  "nbformat": 4,