Merge pull request #125 from pythonhealthdatascience/dev

Dev

Author: amyheather

CHANGELOG.md

@@ -5,8 +5,45 @@ 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.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.
+
+### Added
+
+* Template repositories for package structure.
+* Mathematical proof of correctness page.
+* Discrete-event simulation introductory page.
+* Conclusions page.
+* Feedback page.
+
+### Fixed
+
+* Add correction for R time-weighted measures so last interval is included in calculations.
+
+### Changed
+
+* Pages following *Performance Measures* now use **all** metrics (and not just two) for Python and R.
+* Changed Python approach for determining length of warm-up (previous approach unsuitable when using all metrics).
+* Added patient end-time logging to all simulation model pages.
+* Upgraded to `sim-tools` v1.0.0 (Python) and add `queueing` (R).
+
+Also some minor improvements and refinements, including:
+
+* Extra desk-check suggestions in `verification_validation.qmd`
+* Removed colour variable for R sensitivity plots.
+* Expanded and cross-linked stuff on guidelines in `sharing/archive.qmd` and `intro/guidelines.qmd`.
+* Small corrections in README, docstrings, linting.
+* Refactoring tests.
+* Clarifications on R data storage, seed sequences, correlated streams, and limitations of structuring research as a package.
+* Mentions of MRAN, P3M, commit pinning, `data-raw`, `pins` and `{targets}`.
+* Mentioned relevant verification/validation concepts in topic pages.
+* Added link to repository `renv.lock` on environment page.
+
 ## v0.2.0 - 2025-10-14
 
+This release adds a large number of new pages. It also introduces pre-commits, contributor acknowledgements, a contributing guide, interface improvements, updated introduction boxes, and giscus comments.
+
 ### Added
 
 * Logging page

CITATION.cff

@@ -41,5 +41,5 @@ keywords:
   - simmer
   - rap
 license: MIT
-version: '0.2.0'
-date-released: '2025-10-14'
+version: '0.3.0'
+date-released: '2025-11-06'

README.md

@@ -2,7 +2,7 @@
 
 # DES RAP Book: Reproducible Discrete-Event Simulation in Python and R
 
-[![Python](https://img.shields.io/badge/-Python_3.9.22-a8902b?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
+[![Python 3.11](https://img.shields.io/badge/-Python_3.11-a8902b?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
 ![R 4.4.1](https://img.shields.io/badge/-R_4.4.1-276DC2?style=for-the-badge&logo=r&logoColor=white)
 ![Code licence](https://img.shields.io/badge/🛡️_Code_licence-MIT-8a00c2?style=for-the-badge&labelColor=gray)
 ![Text licence](https://img.shields.io/badge/🛡️_Text_licence-CC--BY--SA--4.0-b100cd?style=for-the-badge&labelColor=gray)

environment.yaml

@@ -22,4 +22,4 @@ dependencies:
     - jupytext==1.17.2
     - kaleido==1.1.0
     - lintquarto==0.5.0
-    - sim-tools==0.10.0
+    - sim-tools==1.0.0

pages/experiments/scenarios.qmd

@@ -106,7 +106,7 @@ In @Heather2025, six out of seven studies with scenarios lacked scenario code. T
 {{< include ../output_analysis/replications_resources/summary_stats.py >}}
 {{< include ../output_analysis/parallel_resources/runner.py >}}
 ```
-= 18
+
 ```{r}
 #| echo: false
 #| file: ../output_analysis/replications_resources/create_params.R
@@ -119,7 +119,7 @@ In @Heather2025, six out of seven studies with scenarios lacked scenario code. T
 
 ```{r}
 #| echo: false
-#| file: ../output_analysis/replications_resources/metrics.R
+#| file: ../output_analysis/length_warmup_resources/metrics.R
 ```
 
 ```{r}
@@ -367,7 +367,7 @@ HTML(to_html_datatable(scenario_results.head(200)))
 
 :::
 
-::: {.r-content}
+:::: {.r-content}
 
 ```{r}
 # Run scenarios
@@ -387,8 +387,22 @@ write.csv(scenario_results,
 kable(scenario_results) |> scroll_box(height = "400px")
 ```
 
+<br>
+
+::: {.callout-note title="Selective re-running"}
+
+For simulations with very long run times, you may wish to explore the [{targets}](https://books.ropensci.org/targets/) package. 
+
+With `{targets}`, you can set up your pipeline so that input changes (like updates to parameter files or scenario definitions) trigger the package to automatically re-run only the affected simulations and analyses, while all other results are reused from cache. This targeted re-running helps save computation time when there are many slow scenarios to run.
+
+If you change the code inside your model function, `{targets}` will detect those updates and make sure all impacted analysis steps are re-run.
+
+*Note: This package hasn't been personally tried in this project, so we can't vouch for whether it definitely works reliably with simmer simulation models - it's just a cool package we've heard about! For guides on using this, see the official [{targets} manual](https://books.ropensci.org/targets/)*.
+
 :::
 
+::::
+
 ## Sensitivity analysis
 
 <div class="h3-tight"></div>
@@ -399,6 +413,8 @@ 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)").
+
 ### Running sensitivity analyses
 
 Sensitivity analyses should be run programmatically, just like scenario analyses, and the code should be shared for reproducibility.