Merge pull request #148 from pythonhealthdatascience/dev

Dev

Author: amyheather

CHANGELOG.md

@@ -5,6 +5,19 @@ 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).
 
+## v0.4.0 - 2026-01-06
+
+### Added
+
+* Quality assurance page.
+* Date each page was last updated (based on commits to main, generated using bash script in GitHub action).
+
+### Changed
+
+* Addressed peer review feedback from Nav Mustafee ([#130](https://github.com/pythonhealthdatascience/des_rap_book/issues/130)).
+* Addressed peer review feedback from Fatemeh Alidoost ([#134](https://github.com/pythonhealthdatascience/des_rap_book/issues/134), [#144](https://github.com/pythonhealthdatascience/des_rap_book/issues/144) and [#146](https://github.com/pythonhealthdatascience/des_rap_book/issues/146)).
+* Restructured the website so it has a homepage, a dedicated section with step-by-step tutorial, but then separate sections with background information. Now has top navbar with banner, for hopefully more professional appearance and easier navigation.
+
 ## v0.3.0 - 2025-11-06
 
 This release adds new pages on the mathematical proof of correctness, discrete-event simulation, and conclusions/feedback, as well as template repositories for structuring work as a package. It fixes the calculation of R time-weighted measures, updates the Python approach to determining warm-up length, and extends all pages to cover all performance metrics. Numerous smaller improvements are also included.

CITATION.cff

@@ -45,5 +45,5 @@ keywords:
   - simmer
   - rap
 license: MIT
-version: '0.3.0'
-date-released: '2025-11-06'
+version: '0.4.0'
+date-released: '2026-01-06'

_brand.yml

@@ -0,0 +1,5 @@
+# _brand.yml
+defaults:
+  bootstrap:
+    defaults:
+      navbar-bg: "#0a4568"

_quarto.yml

@@ -1,5 +1,7 @@
 project:
   type: website
+  pre-render:
+    - bash scripts/make-environment-full.sh
   preview:
     browser: true
   render:
@@ -10,12 +12,15 @@ project:
 
 website:
   title: "DES RAP"
+  site-url: "https://pythonhealthdatascience.github.io/des_rap_book/"
   google-analytics: "G-W2FC4GDHFK"
   cookie-consent: true
   page-navigation: true
+  search: false
   favicon: images/stars_logo_blue.png
   navbar:
     logo: images/stars_logo_white.png
+    collapse-below: "sm"
     left:
       - text: Step-by-step guide
         href: pages/guide/introduction.qmd
@@ -125,7 +130,6 @@ format:
   html:
     theme:
       - cosmo
-      - styles/theme.scss
     toc: true
     toc-depth: 2
     number-sections: false

pages/frameworks/levels_of_rap.qmd

@@ -20,6 +20,13 @@ It is © 2024 Crown Copyright (NHS England), shared under the terms of the [Open
 
 The specific version of the framework copied below is that from commit [2549256](https://github.com/NHSDigital/rap-community-of-practice/commit/2549256498886d6d7ea4cdb736e2a2864c8bb461) (9th September 2024).
 
+::: {.blue}
+
+This book follows the NHS Levels of RAP framework because it is a practical, well-established approach to building full Reproducible Analytical Pipelines in the NHS healthcare setting.
+Although NHS-specific, the principles are still broadly useful for analytical work beyond the NHS.
+
+:::
+
 ### 🥉 Baseline
 
 RAP fundamentals offering resilience against future change.

pages/frameworks/stars_reproducibility.qmd

@@ -20,6 +20,12 @@ As part of the [STARS project](https://pythonhealthdatascience.github.io/stars/)
 
 Those marked with a star (⭐) were identified as having the greatest impact in Heather et al. 2025.
 
+::: {.blue}
+
+This book adopts the STARS reproducibility recommendations because they were developed from a study of real healthcare DES models and focus directly on computational reproducibility. They give a clear, healthcare-specific checklist for making DES studies easier to re-run, troubleshoot, and reuse, which this book follows throughout.
+
+:::
+
 ### Recommendations to support reproduction
 
 ::: {.grey-table}

pages/guide/environment-full.yaml

@@ -0,0 +1,26 @@
+name: des-rap-book
+channels:
+  - conda-forge
+dependencies:
+  - black=25.1.0
+  - flake8=7.3.0
+  - itables=2.5.2
+  - jupyter=1.1.1
+  - openssl=3.3.0
+  - pandas=2.3.1
+  - plotly=6.3.0
+  - pip
+  - pre-commit=4.3.0
+  - pylint=3.3.7
+  - pytest=8.4.1
+  - python=3.11
+  - ruff=0.12.7
+  - simpy=4.1.1
+  - pip:
+    - ansi2html==1.9.2
+    - distfit==1.8.8
+    - jupytext==1.17.2
+    - kaleido==1.1.0
+    - lintquarto==0.5.0
+    - sim-tools==1.0.0
+    - -e .

pages/guide/experiments/full_run.qmd

@@ -23,7 +23,7 @@ date: "2025-10-03T15:54:56+01:00"
 
 As introduced at the start of this book, a **reproducible analytical pipeline (RAP)** is a systematic approach to data analysis and modelling in which every step of the process (end-to-end) is transparent, automated, and repeatable.
 
-![](../intro/rap_resources/rap.png)
+![](/pages/intros/rap_resources/rap.png)
 
 A key aspect RAPs is being able to **run your entire analysis from start to finish with a single command**. For example, one command that can run a simulation model, evaluate the base case, explore scenarios, conduct sensitivity analyses, and produce all tables and figures.
 
@@ -59,6 +59,34 @@ In this example, we'll **focus on a bash script**, since it's often the simplest
 
 <div class="h3-tight"></div>
 
+### What are bash scripts?
+
+A bash script is a plain text file that contains a list of terminal commands, written for the Bash shell, that are executed in order from top to bottom. Instead of typing each command manually, you save them in a `.sh` file and run the script to perform the whole sequence with a single command
+
+### Where to put the script?
+
+Save the script below as `run_notebooks.sh` in the root of your project, alongside the `notebooks/` folder.
+
+::: {.python-content}
+
+This allows the script to loop over `rmarkdown/*.Rmd` without extra path adjustments.
+
+:::
+
+::: {.r-content}
+
+This allows the script to loop over `notebooks/*.ipynb` without extra path adjustments.
+
+:::
+
+### Which terminal to use?
+
+This script is written for Bash.
+
+**Linux** or **macOS** users can just use their normal terminal (which runs Bash or a compatible shell).
+
+On Windows, you'll need to run it from a bash-compatible terminal like **Git Bash**. PowerShell and Command Prompt use different syntax and cannot run `.sh` bash scripts directly.
+
 ### Example script
 
 ::: {.python-content}
@@ -95,7 +123,7 @@ else
 fi
 ```
 
-### Explaining the bash script line by line
+#### Explaining the bash script line by line
 
 ```{.bash}
 #!/usr/bin/env bash
@@ -243,7 +271,19 @@ If a notebook name is given as a command-line argument, it only runs that notebo
 
 ### Running the bash script
 
-Make sure you are in the same directory as the script, then run from the terminal:
+Make sure your terminal is in the project folder (i.e., the place where `run_notebooks.sh` is).
+
+```{.bash}
+# Check where you are
+pwd
+
+# List files; you should see run_notebooks.sh and notebooks/
+ls
+```
+
+If you are not in the correct folder, use `cd path/to/your/project`.
+
+To run the script without making it executable:
 
 ```{.bash}
 bash run_notebooks.sh
@@ -255,7 +295,7 @@ To run a specific notebook:
 bash run_notebooks.sh notebooks/notebook_name.ipynb
 ```
 
-You can make it executable using `chmod +x`. You can then run it directly (without typing `bash` first) from anywhere in your project folder tree (i.e., don't need to be in same directly).
+You can make it executable using `chmod +x`. This means you can then run it directly (without typing `bash` first) from anywhere in your project folder tree (i.e., don't need to be in same directly).
 
 ```{.bash}
 chmod +x run_notebooks.sh

pages/guide/experiments/scenarios.qmd

@@ -38,7 +38,7 @@ This page continues on from: [Parallel processing](../output_analysis/parallel.q
 
 **Required packages:**
 
-These should be available from environment setup in the "Test yourself" section of [Environments](../setup/environment.qmd). 
+These should be available from environment setup on the [Structuring as a package](/pages/guide/setup/package.qmd) page.
 
 ::: {.python-content}
 
@@ -438,7 +438,7 @@ Scenario analysis focuses on a set of pre-defined situations which are plausible
 
 Sensitivity analysis varies one parameter (or a small group of parameters) and assess the impact of small changes in that parameter on outcomes. The purpose is to understand **how uncertainty in the inputs affects the model**, and how **robust** the model is to variation in those inputs.
 
-Sensitivity analysis is an important for model validation (and forms part of "[experimentation validation](../verification_validation/verification_validation.qmd#experimentation-validation)").
+Sensitivity analysis is an important technique for model validation (and forms part of "[experimentation validation](../verification_validation/verification_validation.qmd#experimentation-validation)").
 
 ### Running sensitivity analyses
 

pages/guide/experiments/tables_figures.qmd

@@ -34,7 +34,7 @@ This page uses the results saved on the [Scenario and sensitivity analysis](scen
 
 **Required packages:**
 
-These should be available from environment setup in the "Test yourself" section of [Environments](../setup/environment.qmd). 
+These should be available from environment setup on the [Structuring as a package](/pages/guide/setup/package.qmd) page. 
 
 ::: {.python-content}