How to use this guide
Work through each page in order. Follow along with the code examples as you go. You’ll gradually build up a working model and your skills as you progress.
Each section builds on the previous one. You can:
- Follow the explanations and instructions
- Copy and run the provided code
- Complete exercises at the end to test your understanding
It will help you meet two important reproducibility standards:
NHS Levels of RAP STARS reproducibility recommendations
Language selection
Use the toggle above to switch between Python and R examples throughout.
You have selected: Python
You have selected: R
What you’ll need
- Your chosen programming language installed (Python or R).
- A code editor or IDE (e.g., VSCode, RStudio, PyCharm, Positron).
We do not provide central computing resources (such as virtual machines or HPC clusters) for this training, and you should not need them for the examples in this book. All code and teaching materials are free and open source, so anyone can use them on their own machine or institutional setup without additional cost, provided they can install standard Python or R tooling.
For NHS readers: If your IT department is concerned about installing open source software, check out this advice from the Health Service Modelling Associates (HSMA) website. For users interested in Python and VSCode, HSMA also have a tutorial on how to set this up.
Languages and environments:
- Python and it’s standard libraries.
- R and the base R functions.
- Virtual environments/package managers - such as
conda,rigandrenvfor managing versions and isolating project dependencies. Introduced in Environments.
Version control and hosting:
- Git - command-line tool for version control. Introduced in Version control.
- GitHub - used to host code, run GitHub actions, and share repositories. Introduced in Version control.
Simulation libraries:
- SimPy (Python) - discrete-event simulation package used in the Python examples. Introduced in Entity generation.
- simmer (R) - discrete-event simulation package used in the R examples. Introduced in Entity generation.
Data, analysis, and utilities:
Depending on language, you will see:
- pandas, NumPy, plotly express, and other similar libraries for data handling and analysis.
- dplyr, ggplot2, and other similar libraries for data handling and analysis.
Automation, testing and quality assurance
- pytest or testthat - testing frameworks used for running automated tests. Introduced in Tests.
- Linters such as
ruff,flake8,lintquartoorlintrfor checking code style. Introduced in Linting. - GitHub actions - for continuous integration and automated checks. Introduced in GitHub actions
Before you get started…
If you are new to discrete-event simulation (DES), reproducibility and Reproducible Analytical Pipelines (RAP), or to using free and open source software, it is worth spending a little time on the foundations first.
The following short introductions provide the background you need for this book:
Discrete-Event Simulation - what DES is, explaining the key components and concepts underlying these models, and touching on their use in healthcare.
Reproducible Analytical Pipelines - defining reproducibility and RAPs, and explaining the advantages of reproducibility for you and for others.
Free & Open Source Software - what “free and open source means”, why it is strongly preferred for RAPs, and an overview of FOSS tools for DES, including an explanation for the tools chosen for this book.
If you need to build up your Python, R, or health data science skills first, we recommend starting with introductory programming and data analysis courses (for example, the Python for Health Data Science materials) before tackling the full DES RAP guide.
Example models
Four complete example repositories show fully-implemented DES models. At the end of relevant pages, you’ll see an “Explore the example models” callout pointing you to sections you can reference.
Work through the guide first to understand the fundamentals, then refer to the examples to see how concepts work in practice and adapt them for your own models.
Getting help
This is an openly available resource and we cannot guarantee one‑to‑one support for all learners. However, if you have questions or feedback about the material, you can:
- Leave a comment via the comment section at the bottom of each page.
- Open an issue on the project’s GitHub repository.
- Start or contribute to a discussion in the GitHub Discussions area to ask questions or share ideas with others using the book.
We do not provide a dedicated support email address for this resource. Instead, we use GitHub Issues and Discussions so that questions and answers are visible to all learners, and problems can be tracked transparently. However, for queries that you prefer not to post publicly, you can contact us on the email addresses provided on the Feedback page, but we encourage GitHub Issues/Discussions where possible so that other learners can benefit from the answers.
Reporting problems
If you spot a problem with the training material (for example, a bug in the code, a typo, or something that is unclear), please open an issue in the GitHub repository (or leave a comment via the comment section at the bottom of each page). Include as much detail as you can (page link, code snippet, error message). We label, prioritise, and track these issues in GitHub and close them once a fix has been implemented.
Ready? Let’s get started. → Next: Version control