pythonhealthdatascience · TomMonks · May 1, 2024 · Oct 24, 2022 · Aug 9, 2023 · Oct 30, 2023
diff --git a/CITATION.cff b/CITATION.cff
@@ -0,0 +1,32 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: >-
+  Towards Sharing Tools and Artifacts for Reusable
+  Simulation: example enhanced documentation for a `simpy`
+  model.
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Thomas
+    family-names: Monks
+    affiliation: University of Exeter
+    orcid: 'https://orcid.org/0000-0003-2631-4481'
+  - given-names: Alison
+    family-names: Harper
+    affiliation: University of Exeter
+    orcid: 'https://orcid.org/0000-0001-5274-5037'
+repository-code: >-
+  https://github.com/pythonhealthdatascience/stars-simpy-example-docs
+url: >-
+  https://pythonhealthdatascience.github.io/stars-simpy-example-docs
+keywords:
+  - Discrete-event simulation
+  - Open Science
+  - Reproducibility
+  - Documentation
+  - Model reuse
+license: MIT
diff --git a/README.md b/README.md
@@ -1,17 +1,111 @@
-[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/TomMonks/treatment-centre-sim/HEAD)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pythonhealthdatascience/stars-simpy-example-docs/HEAD)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.10054063.svg)](https://doi.org/10.5281/zenodo.10054063)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/release/python-360+/)
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6497477.svg)](https://doi.org/10.5281/zenodo.6497477)
+[![Read the Docs](https://readthedocs.org/projects/pip/badge/?version=latest)](https://pythonhealthdatascience.github.io/stars-simpy-example-docs)
+[![License: MIT](https://img.shields.io/badge/ORCID-0000--0001--5274--5037-brightgreen)](https://orcid.org/0000-0001-5274-5037)
+[![License: MIT](https://img.shields.io/badge/ORCID-0000--0003--2631--4481-brightgreen)](https://orcid.org/0000-0003-2631-4481)
 [<img src="https://img.shields.io/static/v1?label=dockerhub&message=images&color=important?style=for-the-badge&logo=docker">](https://hub.docker.com/r/tommonks01/treat_sim)
 
+#   Towards Sharing Tools and Artifacts for Reusable Simulation: example enhanced documentation for a `simpy` model. 
 
-# An open treatment centre simulation model.
+## Overview
 
-This work occompanies Monks et al (2022).
+The materials and methods in this repository support work towards developing the S.T.A.R.S healthcare framework (**S**haring **T**ools and **A**rtifacts for **R**eusable **S**imulations in healthcare).  The code and written materials here demonstrate the application of S.T.A.R.S' version 1 to sharing a `simpy` discrete-event simuilation model and associated research artifacts.  
 
-The repo contains an free and open implementation of the Treatment Centre Model from Nelson (2013).  It is published under a permissive MIT license.
+* All artifacts in this repository are linked to study researchers via ORCIDs;
+* Model code is made available under a MIT license;
+* Python dependencies are managed through `conda`;`
+* The python code itself can be viewed and executed in Jupyter notebooks via [Binder](https://mybinder.org); 
+* The model is documented and explained in a [Jupyter book website](https://pythonhealthdatascience.github.io/stars-simpy-example-docs) served up by GitHub pages;
+* The materials are deposited and made citatable using Zenodo;
+* The models are sharable with other researchers and the NHS without the need to install software.
 
-## References
+## Author ORCIDs
 
-1. *Monks.T, Harper.A, Anagnoustou. A, Allen.M, Taylor.S. (2022) Open Science for Computer Simulation*
-2. *Nelson. B.L. (2013). [Foundations and methods of stochastic simulation](https://www.amazon.co.uk/Foundations-Methods-Stochastic-Simulation-International/dp/1461461596/ref=sr_1_1?dchild=1&keywords=foundations+and+methods+of+stochastic+simulation&qid=1617050801&sr=8-1). Springer.* 
+[![ORCID: Harper](https://img.shields.io/badge/ORCID-0000--0001--5274--5037-brightgreen)](https://orcid.org/0000-0001-5274-5037)
+[![ORCID: Monks](https://img.shields.io/badge/ORCID-0000--0003--2631--4481-brightgreen)](https://orcid.org/0000-0003-2631-4481)
+
+## Citation
+
+> Monks, T., & Harper, A. (2023). Towards Sharing Tools and Artifacts for Reusable Simulation: example enhanced documentation for a `simpy` model. (v1.1.0). Zenodo. https://doi.org/10.5281/zenodo.10054063
+
+```bibtex
+@software{stars_example_docs,
+  author       = {Monks, Thomas and
+                  Harper, Alison},
+  title        = {{Towards Sharing Tools and Artifacts for Reusable 
+                   Simulation: example enhanced documentation for a
+                   `simpy` model.}},
+  month        = oct,
+  year         = 2023,
+  publisher    = {Zenodo},
+  version      = {v1.1.0},
+  doi	       = {10.5281/zenodo.10054063},
+  url	       = {https://doi.org/10.5281/zenodo.10054063},
+}
+```
+
+## Funding
+
+This code is part of independent research supported by the National Institute for Health Research Applied Research Collaboration South West Peninsula. The views expressed in this publication are those of the author(s) and not necessarily those of the National Institute for Health Research or the Department of Health and Social Care.
+
+## Case study model
+
+**This example is based on exercise 13 from Nelson (2013) page 170.**
+
+> *Nelson. B.L. (2013). [Foundations and methods of stochastic simulation](https://www.amazon.co.uk/Foundations-Methods-Stochastic-Simulation-International/dp/1461461596/ref=sr_1_1?dchild=1&keywords=foundations+and+methods+of+stochastic+simulation&qid=1617050801&sr=8-1). Springer.* 
+
+We adapt a textbook example from Nelson (2013): a terminating discrete-event simulation model of a U.S based treatment centre. In the model, patients arrive to the health centre between 6am and 12am following a non-stationary Poisson process. On arrival, all patients sign-in and are triaged into two classes: trauma and non-trauma. Trauma patients include impact injuries, broken bones, strains or cuts etc. Non-trauma include acute sickness, pain, and general feelings of being unwell etc. Trauma patients must first be stabilised in a trauma room. These patients then undergo treatment in a cubicle before being discharged. Non-trauma patients go through registration and examination activities. A proportion of non-trauma patients require treatment in a cubicle before being discharged. The model predicts waiting time and resource utilisation statistics for the treatment centre. The model allows managers to ask question about the physical design and layout of the treatment centre, the order in which patients are seen, the diagnostic equipment needed by patients, and the speed of treatments. For example: “what if we converted a doctors examination room into a room where nurses assess the urgency of the patients needs.”; or “what if the number of patients we treat in the afternoon doubled” 
+
+## Online Notebooks via Binder
+
+The python code for the model has been setup to run online in Jupyter notebooks via binder [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pythonhealthdatascience/stars-ciw-example/HEAD)
+
+> Binder is a free service.  If it has not been used in a while Binder will need to re-containerise the code repository, and push to binderhub. This will take several minutes. After that the online environment will be quick to load.
+
+## Online documentation produced by Jupyter-book
+
+[![Read the Docs](https://readthedocs.org/projects/pip/badge/?version=latest)](https://pythonhealthdatascience.github.io/stars-simpy-example-docs)
+
+* The documentation can be access at [https://pythonhealthdatascience.github.io/stars-simpy-example-docs](https://pythonhealthdatascience.github.io/stars-simpy-example-docs)
+
+## How to create the website locally
+
+Alternatively you may wish to create the website on your local machine.  
+
+### Downloading the code
+
+Either clone the repository using git or click on the green "code" button and select "Download Zip".
+
+```bash
+git clone https://github.com/pythonhealthdatascience/stars-simpy-examplar-docs
+```
+
+### Installing dependencies
+
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/release/python-360+/)
+
+All dependencies can be found in [`binder/environment.yml`]() and are pulled from conda-forge.  To run the code locally, we recommend install [mini-conda](https://docs.conda.io/en/latest/miniconda.html); navigating your terminal (or cmd prompt) to the directory containing the repo and issuing the following command:
+
+```bash
+conda env create -f binder/environment.yml
+```
+
+To activate the environment issue the following command:
+
+```bash
+conda activate stars_docs`
+```
+
+### Building the book
+
+In the directory (folder) containing the code issue the following command via the terminal (or cmd prompt/powershell on windows)
+
+```bash
+jb build .
+```
+
+> The configutation of the book has been setup to re-run all of the notebooks.  It may take a few minutes to execute on your local machine.
+
+When the build is complete Jupyter book will display a hyper-link to the book that has been built on your machine.  Click on the link (or copy paste into a browser) to run it.
diff --git a/binder/environment.yml b/binder/environment.yml
@@ -1,4 +1,4 @@
-name: treatment_sim
+name: stars_docs
 channels:
   - conda-forge
 dependencies:
@@ -11,4 +11,6 @@ dependencies:
   - python=3.8.12
   - scipy=1.6.1
   - simpy=4.0.1
+  - pip:
+    - jupyter-book==0.15.1
 
diff --git a/content/01_introduction/03_citation.md b/content/01_introduction/03_citation.md
@@ -1,19 +1,21 @@
 # Citation
 
-Please cite this online book using:
+If you use or adapt the materials in this book please cite the artifacts as follows:
+
+> Monks, T., & Harper, A. (2023). Towards Sharing Tools and Artifacts for Reusable Simulation: example enhanced documentation for a `simpy` model. (v1.1.0). Zenodo. https://doi.org/10.5281/zenodo.10054063
 
 ```bibtex
-@software{monks_thomas_2022_6772475,
+@software{stars_example_docs,
   author       = {Monks, Thomas and
-                  Harper, Alison and
-                  Taylor, J.E, Simon and
-                  Anagnostou, Anastasia},
-  title        = {TomMonks/treatment-centre-sim: v0.4.0},
-  month        = jun,
-  year         = 2022,
+                  Harper, Alison},
+  title        = {{Towards Sharing Tools and Artifacts for Reusable 
+                   Simulation: example enhanced documentation for a
+                   `simpy` model.}},
+  month        = oct,
+  year         = 2023,
   publisher    = {Zenodo},
-  version      = {v0.4.0},
-  doi          = {10.5281/zenodo.6772475},
-  url          = {https://doi.org/10.5281/zenodo.6772475}
+  version      = {v1.1.0},
+  doi	       = {10.5281/zenodo.10054063},
+  url	       = {https://doi.org/10.5281/zenodo.10054063},
 }
 ```
diff --git a/content/01_introduction/04_openworking.md b/content/01_introduction/04_openworking.md
@@ -4,8 +4,8 @@ This project has taken the following steps to ensure the work is discoverable, u
 
 |   | **Level**          | **Achieved via**                                                                                                                                                                                                                                                                                                 |
 |---|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| 1 | Open Access        | A preprint to accompany and document this pilot work is available via the Open Science Framework [https://doi.org/10.31219/osf.io/zpxtm](https://doi.org/10.31219/osf.io/zpxtm)                                                                                                                                                                                                                  |
-| 2 | Open Artefacts     | <ul><li>All research artefacts including this website are archived permanently at [Zenodo](https://doi.org/10.5281/zenodo.6497477)</li><li>Production code is available from [GitHub](https://github.com/TomMonks/treatment-centre-sim)</li></ul>                                                                                                                                                                                      |
+| 1 | Open Access        | A conference paper of this work was presented at the OR Society Simulation Workshop 2023 [https://www.theorsociety.com/media/7313/doiorg1036819sw23030.pdf](https://www.theorsociety.com/media/7313/doiorg1036819sw23030.pdf)                                                                                                                                                                                                                  |
+| 2 | Open Artifacts     | <ul><li>All research artifacts including this website are archived permanently at [Zenodo](https://zenodo.org/records/10054063)</li><li>Production code is available from [GitHub](https://github.com/pythonhealthdatascience/stars-simpy-example-docs)</li></ul>                                                                                                                                                                                      |
 | 3 | Open Model         | <ul><li>The model has been developed using Free and open simulation software;</li> <li>All mode code is reusable and adaptable under the permissive MIT license model;</li><li>The model is documented in detail within a online Jupyter Book;</li><li>Additional documentation organised by the [STRESS-DES checklist](../03_stress/01_objectives.md) within the Jupyter Book.</li></ul> |
 | 4 | Open Environment   | A [docker image is available via dockerhub](https://hub.docker.com/r/tommonks01/treat_sim) to enable replication of the OS and software environment and model execution on a local machine.                                                                                                                                                                       |
 | 5 | Open Infrastucture | The model can be run online using BinderHub or Thebe                                                                                                                                                                                                                                                             |
diff --git a/content/02_model_code/04_model.ipynb b/content/02_model_code/04_model.ipynb
diff --git a/content/02_model_code/output/table_3.txt b/content/02_model_code/output/table_3.txt
@@ -6,12 +6,12 @@
 \toprule
 Mean waiting time (mins) &   base &  triage+1 &  exam+1 &  treat+1 &  triage+exam \\
 \midrule
-                  Triage &  28.86 &      1.09 &   36.46 &    39.36 &         1.14 \\
-             Registation & 113.56 &    138.79 &  106.27 &   108.46 &       140.14 \\
-             Examination &  24.57 &     24.15 &    0.13 &    23.03 &         0.15 \\
-    Non-trauma treatment & 137.72 &    139.98 &  151.82 &     2.26 &       152.09 \\
-    Trauma stabilisation & 144.46 &    154.00 &  132.94 &   146.09 &       165.43 \\
-        Trauma treatment & 168.27 &    209.12 &  195.16 &   150.37 &       193.69 \\
+                  Triage &  29.52 &      1.17 &   29.47 &    23.99 &         1.21 \\
+             Registation & 101.88 &    128.14 &  101.09 &   109.70 &       125.47 \\
+             Examination &  25.34 &     24.93 &    0.16 &    24.03 &         0.14 \\
+    Non-trauma treatment & 134.19 &    134.80 &  148.81 &     2.10 &       150.61 \\
+    Trauma stabilisation & 171.44 &    182.96 &  139.42 &   166.51 &       178.34 \\
+        Trauma treatment &  20.26 &     22.65 &   19.40 &    16.96 &        19.48 \\
 \bottomrule
 \end{tabular}
 \end{table}
diff --git a/content/03_stress/05_implementation.md b/content/03_stress/05_implementation.md
@@ -1,4 +1,4 @@
-# 5 Implementation
+# 5. Implementation
 
 ## 5.1 Software or programming language
 
@@ -22,9 +22,9 @@ A [conda virtual environment](https://github.com/TomMonks/treatment-centre-sim/b
 
 ## 5.2 Random sampling 
 
-All sampling uses [`numpy.random.Generator`](https://numpy.org/doc/stable/reference/random/generator.html).  A `numpy` generator object implements the Permuted Congruential Generator 64-bit (PCG64; period = $2^{128}$).
+All sampling uses [`numpy.random.Generator`](https://numpy.org/doc/stable/reference/random/generator.html).  A `numpy` generator object implements the Permuted Congruential Generator 64-bit (PCG64; period = $2^{128}$; maximum number of streams = $2^{63}$).
 
-Common random number streams are used in the model.  These are created by through seed vectors (one seed for each activity in each replication).
+Repeatable experiments and common random number streams are used in the model.  Non overlapping streams are creating using a `numpy.random.SeedSequence`. One seed - the replication number - is passed to a `SeedSequence` and $n$ child seeds are spawned that are then used to create the $n$ streams. The seeds spawned by `SeedSequence` ensure that these streams are "very likely" non-overlapping.
 
 ## 5.3 Model execution
 

diff --git a/content/03_stress/06_code_access.md b/content/03_stress/06_code_access.md
@@ -1,4 +1,4 @@
-# 6 Code access
+# 6. Code access
 
 * Simulation model code is available from the main branch of Githib repo: https://github.com/TomMonks/treatment-centre-sim
 * All simulation model code is contained within a Jupyter notebook: https://github.com/TomMonks/treatment-centre-sim/blob/main/src/model.ipynb

diff --git a/content/front_page.md b/content/front_page.md
@@ -2,21 +2,21 @@
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.6497477.svg)](https://doi.org/10.5281/zenodo.6497477)
 
-This book contains example documentation and open working for a computer simulation model. The model is a based on the treatment centre example in Nelson [1]. The model is implemented in `python` and `simpy`.
+This book contains example enhanced documentation and open working for a discrete-event simulation model. The model is a based on the treatment centre example in Nelson [1]. The model is implemented in `python` and `simpy`.
 
-The book covers the following aspects of open working for simulation:
+##   Towards Sharing Tools and Artifacts for Reusable Simulation: example enhanced documentation for a `simpy` model. 
 
-* Sharing your model code and parameters with other researchers and simulation modellers.
-* An example of documenting your model using the STRESS reporting checklist (for DES).
-* Providing a simple executable version of your model for other to verify results.
+The materials and methods in this repository support work towards developing the S.T.A.R.S healthcare framework (**S**haring **T**ools and **A**rtifacts for **R**eusable **S**imulations in healthcare).  The code and written materials here demonstrate the application of S.T.A.R.S' version 1 to sharing a `simpy` discrete-event simuilation model and associated research artifacts.  
 
-## Contributors
+* All artifacts in this repository are linked to study researchers via ORCIDs;
+* Model code is made available under a MIT license;
+* Python dependencies are managed through `conda`;`
+* The python code itself can be viewed and executed in Jupyter notebooks via [Binder](https://mybinder.org); 
+* The model is documented and explained in a [Jupyter book website](https://pythonhealthdatascience.github.io/stars-simpy-example-docs) served up by GitHub pages;
+* The materials are deposited and made citatable using Zenodo;
+* The models are sharable with other researchers and the NHS without the need to install software.
 
-* Thomas Monks, University of Exeter
-* Alison Harper, University of Exeter
-* Simon Taylor, Brunel University London
-* Anastasia Anagnostou, Brunel University London
+## Author ORCIDs
 
-## References
-
-1. *Nelson. B.L. (2013). [Foundations and methods of stochastic simulation: A first course](https://www.amazon.co.uk/Foundations-Methods-Stochastic-Simulation-International/dp/1461461596/ref=sr_1_1?dchild=1&keywords=foundations+and+methods+of+stochastic+simulation&qid=1617050801&sr=8-1). Springer.* 
+[![ORCID: Harper](https://img.shields.io/badge/ORCID-0000--0001--5274--5037-brightgreen)](https://orcid.org/0000-0001-5274-5037)
+[![ORCID: Monks](https://img.shields.io/badge/ORCID-0000--0003--2631--4481-brightgreen)](https://orcid.org/0000-0003-2631-4481)