index.qmd

---
title: "Reproducible Discrete-Event Simulation in Python and R"
subtitle: "Building transparent reliable simulation models within a reproducible analytical pipeline."
date: last-modified
language:
  title-block-published: "Website last updated"
include-in-header:
  - text: |
      <style>
      h1 {
        text-align: center;
      }
      p.subtitle.lead {
        text-align: center;
      }
      </style>
      <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css">
format: 
  html:
    page-layout: full
---

<!-- Hide as no python-content or r-content blocks -->
<style>
      #quarto-announcement {
        display: none !important;
      }
</style>

This open book is a self-paced training resource that teaches you how to design, implement, and share discrete-event simulation (DES) models in Python and R as part of a reproducible analytical pipeline. It combines a **step-by-step guide** with **complete example repositories** that you can adapt for your own projects.

The material is designed for analysts, researchers, and students in health and operations research who want to build transparent, trustworthy simulation models. To get the most from this resource, you should be comfortable with basic programming in either Python or R and have some familiarity with probability and basic statistics. **No prior DES experience is required**: short introductions to DES, reproducible analytical pipelines, and free and open source software are provided in the "Intros" section and linked below.

::: {.pale-blue}

"The DES RAP Book was a valuable resource in our transition to open-source DES modelling. It provided us with a step-by-step structure to follow and guidance on best practice for writing code, tests and documentation for our package. Our model is being using in the Midlands, and beyond, for understanding future demand and capacity within Kidney Replacement Therapy." - **Lucy Morgan, Analytics Manager at The Strategy Unit**.

:::

An engaged learner can complete the core step-by-step guide in around 10-15 hours, including time to run the code examples and attempt the exercises. You can work through the material in order as a structured course, or dip into specific sections (such as input modelling, verification and validation, or sharing and archiving) as needed.

After working through this resource, you will be able to:

* Set up **version control** and reproducible **environments** for your DES RAP project.
* Structure your work as a **package**, with clear, reusable code organisation.
* Manage **inputs** systematically, including data, parameters, and validation.
* Build a working **DES model** with entities, processes, randomness, and logging.
* Carry out **output analysis** and **experimentation**, including warm-up, replications, and scenario/sensitivity analysis.
* Apply **verification, validation, testing, and quality assurance** to increase trust in your model.
* Improve **style, documentation, and automation** with linting, docstrings, and GitHub Actions.
* **Collaborate and share** your work effectively, including code review, licensing, citation, changelogs, and archiving.

> If you use the DES RAP book in your teaching, research, or training, we'd love to hear about it. Please [get in touch](/pages/guide/further_info/feedback.qmd) to share how you've used the material, suggest improvements, or point us to example models or case studies that others might find helpful.
>
> Educators and trainers can adopt the book as a complete syllabus for a short course or reuse individual chapters as standalone teaching units (for example, sessions on RAP, testing, packaging, or sharing models),  and should cite the resource when they do so in line with the provided citation below. The accompanying code is released under an MIT licence, and the text is available under a CC BY-SA 4.0 licence, allowing reuse and adaptation with appropriate attribution.

<br>

```{=html}
<div class="value-grid">
  <a href="pages/guide/introduction.qmd" class="value-box">
    <div class="icon"><i class="bi bi-journal-code"></i></div>
    <div class="text">
      <div class="title">Step-by-step guide</div>
      <div class="value">Click to follow along with our guide to build your own reproducible DES model.</div>
    </div>
  </a>
  <a href="pages/example_models/example_models.qmd" class="value-box">
    <div class="icon"><i class="bi bi-folder2-open"></i></div>
    <div class="text">
      <div class="title">Examples</div>
      <div class="value">The guide is accompanied by four complete example repositories - click to find out more!</div>
    </div>
  </a>
</div>
```

<br>

<div class="section-block">

#### Reproducibility frameworks

Our resources are designed to help you meet two important reproducibility standards. Learn more:

<a href="pages/frameworks/levels_of_rap.qmd" class="inline-btn">
  <span class="inline-btn-icon"><i class="fa-solid fa-link"></i></span>
  NHS Levels of RAP
</a>
<a href="pages/frameworks/stars_reproducibility.qmd" class="inline-btn">
  <span class="inline-btn-icon"><i class="fa-solid fa-link"></i></span>
  STARS reproducibility recommendations
</a>

#### New to these concepts?

We have dedicated pages explaining the foundations, helpful if you're new to any of these areas.

<a href="pages/intros/des.qmd" class="inline-btn">
  <span class="inline-btn-icon"><i class="fa-solid fa-circle-info"></i></span>
  Discrete-Event Simulation
</a>
<a href="pages/intros/rap.qmd" class="inline-btn">
  <span class="inline-btn-icon"><i class="fa-solid fa-circle-info"></i></span>
  Reproducible Analytical Pipelines
</a>
<a href="pages/intros/foss.qmd" class="inline-btn">
  <span class="inline-btn-icon"><i class="fa-solid fa-circle-info"></i></span>
  Free & Open Source Software
</a>

</div>

<br>

This resource is an output of **STARS**, a research project led by Associate Prof. **Tom Monks** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0003-2631-4481).

The book is written by **Amy Heather** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0002-6596-3479). It has been reviewed by:

