🏗 WORK IN PROGRESS (STARS 2.0) 🏗️
The materials in this repo are experimental.
The materials and methods in this documentation support work towards developing the STARS healthcare framework (Sharing Tools and Artifacts for Reproducible Simulations in healthcare). Long term STARS aims to support researchers share open simulation models regardless of language choice, improve the quality of sharing, and reduce the workload required to meet high standards of open science for the modelling and simulation community.
The code and written materials are a work in progress towards STARS version 2.0. It is not recommended to use these materials in simulation practice at the moment.
This repo demonstrates the application of sharing a discrete-event simulation model in R and associated research artifacts:
- All artifacts in this repository are linked to study researchers via ORCIDs;
- Model code is made available under the MIT license;
- Project dependencies managed through
renv - The simulation model is deployed as an R package via R Universe
- The R code, simmer model, (to do and package) are documented and explained in a quarto website served up by GitHub pages;
- The materials are deposited and made citatable using Zenodo;
- [To do: The models are sharable with other researchers and the NHS without the need to install software.]
Please cite our code if you use it:
Monks, T., Harper, A., Heather, A., & Mustafee, N. (2024). Towards Sharing Tools, Artifacts, and Reproducible Simulation: a `simmer` model example (v0.2.0). Zenodo. https://doi.org/10.5281/zenodo.11222943
@software{monks_2024_11546973,
author = {Monks, Thomas and
Harper, Alison and
Heather, Amy and
Mustafee, Navonil},
title = {{Towards Sharing Tools, Artifacts, and Reproducible
Simulation: a `simmer` model example}},
month = jun,
year = 2024,
publisher = {Zenodo},
version = {v0.3.0},
doi = {10.5281/zenodo.11222943},
url = {https://doi.org/10.5281/zenodo.11222943}
}We do not have a publication to support this work yet. For now, please cite the Journal of Simulation article that reports STARS 1.0 and our pilot work.
@article{towards_stars_jos_paper,
author = {Thomas Monks, Alison Harper and Navonil Mustafee},
title = {Towards sharing tools and artefacts for reusable simulations in healthcare},
journal = {Journal of Simulation},
volume = {0},
number = {0},
pages = {1--20},
year = {2024},
publisher = {Taylor \& Francis},
doi = {10.1080/17477778.2024.2347882},
URL = { https://doi.org/10.1080/17477778.2024.2347882},
}This work was supported by the Medical Research Council [grant number MR/Z503915/1]
This example is based on exercise 13 from Nelson (2013) page 170. Please also credit this work is you use our materials.
Nelson. B.L. (2013). Foundations and methods of stochastic simulation. 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”
🏗 *Only tested on Linux (Ubuntu 22.04) 🏗️
The materials in this repo are experimental.
We recommend the use of RStudio to run the code locally.
We have made the model available as R package that can be installed from R Universe
If you use the model we recommend use of R studio and renv to isolate your project environment. To install from the R console:
install.packages("treat.sim", repos = c("https://pythonhealthdatascience.r-universe.dev", "https://cloud.r-project.org"))Either clone the repository using git or click on the green "code" button and select "Download Zip".
git clone https://github.com/pythonhealthdatascience/stars-treat-simmerThe current version of the code is maintained in R version 4.4.1
Dependencies are managed via renv. To replicate the R package software environment follow these instructions:
- Open RStudio
- Using RStudio open the project
treat-sim-rsimmer.Rproj(
At this point RStudio will identify that renv is required and install and activate it. To restore the R packages issue the following command in R:
renv::restore()You may need to wait several minutes while the software environment is restored.
library(treat.sim)
# create experiment and hide all logging
default_exp <- create_experiment(log_level=0)
# run 10 replications of the experiment (increase to improve histogram)
envs <- multiple_replications(default_exp, n_reps=10)
# process simmer environments into simple data.frame of reps by KPIs
rep_table <- replication_results_table(envs, default_exp, 60 * 19)
# printout summary table
create_summary_table(rep_table)
## show histogram of patient throughput per day
g <- histogram_of_replications(rep_table, "09_throughput", "patients")
g
- The documentation can be access at https://pythonhealthdatascience.github.io/stars-treat-simmer/