Towards Sharing Tools and Artifacts for Reusable Simulation: example enhanced documentation for a simpy
model.
The materials and methods in this repository support work towards developing the S.T.A.R.S healthcare framework (Sharing Tools and Artifacts for Reusable Simulations 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.
- 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;
- The model is documented and explained in a Jupyter book website 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.
Monks, T., & Harper, A. (2024). Towards Sharing Tools and Artifacts for Reusable Simulation: example enhanced documentation for a
simpy
model. (v1.1.2). Zenodo. https://doi.org/10.5281/zenodo.11102373
@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 = may,
year = 2024,
publisher = {Zenodo},
version = {v1.1.2},
doi = {10.5281/zenodo.11102373},
url = {https://doi.org/10.5281/zenodo.11102373}
}
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.
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”
The python code for the model has been setup to run online in Jupyter notebooks via binder
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.
- The documentation can be access at https://pythonhealthdatascience.github.io/stars-simpy-example-docs
Alternatively you may wish to create the website on your local machine.
Either clone the repository using git or click on the green "code" button and select "Download Zip".
git clone https://github.com/pythonhealthdatascience/stars-simpy-example-docs
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; navigating your terminal (or cmd prompt) to the directory containing the repo and issuing the following command:
conda env create -f binder/environment.yml
To activate the environment issue the following command:
conda activate stars_docs`
In the directory (folder) containing the code issue the following command via the terminal (or cmd prompt/powershell on windows)
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.