* Prof. **Nav Mustafee** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0002-2204-8924)
* Dr. **Alison Harper** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0001-5274-5037)
* Associate Prof. **Tom Monks** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0003-2631-4481)
* **Fatemeh Alidoost** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0009-0000-0252-560X)
* Dr. **Rob Challen** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0000-0002-5504-7768)
* **Tom Slater** [![ORCID](images/orcid.png){fig-alt="ORCID logo"}](https://orcid.org/0009-0007-0838-7499)

The STARS project is supported by the Medical Research Council [grant number MR/Z503915/1] from 1st May 2024 to 31st October 2026. The listed researchers are associated with the **University of Exeter** Medical and Business Schools, and the **University of Bristol** School of Engineering, Mathematics and Technology.

You can find out more about our project on the [**STARS project website**](https://pythonhealthdatascience.github.io/stars/){target="_blank"}. If you use this resource, **please cite us:**

> Heather, A., Monks, T., Mustafee, N., Harper, A., Alidoost, F., Challen, R., & Slater, T. (2025). DES RAP Book: Reproducible Discrete-Event Simulation in Python and R. https://github.com/pythonhealthdatascience/des_rap_book. https://doi.org/10.5281/zenodo.17094155.

<br>

<i><b>Keywords:</b> discrete-event simulation; reproducible analytical pipelines; health services research; Python; R; simulation modelling; research software engineering; open-source tools; SimPy; simmer.</i>

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TrainingMaterial",
  "@id": "https://doi.org/10.5281/zenodo.17094155",
  "http://purl.org/dc/terms/conformsTo": {
    "@type": "CreativeWork",
    "@id": "https://bioschemas.org/profiles/TrainingMaterial/1.0-RELEASE"
  },
  "name": "DES RAP Book: Reproducible Discrete-Event Simulation in Python and R",
  "description": "An open, self-paced training resource that teaches how to design, implement, and share discrete-event simulation (DES) models in Python and R as part of a reproducible analytical pipeline (RAP).",
  "keywords": [
    "discrete-event simulation",
    "reproducible analytical pipelines",
    "health services research",
    "Python",
    "R",
    "simulation modelling",
    "research software engineering",
    "open-source tools",
    "SimPy",
    "simmer"
  ],
  "url": "https://pythonhealthdatascience.github.io/des_rap_book/",
  "identifier": [
    {
      "@type": "PropertyValue",
      "propertyID": "DOI",
      "value": "10.5281/zenodo.17094155"
    }
  ],
  "abstract": "This practical guide shows you how to build reproducible discrete-event simulation models (DES) that fit into a reproducible analytical pipeline (RAP), with tips that benefit all types of models and analysis. The resource combines a step-by-step guide with complete example repositories in Python and R.",
  "about": [
    {
      "@type": "DefinedTerm",
      "name": "Discrete-event simulation"
    },
    {
      "@type": "DefinedTerm",
      "name": "Reproducible analytical pipelines"
    },
    {
      "@type": "DefinedTerm",
      "name": "Health services research"
    },
    {
      "@type": "DefinedTerm",
      "name": "Research software engineering"
    }
  ],
  "audience": [
    {
      "@type": "Audience",
      "audienceType": "researchers"
    },
    {
      "@type": "Audience",
      "audienceType": "research software engineers"
    },
    {
      "@type": "Audience",
      "audienceType": "analysts"
    },
    {
      "@type": "Audience",
      "audienceType": "postgraduate students in health and operations research"
    }
  ],
  "author": [
    {
      "@type": "Person",
      "name": "Amy Heather",
      "@id": "https://orcid.org/0000-0002-6596-3479"
    }
  ],
  "contributor": [
    {
      "@type": "Person",
      "name": "Tom Monks",
      "@id": "https://orcid.org/0000-0003-2631-4481"
    },
    {
      "@type": "Person",
      "name": "Nav Mustafee",
      "@id": "https://orcid.org/0000-0002-2204-8924"
    },
    {
      "@type": "Person",
      "name": "Alison Harper",
      "@id": "https://orcid.org/0000-0001-5274-5037"
    },
    {
      "@type": "Person",
      "name": "Fatemeh Alidoost",
      "@id": "https://orcid.org/0009-0000-0252-560X"
    },
    {
      "@type": "Person",
      "name": "Rob Challen",
      "@id": "https://orcid.org/0000-0002-5504-7768"
    },
    {
      "@type": "Person",
      "name": "Tom Slater",
      "@id": "https://orcid.org/0009-0007-0838-7499"
    }
  ],
  "competencyRequired": [
    "Basic programming in Python or R (functions, packages, simple scripts)",
    "Familiarity with probability and basic statistics"
  ],
  "educationalLevel": "intermediate",
  "inLanguage": "en",
  "learningResourceType": [
    "online book",
    "step-by-step guide",
    "worked examples"
  ],
  "license": [
    "https://opensource.org/license/mit",
    "https://creativecommons.org/licenses/by-sa/4.0/"
  ],
  "mentions": [
    {
      "@type": "SoftwareApplication",
      "name": "SimPy"
    },
    {
      "@type": "SoftwareApplication",
      "name": "simmer"
    },
    {
      "@type": "SoftwareApplication",
      "name": "Git"
    },
    {
      "@type": "SoftwareApplication",
      "name": "GitHub"
    }
  ],
  "teaches": [
    "Setting up version control and reproducible environments for DES RAP projects",
    "Structuring simulation projects as reusable packages",
    "Managing inputs, parameters, and experiments in a reproducible way",
    "Building DES models with entities, processes, randomness, and logging",
    "Performing output analysis, warm-up, replications, and scenario/sensitivity analysis",
    "Applying verification, validation, testing, and quality assurance to simulation models",
    "Automating checks with linters and continuous integration",
    "Documenting, licensing, citing, and archiving DES models for reuse"
  ],
  "timeRequired": "PT10H",
  "provider": {
    "@type": "Organization",
    "name": "STARS project, University of Exeter and University of Bristol"
  },
  "datePublished": "2025-09-10",
  "creativeWorkStatus": "Active",
  "version": "1.0"
}
</script>

<!-- datePublished is set to date of first release -->