Merge pull request #89 from pythonhealthdatascience/dev

Dev

Author: amyheather

README.md

@@ -138,6 +138,8 @@ RETICULATE_CONDA=/home/amy/mambaforge/bin/conda
 
 To cite this work, see the `CITATION.cff` file in this repository or use the "Cite this repository" button on GitHub.
 
+You can also cite the archived version of this work on Zenodo: https://doi.org/10.5281/zenodo.17094155.
+
 <br>
 
 ## Linting

_quarto.yml

@@ -47,8 +47,8 @@ website:
       - pages/model/process.qmd
     - section: "Output analysis"
       contents:
-      - pages/output_analysis/outputs.qmd
       - pages/output_analysis/warmup.qmd
+      - pages/output_analysis/outputs.qmd
       - pages/output_analysis/replications.qmd
       - pages/output_analysis/n_reps.qmd
       - pages/output_analysis/parallel.qmd
@@ -103,6 +103,19 @@ website:
           Code licence: <a href="https://opensource.org/license/mit" target="_blank" rel="noopener">MIT</a>.  
           Text licence: <a href="https://creativecommons.org/licenses/by-sa/4.0/" target="_blank" rel="noopener">CC-BY-SA 4.0</a>.
 
+comments:
+  giscus: 
+    repo: "pythonhealthdatascience/des_rap_book"
+    repo-id: "R_kgDOOXKhOA"
+    category: "Announcements"
+    category-id: "DIC_kwDOOXKhOM4CuWAj"
+    mapping: "pathname"
+    reactions-enabled: true
+    loading: "lazy"
+    input-position: "bottom"
+    theme: "light"
+    language: "en"
+
 format:
   html:
     theme: cosmo
@@ -121,8 +134,8 @@ format:
     filters:
       - filters/guidelines-filter.lua
     include-after-body:
-      text: |
-        <script type="application/javascript" src="../../scripts/language-selector.js"></script>
+      - scripts/webex.js
+      - scripts/language-selector.js
 
 params:
   language: "python"  # Default language parameter

index.qmd

