Merge pull request #191 from pythonhealthdatascience/dev

Dev

Author: amyheather

CHANGELOG.md

@@ -5,6 +5,26 @@ 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.5.0 - 2026-02-20
+
+This release has lots and lots of changes based on peer review of the book from Nav Mustafee, Rob Challen, Tom Slater and Alison Harper. Other changes include addressing FAIRness requirements, switching R length of warm-up analysis to use intervals, and improving the docker action used to build the site.
+
+### Added
+
+* Addressed FAIRness requirements ([#170](https://github.com/pythonhealthdatascience/des_rap_book/issues/170)), with some larger changes including:
+    * Addition of action which checks all images have alt text.
+    * New "Impact" page.
+
+### Changed
+
+* R length of warm-up now uses intervals.
+* Improved `docker_quarto.yaml` (shorter run-time as doesn't need to restore renv every time build book).
+* Addressed peer review feedback from Nav Mustafee ([#149](https://github.com/pythonhealthdatascience/des_rap_book/issues/149), [#150](https://github.com/pythonhealthdatascience/des_rap_book/issues/150), [#158](https://github.com/pythonhealthdatascience/des_rap_book/issues/158), and [#161](https://github.com/pythonhealthdatascience/des_rap_book/issues/161)).
+* Addressed peer review feedback from Rob Challen ([#152](https://github.com/pythonhealthdatascience/des_rap_book/issues/152) and sub-issues).
+* Addressed peer review feedback from Tom Slater ([#172](https://github.com/pythonhealthdatascience/des_rap_book/issues/172) and sub-issues).
+* Addressed peer review feedback from Alison Harper ([#169](https://github.com/pythonhealthdatascience/des_rap_book/issues/169) and sub-issues).
+* Add all-contributors CLI instructions to `CONTRIBUTING.md`.
+
 ## v0.4.0 - 2026-01-06
 
 ### Added
@@ -129,4 +149,4 @@ This release adds a large number of new pages. It also introduces pre-commits, c
 * Model building section covering:
     * Randomness
     * Entity generation
-    * Entity processing
+    * Entity processing

CITATION.cff

@@ -53,5 +53,5 @@ keywords:
   - simmer
   - rap
 license: MIT
-version: '0.4.0'
-date-released: '2026-01-06'
+version: '0.5.0'
+date-released: '2026-02-20'

pages/guide/environment-full.yaml

@@ -6,7 +6,7 @@ dependencies:
   - flake8=7.3.0
   - itables=2.5.2
   - jupyter=1.1.1
-  - nbconvert-core=7.16.6
+  - nbconvert=7.17.0
   - openssl=3.3.0
   - pandas=2.3.1
   - plotly=6.3.0

pages/guide/further_info/conclusion.qmd

@@ -3,13 +3,6 @@ title: Conclusion
 date: "2025-11-05T11:44:20+00:00"
 ---
 
-<!-- Hide as no python-content or r-content blocks -->
-<style>
-      #quarto-announcement {
-        display: none !important;
-      }
-</style>
-
 <br>
 
 ::: {.pale-blue}
@@ -32,16 +25,32 @@ Remember, these are **examples**, not prescriptions. They're not perfect, and th
 
 **Nurse visit simulation:**
 
+::: {.python-content}
+
 {{< include /html/pydesrapmms.html >}}
 
+:::
+
+::: {.r-content}
+
 {{< include /html/rdesrapmms.html >}}
 
+:::
+
 **Stroke pathway simulation:**
 
+::: {.python-content}
+
 {{< include /html/pydesrapstroke.html >}}
 
+:::
+
+::: {.r-content}
+
 {{< include /html/rdesrapstroke.html >}}
 
+:::
+
 ### Make your own model
 
 The best way to solidify what you've learned is to apply it. When planning your model, remember that a good simulation starts with **conceptual modelling**. As defined in Robinson (2007):

pages/guide/output_analysis/length_warmup.qmd

@@ -1021,8 +1021,6 @@ If you've already built warm-up logic into your model (as we have done), make su
 
 As mentioned above, we have used multiple replications and a long run length. This run length is based on the assumption that our desired simulation run length is 10 days (14400 minutes).
 
-> So far, the model we have been constructing in this book has intentionally had a short duration. This is handy when developing - for example, for looking over the log messages. However, this is unrealistic of an actual simulation of a healthcare system, and will produce great variability (requiring very long warm-up / large number of replications for stable results). From this point onwards, we increase the run time as mentioned.
-
 ```{r}
 #| warning: false
 
@@ -1079,11 +1077,11 @@ ggplotly(plots[[5L]])
 
 ::::
 
-The selection of a warm-up period is **subjective**. The dotted red line shows our suggestion, but this choice could be changed subject to discussion and evaluation of other metrics.
+The selection of a warm-up period is **subjective**. The dotted red line shows our suggestion, but in practice, there is usually a range of sensible warm-up values that give very similar results, and small changes within a reasonable range will often only have a small effect on results, as long as the total run length is long enough.
 
 ::: {.callout-note}
 
-In this example, we assumed a total run length of 10 days (14400 minutes) to illustrate how to determine an appropriate warm-up period. However, for the remainder of this book, we will return to using shorter parameters (i.e., 30 minute warm-up, 40 minute data collection period, 5 replications) to keep examples simple, quick to run, and easy to follow.
+In this example, we assumed a total run length of 10 days (14400 minutes) to illustrate how to determine an appropriate warm-up period. Short model runs, like those we've used so far, are useful during development (e.g., when inspecting log messages), but they produce high variability and are unrealistic of an actual healthcare system. However, for the remainder of this book, we will return to using shorter parameters (i.e., 30 minute warm-up, 40 minute data collection period, 5 replications) to keep examples simple, quick to run, and easy to follow.
 
 :::
 

pages/guide/output_analysis/n_reps.qmd

@@ -31,10 +31,10 @@ This page continues on from: [Replications](replications.qmd).
 
 The following imports are required. These should be available from environment setup on the [Structuring as a package](/pages/guide/setup/package.qmd) page.
 
-Since [Replications](replications.qmd), we have several new imports: functions from `typing` and from `sim_tools.output_analysis`.
-
 ::: {.python-content}
 
+Since [Replications](replications.qmd), we have several new imports: functions from `typing` and from `sim_tools.output_analysis`.
+
 ```{python}
 # For display purposes:
 from IPython.display import HTML
@@ -181,7 +181,7 @@ The `desired_precision` parameter is set to 0.1, which means we are interested i
 
 ::: {.callout-note title="Stopping condition: `desired_precision` and confidence intervals"}
 
-We construct a confidence interval for each performance measure at a chosen confidence level (typically 95%). The interval has a half‑width, which is the margin of error around the estimated mean. The `desired_precision` parameter sets how small this half‑width must be relative to the mean (for example, 0.1 means “within 10% of the mean”).
+We construct a confidence interval for each performance measure at a chosen confidence level (typically 95%). The interval has a half‑width, which is the margin of error around the estimated mean. The `desired_precision` parameter sets how small this half‑width must be relative to the mean (for example, 0.1 means "within 10% of the mean").
 
 The confidence interval method keeps increasing the number of replications until this relative half‑width falls below `desired_precision` (and is above `min_rep`), indicating that additional replications are unlikely to change the estimate by more than the chosen percentage.
 
@@ -508,6 +508,20 @@ plot_replication_ci <- function(
 
 :::
 
+`confidence_interval_method()` runs the model for the specified number of replications, and after each replication it updates a single row that summarises what we know so far about the chosen performance measure. It records the most recent value of the metric, the running average across all completed replications, the standard deviation, and the 95% confidence interval around that average (lower and upper bounds). From this interval it also calculates a relative "half‑width" (how far the upper confidence limit is above the mean, as a proportion of the mean), which is compared to desired_precision to decide when you have run enough replications. The function returns a data frame containing this full sequence of per‑replication summaries, and prints a message when the desired precision is first achieved.
+
+We supply `confidence_interval_method` with three main inputs: the parameters, the performance measure to analyse, and the `desired_precision`. The `desired_precision` parameter is set to 0.1, which means we are interested in identifying when the percentage deviation of the confidence interval from the mean falls **below 10%**.
+
+::: {.callout-note title="Stopping condition: `desired_precision` and confidence intervals"}
+
+We construct a confidence interval for each performance measure at a chosen confidence level (typically 95%). The interval has a half‑width, which is the margin of error around the estimated mean. The `desired_precision` parameter sets how small this half‑width must be relative to the mean (for example, 0.1 means "within 10% of the mean").
+
+The confidence interval method keeps increasing the number of replications until this relative half‑width falls below `desired_precision`, indicating that additional replications are unlikely to change the estimate by more than the chosen percentage.
+
+**Note:** The 10% threshold used is our default, but is relatively arbitrary. We are just using it to help us identify the point where results are stable enough.
+
+::: 
+
 ```{r}
 metrics <- c("mean_wait_time_doctor", "utilisation_doctor",
              "mean_queue_length_doctor", "mean_time_in_system",
@@ -526,6 +540,8 @@ for (m in metrics) {
 }
 ```
 
+`plot_replication_ci()` then takes that data frame and produces a plot showing how the cumulative mean and its confidence interval change as you add more replications, optionally marking the recommended number of replications with a vertical dashed line so you can visually check that the estimates have stabilised.
+
 Click the name of each metric below to view the relevant plot:
 
 ::: {.panel-tabset}
@@ -1451,7 +1467,11 @@ res <- run_replications_algorithm(
 
 # View recommended number of replications
 res$nreps
+```
 
+The algorithm returns the minimum number of replications required for each performance measure to reach the desired precision. In this example, the largest of these values is 19 (for `mean_queue_length_doctor`), so we would use approximately 19 replications for this model overall, to ensure all performance measures meet the target precision.
+
+```{r}
 # View full results table
 res$summary_table |>
   kable() |>

pages/guide/sharing/archive.qmd

@@ -137,7 +137,7 @@ Whilst platforms like GitHub are great for sharing code, they provide no guarant
 
 Open science archives will **provide long-term storage guarantees** ensuring future access to your work. They will create a **digital object identifier (DOI)** (a persistent identifier for your code).
 
-Archives should adhere to recognised principles like [TRUST (Transparency, Responsibility, User focus, Sustainability, and Technology)](https://doi.org/10.1038/s41597-020-0486-7) and the [FORCE11 standards](https://doi.org/10.7717/peerj-cs.86)
+Archives should adhere to recognised principles like [TRUST (Transparency, Responsibility, User focus, Sustainability, and Technology)](https://doi.org/10.1038/s41597-020-0486-7) and the [FORCE11 (Future of Research Communications and E-Scholarship) standards](https://doi.org/10.7717/peerj-cs.86)
 
 Archives can be generalist (for any research discipline), subject-specific, or institutional (hosted by a particular university or research institute). Examples include:
 

pages/guide/sharing/citation.qmd

@@ -49,7 +49,9 @@ This page explains why and how to provide citation instructions in your simulati
 
 > Explicitly list and acknowledge everyone who played a role in the project (including minor contributions). There are structured frameworks which can be used to specify roles, like the [Contributor Role Taxonomy (CRediT)](https://credit.niso.org/) for research projects.
 
-For `CITATION.cff` files...
+<br>
+
+Many repositories use a CITATION.cff file to store structured citation metadata for software and datasets. This plain-text file is both human- and machine-readable and is supported by tools like GitHub, Zenodo, and Zotero. For repositories using `CITATION.cff` files, additional benefits are that it is...
 
 **Used when archiving**
 
@@ -65,7 +67,7 @@ For `CITATION.cff` files...
 
 ### `CITATION.cff`
 
-A `CITATION.cff` file is a plain text file with a standard structure to share citation metadata for software or datasets.
+As mentioned above, a `CITATION.cff` file is a plain text file with a standard structure to share citation metadata for software or datasets.
 
 The easiest way to create this file is using the [cffinit](https://citation-file-format.github.io/cff-initializer-javascript/#/) web application. It will guide you through the required information, and generate a `CITATION.cff` file at the end.
 
@@ -85,9 +87,15 @@ As an example, the `CITATION.cff` from the repository for this book:
 
 * **Zotero:** The Zotero reference manager uses `CITATION.cff` when importing the repository as a reference.
 
-* **GitHub:** Adds a "Cite this repository" button to the sidebar, which provides APA and BibTeX citations (based on the `CITATION.cff` file), and links to the file. For example:
+* **GitHub:** Adds a "Cite this repository" button to the sidebar, which provides APA and BibTeX citations (based on the `CITATION.cff` file), and links to the file.
+
+::: {.callout-tip title="Why Zenodo and Zotero matter for your model"}
+
+**Zenodo:** Archiving a release of your GitHub repo on Zenodo gives your software a DOI, and Zenodo can read your `CITATION.cff` to auto‑populate title, authors, and version. This means others can cite the exact version of your model reproducibly.
+
+**Zotero:** Many collaborators and reviewers manage references in Zotero. Having a DOI and structured metadata (via `CITATION.cff` or Zenodo) lets them add your software to their library and cite it like a paper or dataset.
 
-![](citation_resources/cff_github.png){fig-alt="Screenshot of GitHub 'Cite this repository'."}
+:::
 
 ### `README.md`
 
@@ -120,11 +128,11 @@ Heather, A., Monks, T., Mustafee, N., Harper, A., Alidoost, F., Challen, R., & S
 If you have [structured your model as a package](../setup/package.qmd), then you can include some citation instructions within the package.
 
 :::{.python-content}
-Depending on your package manager, you can include citation and author details in several ways...
+Depending on your package manager, you can include citation and author details in several ways. A package manager is a tool that helps you build, install, and share your Python project as a package; it usually reads project metadata from a configuration file called `pyproject.toml`. This file can store information such as the package name, version, and authors, which users and tools can then use when citing your work.
 
 <br>
 
-**Flit:** Our tutorial used this as it is a very basic minimalist package manager. It had `__init.py` and `pyproject.toml` files. We can amend the `pyproject.toml` to add some citation information as follows:
+**Flit:** Our tutorial used Flit, a minimalist package manager that keeps configuration in a `pyproject.toml` file. You can add basic citation information (such as your name and email) to the `[project]` section so it is recorded as part of the package metadata:
 
 ```{.bash}
 [build-system]
@@ -141,7 +149,7 @@ authors = [
 
 <br>
 
-**Poetry:** Another popular manager, this has project details within `pyproject.toml` like so:
+**Poetry:** Poetry is another popular tool for managing dependencies and packaging, which also uses `pyproject.toml` to store project details. Here, citation‑related information like the package name, version, and authors is defined under the `[tool.poetry]` section:
 
 ```{.bash}
 [tool.poetry]
@@ -150,6 +158,11 @@ version = "0.1.0"
 authors = ["First Last <firstname.lastname@example.com>"]
 readme = "README.md"
 ```
+
+<br>
+
+Other tools follow the same idea, but the exact section and format depend on the package manager you use.
+
 :::
 
 :::{.r-content}