Skip to content

Commit 6aa9345

Browse files
amyheatheramyheather
committed
docs(README): wrote "how does model work" and "acknowledgements" sections
1 parent 6188b03 commit 6aa9345

File tree

3 files changed

+103
-4
lines changed

3 files changed

+103
-4
lines changed

‎README.md‎

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Table of contents:
3030
* [📝 Citation](#-citation)
3131
* [📜 Licence](#-licence)
3232
* [💰 Funding](#-funding)
33+
* [👨‍👨‍👧 Acknowledgements](#-acknowledgements)
3334
* [📄 Template README for your project](#-template-readme-for-your-project)
3435

3536
<br>
@@ -38,13 +39,13 @@ Table of contents:
3839

3940
This repository provides a template for building discrete-event simulation (DES) models in R.
4041

41-
😊 **Simple:** Easy-to-follow code structure using [simmer](https://r-simmer.org/). Implements a simple M/M/s queueing model in which patients arrive, wait to see a nurse, have a consultation with the nurse and then leave.
42-
4342
♻️ **Reproducible:** This template is designed to function as a RAP. It adheres to reproducibility recommendations from:
4443

4544
* ["Levels of RAP" framework](https://nhsdigital.github.io/rap-community-of-practice/introduction_to_RAP/levels_of_RAP/) from the NHS RAP Community of Practice (as documented in `nhs_rap.md`).
4645
* Recommendations from [Heather et al. 2025](TODO:ADDLINK) "*On the reproducibility of discrete-event simulation studies in health research: a computational investigation using open models*" (as documented in `heather_2025.md`).
4746

47+
😊 **Simple:** Easy-to-follow code structure using [simmer](https://r-simmer.org/). Implements a simple M/M/s queueing model in which patients arrive, wait to see a nurse, have a consultation with the nurse and then leave.
48+
4849
✨ **Design practices:** Functions are documented with `roxygen2` docstrings and `lintr` is used to lint `.R` and `.Rmd` files.
4950

5051
🧱 **Package structure:** The simulation code (`R/`) is structured as a little local R package. It is installed in our environment using `devtools::install()` and then `library(simulation)`. This means it can easily be used anywhere else in the directory - here, in `rmarkdown/` and `tests/` - without needing any additional code (e.g. no need to run `source()` with paths to the files).
@@ -204,7 +205,17 @@ The `lint_package()` function will run on files typically included in a package
204205

205206
## ❓ How does the model work?
206207

207-
TBC <!-- TODO: Write this section -->
208+
**Model run process**
209+
210+
1. **Set parameters:** Use `parameters()` to create a list with the desired model parameters.
211+
212+
2. **Run simulation:** Use `model()` to execute the simulation once, or `runner()` to perform multiple replications of the model.
213+
214+
**Relationships between functions:**
215+
216+
![Model structure diagram](images/model_structure.png)
217+
218+
*Illustration of functions created using [draw.io](https://draw.io/).*
208219

209220
<br>
210221

@@ -234,7 +245,8 @@ repo/
234245
├── NEWS.md # Describes changes between releases (equivalent to a changelog for R packages)
235246
├── rap_template_r_des.Rproject # Project settings
236247
├── README.md # This file! Describes the repository
237-
└── renv.lock # Lists R version and all packages in the R environment
248+
├── renv.lock # Lists R version and all packages in the R environment
249+
└── run_rmarkdown.sh # Bash script to run knit all .Rmd from the command line
238250
```
239251

240252
<br>
@@ -303,6 +315,17 @@ SOFTWARE.
303315

304316
<br>
305317

318+
## 👨‍👨‍👧 Acknowledgements
319+
320+
This repository was developed with thanks to a few others sources. These are acknowledged throughout in the relevant scipts, and also summarised here:
321+
322+
| Source | Find out more about how it was used... |
323+
| - | - |
324+
| Ucar I, Smeets B (2023). simmer.plot: Plotting Methods for 'simmer'. https://r-simmer.org. https://github.com/r-simmer/simmer.plot. | `R/get_run_results.R` |
325+
| Tom Monks (2021) sim-tools: fundamental tools to support the simulation process in python (https://github.com/TomMonks/sim-tools) (MIT Licence).<br> Who themselves cite Hoad, Robinson, & Davies (2010). Automated selection of the number of replications for a discrete-event simulation (https://www.jstor.org/stable/40926090), and Knuth. D "The Art of Computer Programming" Vol 2. 2nd ed. Page 216. | `R/choose_replications.R` |
326+
327+
<br>
328+
306329
## 💰 Funding
307330

308331
This project was developed as part of the project STARS: Sharing Tools and Artefacts for Reproducible Simulations. It is supported by the Medical Research Council [grant number [MR/Z503915/1](https://gtr.ukri.org/projects?ref=MR%2FZ503915%2F1)].

‎images/model_structure.drawio‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
<mxfile host="app.diagrams.net" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36" version="26.1.1">
2+
<diagram name="Page-1" id="ynTKS2v_TZv17swCPKiS">
3+
<mxGraphModel dx="1434" dy="915" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
4+
<root>
5+
<mxCell id="0" />
6+
<mxCell id="1" parent="0" />
7+
<mxCell id="ltitkqDnKHNBnyyiyaz9-11" value="&lt;span style=&quot;font-size: 14px;&quot;&gt;parameters()&lt;/span&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#F2A25C;" parent="1" vertex="1">
8+
<mxGeometry x="127.5" y="50" width="100" height="30" as="geometry" />
9+
</mxCell>
10+
<mxCell id="5LiT1j53H3c69v0TLy5i-11" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="ltitkqDnKHNBnyyiyaz9-40" target="5LiT1j53H3c69v0TLy5i-1">
11+
<mxGeometry relative="1" as="geometry" />
12+
</mxCell>
13+
<mxCell id="5LiT1j53H3c69v0TLy5i-17" value="Input to..." style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="5LiT1j53H3c69v0TLy5i-11">
14+
<mxGeometry x="-0.3333" y="3" relative="1" as="geometry">
15+
<mxPoint as="offset" />
16+
</mxGeometry>
17+
</mxCell>
18+
<mxCell id="ltitkqDnKHNBnyyiyaz9-40" value="Generates list of parameters" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=1;" parent="1" vertex="1">
19+
<mxGeometry x="90" y="81.5" width="175" height="23.5" as="geometry" />
20+
</mxCell>
21+
<mxCell id="5LiT1j53H3c69v0TLy5i-14" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;" edge="1" parent="1" source="5LiT1j53H3c69v0TLy5i-1" target="5LiT1j53H3c69v0TLy5i-3">
22+
<mxGeometry relative="1" as="geometry" />
23+
</mxCell>
24+
<mxCell id="5LiT1j53H3c69v0TLy5i-15" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;" edge="1" parent="1" source="5LiT1j53H3c69v0TLy5i-1" target="5LiT1j53H3c69v0TLy5i-5">
25+
<mxGeometry relative="1" as="geometry" />
26+
</mxCell>
27+
<mxCell id="5LiT1j53H3c69v0TLy5i-16" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;curved=0;" edge="1" parent="1" source="5LiT1j53H3c69v0TLy5i-1" target="5LiT1j53H3c69v0TLy5i-7">
28+
<mxGeometry relative="1" as="geometry" />
29+
</mxCell>
30+
<mxCell id="5LiT1j53H3c69v0TLy5i-18" value="Uses..." style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="5LiT1j53H3c69v0TLy5i-16">
31+
<mxGeometry x="-0.6645" relative="1" as="geometry">
32+
<mxPoint as="offset" />
33+
</mxGeometry>
34+
</mxCell>
35+
<mxCell id="5LiT1j53H3c69v0TLy5i-1" value="&lt;span style=&quot;font-size: 14px;&quot;&gt;model()&lt;/span&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#F2A25C;" vertex="1" parent="1">
36+
<mxGeometry x="142.5" y="170" width="70" height="30" as="geometry" />
37+
</mxCell>
38+
<mxCell id="5LiT1j53H3c69v0TLy5i-13" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="5LiT1j53H3c69v0TLy5i-2" target="5LiT1j53H3c69v0TLy5i-9">
39+
<mxGeometry relative="1" as="geometry" />
40+
</mxCell>
41+
<mxCell id="5LiT1j53H3c69v0TLy5i-19" value="Used by..." style="edgeLabel;html=1;align=center;verticalAlign=middle;resizable=0;points=[];" vertex="1" connectable="0" parent="5LiT1j53H3c69v0TLy5i-13">
42+
<mxGeometry x="-0.2477" y="-2" relative="1" as="geometry">
43+
<mxPoint as="offset" />
44+
</mxGeometry>
45+
</mxCell>
46+
<mxCell id="5LiT1j53H3c69v0TLy5i-2" value="Defines model processes, runs simulation with seeds and logs, extracts patient and resource results" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=1;" vertex="1" parent="1">
47+
<mxGeometry x="102.5" y="208" width="150" height="57.5" as="geometry" />
48+
</mxCell>
49+
<mxCell id="5LiT1j53H3c69v0TLy5i-3" value="&lt;span style=&quot;font-size: 14px;&quot;&gt;valid_inputs()&lt;/span&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#F2A25C;" vertex="1" parent="1">
50+
<mxGeometry x="427.75" y="130.5" width="102.5" height="30" as="geometry" />
51+
</mxCell>
52+
<mxCell id="5LiT1j53H3c69v0TLy5i-4" value="Checks that provided parameters are valid" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=1;" vertex="1" parent="1">
53+
<mxGeometry x="530.25" y="130.5" width="150" height="40" as="geometry" />
54+
</mxCell>
55+
<mxCell id="5LiT1j53H3c69v0TLy5i-5" value="&lt;span style=&quot;font-size: 14px;&quot;&gt;filter_warmup()&lt;/span&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#F2A25C;" vertex="1" parent="1">
56+
<mxGeometry x="424" y="180.5" width="110" height="30" as="geometry" />
57+
</mxCell>
58+
<mxCell id="5LiT1j53H3c69v0TLy5i-6" value="Removes results that occurred during warm-up" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=1;" vertex="1" parent="1">
59+
<mxGeometry x="534" y="175.5" width="150" height="40" as="geometry" />
60+
</mxCell>
61+
<mxCell id="5LiT1j53H3c69v0TLy5i-7" value="&lt;span style=&quot;font-size: 14px;&quot;&gt;get_run_results()&lt;/span&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#F2A25C;" vertex="1" parent="1">
62+
<mxGeometry x="414" y="230.5" width="130" height="30" as="geometry" />
63+
</mxCell>
64+
<mxCell id="5LiT1j53H3c69v0TLy5i-8" value="Calculates average results for that run" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=1;" vertex="1" parent="1">
65+
<mxGeometry x="544" y="225.5" width="130" height="40" as="geometry" />
66+
</mxCell>
67+
<mxCell id="5LiT1j53H3c69v0TLy5i-9" value="&lt;span style=&quot;font-size: 14px;&quot;&gt;runner()&lt;/span&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#F2A25C;" vertex="1" parent="1">
68+
<mxGeometry x="142.5" y="330" width="70" height="30" as="geometry" />
69+
</mxCell>
70+
<mxCell id="5LiT1j53H3c69v0TLy5i-10" value="Runs replications, sequentially or in parallel" style="text;html=1;align=center;verticalAlign=middle;whiteSpace=wrap;rounded=1;" vertex="1" parent="1">
71+
<mxGeometry x="102.5" y="360" width="150" height="40" as="geometry" />
72+
</mxCell>
73+
</root>
74+
</mxGraphModel>
75+
</diagram>
76+
</mxfile>

‎images/model_structure.png‎

184 KB
Loading

0 commit comments

Comments
 (0)