@@ -23,4 +23,6 @@ This practical guide shows you how to build **reproducible** discrete-event simu
 
 This resource is an output of **STARS**, a research project led by Associate Prof. **Tom Monks** [![ORCID](images/orcid.png)](https://orcid.org/0000-0003-2631-4481). The book is written by **Amy Heather** [![ORCID](images/orcid.png)](https://orcid.org/0000-0002-6596-3479) and reviewed by Prof. **Nav Mustafee** [![ORCID](images/orcid.png)](https://orcid.org/0000-0002-2204-8924), Dr. **Alison Harper** [![ORCID](images/orcid.png)](https://orcid.org/0000-0001-5274-5037), and Associate Prof. **Tom Monks** [![ORCID](images/orcid.png)](https://orcid.org/0000-0003-2631-4481). The STARS project is supported by the Medical Research Council [grant number MR/Z503915/1]. The listed researchers are associated with the **University of Exeter** Medical and Business Schools.
 
-> *Please **cite** us if you use this resource!* <!--TODO: Add Zenodo DOI once archive-->
+> *Please **cite** us if you use this resource!*
+>
+> Heather, A., Monks, T., Mustafee, N., & Harper, A. (2025). DES RAP Book: Reproducible Discrete-Event Simulation in Python and R. https://github.com/pythonhealthdatascience/des_rap_book. https://doi.org/10.5281/zenodo.17094155.

pages/_metadata.yml

@@ -11,20 +11,11 @@ title: Input data management
 
 ::: {.pale-blue}
 
-🎯 **Objectives**
+**Learning objectives:**
 
-This page provides guidance on managing data and parameters for simulation projects.
-
-* **🧾 Input data:** Understand the types of input data.
-* **📦 What is included in a RAP?** Advice on which data should be shared to ensure a reproducible analytical pipeline (RAP). 
-* **🗃️ Raw data:** Recommendations on storage and sharing.
-* **📜 Input modelling code:** Recommendations on storage and sharing.
-* **⚙️ Parameters:** Recommendations on storage and sharing.
-* **🔐 Maintaining a private and public version of your model:** Advice for projects with sensitive data.
-
-[🔗](../intro/guidelines.qmd) **Reproducibility guidelines**
-
-While not directly meeting specific criteria, this page explains the importance of sharing input data for a RAP, and how this can be managed when there is sensitive data.
+* Recognise where a **reproducible analytical pipeline** begins, and what data is included.
+* Learn recommended practices for **storing and sharing raw data, input modelling code, and parameters**.
+* Understand how **private and public versions** of a model could be maintained when there is sensitive data.
 
 :::
 
@@ -246,15 +237,18 @@ The way you might set these up depends on whether you are allowed to share the r
 
 ## 🧪 Test yourself
 
-```{r, echo = FALSE}
+```{r}
+#| echo: false
 library(webexercises) # nolint: library_call_linter
 ```
 
 :::{.callout-note}
 
 ## If your raw (e.g. patient-level) data cannot be shared, which of the following is recommended?
 
-```{r, results="asis", echo = FALSE}
+```{r}
+#| output: asis
+#| echo: false
 cat(longmcq(c(
   "Do not share or describe anything.",
   answer = paste0(
@@ -270,7 +264,9 @@ cat(longmcq(c(
 
 ## Even if it cannot be shared publicly, input modelling code be retained so parameters can be re-estimated if new data or assumptions arise.
 
-```{r, results="asis", echo = FALSE}
+```{r}
+#| output: asis
+#| echo: false
 cat(longmcq(c(
   answer = "True",
   "False"
@@ -283,7 +279,9 @@ cat(longmcq(c(
 
 ## What is a good strategy when maintaining a public and private version of a model?
 
-```{r, results="asis", echo = FALSE}
+```{r}
+#| output: asis
+#| echo: false
 cat(longmcq(c(
   "Duplicate all simulation code across both repositories.",
   answer = paste(

pages/inputs/input_data.qmd

@@ -6,29 +6,57 @@ bibliography: input_modelling_resources/references.bib
 
 {{< include ../../scripts/_reticulate-setup.md >}}
 
-::: {.pale-blue}
+:::: {.pale-blue}
 
-🎯 **Objectives**
+**Learning objectives:**
 
-This page has step-by-step instructions for input modelling in Python or R, with inspiration from @Robinson2007 and @Monks2024.
+* Identify what **data** is needed for input modelling and why **quality** matters.
+* Understand how input data forms the basis for **randomness** in simulated systems.
+* **Inspect, fit, and select probability distributions** for your model using both **targeted and comprehensive** approaches.
 
-* **📂 Data:** Identify what data is needed for input modelling and why quality matters.
-* **➡️ How is this data used in the model?** Understand how input data forms the basis for randomness in simulated systems.
-* **📈 Input modelling:** Inspect, fit, and select probability distributions for your model using both targeted and comprehensive approaches, with steps:
-    * **🔧 Set-up**
-    * **🔍 Step 1. Identify possible distributions**
-    * **📊 Step 2. Fit distributions and compare goodness-of fit**
-    * **✅ Step 3. Choose distributions**
-    * **⚙️ Parameters**
+**Required packages:**
 
-For advice on making your input modelling workflow **reproducible** and **sharing data or scripts with sensitive content**, see the [page on input data management](input_data.qmd).
+This should be available from environment setup in the "🧪 Test yourself" section of [Environments](../setup/environment.qmd). 
 
-[🔗](../intro/guidelines.qmd) **Reproducibility guidelines**
+::: {.python-content}
+
+```{python}
+from distfit import distfit
+import numpy as np
+import pandas as pd
+import plotly.express as px
+import plotly.graph_objects as go
+from scipy import stats
+```
+
+```{python}
+#| echo: false
+# To ensure renders correctly in quarto
+import plotly.io as pio
+pio.renderers.default = "plotly_mimetype"
+```
+
+:::
+
+::: {.r-content}
 
-While not directly meeting specific criteria, this page encourages recording clear, reproducible input modelling processes to improve transparency and verification in your simulation work.
+```{r}
+#| output: false
+library(dplyr)
+library(fitdistrplus)
+library(ggplot2)
+library(lubridate)
+library(plotly)
+library(readr)
+library(tidyr)
+```
 
 :::
 
+**Acknowledgements:** Inspired by @Robinson2007 and @Monks2024.
+
+::::
+
 ## 📂 Data
 
 To build a DES model, you first need **data** that reflects the system you want to model. In healthcare, this might mean you need to access healthcare records with patient arrival, service and departure times, for example. The quality of your simulation depends directly on the quality of your data. Key considerations include:
@@ -102,44 +130,6 @@ touch rmarkdown/input_modelling.Rmd
 
 :::
 
-Before you begin, ensure the following packages are available. They should already be installed if you set up the environment in the "*🧪 Test yourself*" section of the [Environments](../setup/environment.qmd) page.
-
-::: {.python-content}
-
-```{python}
-# Import required packages
-from distfit import distfit
-import numpy as np
-import pandas as pd
-import plotly.express as px
-import plotly.graph_objects as go
-from scipy import stats
-```
-
-```{python, echo=FALSE}
-import plotly.io as pio
-pio.renderers.default = "plotly_mimetype"
-```
-
-:::
-
-::: {.r-content}
-
-```{r, message=FALSE}
-# nolint start: undesirable_function_linter.
-# Import required packages
-library(dplyr)
-library(fitdistrplus)
-library(ggplot2)
-library(lubridate)
-library(plotly)
-library(readr)
-library(tidyr)
-# nolint end
-```
-
-:::
-
 ## 🔍 Step 1. Identify possible distributions
 
 You first need to select which distributions to fit to your data. You should both:
@@ -522,7 +512,8 @@ inspect_histogram <- function(
 }
 ```
 
-```{r, warning=FALSE}
+```{r}
+#| warning: false
 # Plot histogram of inter-arrival times
 inspect_histogram(
   data = data, var = "iat_mins", x_lab = "Inter-arrival time (min)",
@@ -1007,7 +998,7 @@ If you haven't already followed along, **now's the time to put everything from t
 ::: {.python-content}
 * Download the arrival data, and create a Jupyter notebook for your analysis.
 :::
-::: {.python-content}
+::: {.r-content}
 * Download the arrival data, and create an R markdown file for your analysis.
 :::
 

pages/inputs/input_modelling.qmd

@@ -4,30 +4,53 @@ title: Parameters from file
 
 {{< include ../../scripts/_reticulate-setup.md >}}
 
-::: {.pale-blue}
+```{python}
+#| echo: false
+# pylint: disable=wrong-import-position,reimported,wrong-import-order
+# pylint: disable=ungrouped-imports,too-many-instance-attributes
+# pylint: disable=too-many-arguments, too-many-positional-arguments
+# pylint: disable=too-few-public-methods,redefined-outer-name
+# pylint: disable=function-redefined
+```
 
-🎯 **Objectives**
+:::: {.pale-blue}
 
-Discrete-event simulations (DES) require many parameters - like arrival rates, resource times, and probabilities - which often need to be changed for different scenarios and analyses. Managing these parameters well makes your simulations easier to update, track, and reuse.
+**Learning objectives:**
 
-This page focuses on the storage of parameters within a file.
+* Know the **advantages** of using external parameter files in simulation workflows  
+* Learn how to create a **parameter file** and **data dictionary**.
+* Understand methods for **importing** parameters.
 
-* **❓ Why use external parameter files?**
-* **📝 Create parameter file**
-* **📖 Create data dictionary**
-* **📥 Methods for importing parameters**
+**Relevant reproducibility guidelines:**
 
-If you want to see how to store parameters within a script, see the [parameters from script](parameters_script.qmd) page.
+* STARS Reproducibility Recommendations: Avoid hard-coded parameters.
+* NHS Levels of RAP (🥈): Data is handled and output in a Tidy data format.
 
-[🔗](../intro/guidelines.qmd) **Reproducibility guidelines**
+**Required packages:**
 
-This page helps you meet reproducibility criteria from:
+This should be available from environment setup in the "🧪 Test yourself" section of [Environments](../setup/environment.qmd). 
 
-* STARS Reproducibility Recommendations: Avoid hard-coded parameters.
-* NHS Levels of RAP (🥈): Data is handled and output in a Tidy data format.
+::: {.python-content}
+
+```{python}
+import pandas as pd
+import json
+from collections import defaultdict
+```
+
+:::
+
+::: {.r-content}
+
+```{r}
+library(jsonlite)
+library(R6)
+```
 
 :::
 
+::::
+
 :::: {.python-content}
 
 ::: {.callout-note title="Utility function" collapse="true"}
@@ -90,33 +113,8 @@ def print_dict(dictionary, max_items_per_level):
 
 :::
 
-```{python, echo=FALSE}
-# pylint: disable=wrong-import-position,reimported,wrong-import-order
-# pylint: disable=ungrouped-imports,too-many-instance-attributes
-# pylint: disable=too-many-arguments, too-many-positional-arguments
-# pylint: disable=too-few-public-methods,redefined-outer-name
-# pylint: disable=function-redefined
-```
-
-```{python}
-import pandas as pd
-import json
-from collections import defaultdict
-```
-
 ::::
 
-::: {.r-content}
-
-```{r}
-# nolint start: undesirable_function_linter
-library(jsonlite)
-library(R6)
-# nolint end
-```
-
-:::
-
 ## ❓ Why use external parameter files?
 
 External parameter files can offer some advantages over storing parameters directly in scripts:
@@ -204,10 +202,8 @@ As mentioned in the [checklist for managing parameter data](input_data.qmd#check
 
 The examples below were created using markdown (converted to PDF using `pandoc`), but you can use any suitable format (e.g. CSV, YAML, etc.) - as long as it is clear, consistent and accessible.
 
-```{python}
+```{.python}
 #| echo: false
-#| output: false
-
 import subprocess
 
 subprocess.run([