DES RAP Book: Reproducible Discrete-Event Simulation in Python and R

DES RAP Book is an open resource and website for building discrete-event simulation (DES) models within a reproducible analytical pipline (RAP), supporting the healthcare simulation community.

The resource demonstrates practical, code-based workflows and tools to help researchers and practitioners develop, validate, and share DES models in Python (SimPy) and R (simmer), ensuring models are reproducible.

Check it out at: https://pythonhealthdatascience.github.io/des_rap_book/.

Who is this for?

• Researchers, analysts, practitioners, and students in simulation modeling - especially those in healthcare and operations research.

• Anyone using Python or R who is seeking practical guidance on best practices for reproducibility, with many of the sections (e.g. environments, version control, documentation, testing) being broadly relevant to any research software and data science projects.

• Accessible to a range of experience levels. The material is designed to be approachable, though some familiarity with Python or R, and basic command line usage, is recommended. Prior experience with simulation modeling is also helpful.

What's covered?

• Getting started: introduction to reproducibility and open-source.

• Building models: Structured guidance on model inputs, implementation, experimentation, and analysis with clear, reproducible code examples in Python and R. This includes recommendations for experimentation, output analysis, and verification and validation.

• Best practices: Code packaging, environment management, version control, linting, testing, and documentation for robust and transparent workflows.

• Reporting and collaboration: Generating tables/figures, licensing, sharing, peer review, archiving, citation, and changelogs.

Getting started/Navigation

• Visit the DES RAP Book website for all tutorials and resources (also viewable locally as described below).

• The example model repositories linked from the book are:

  • Python M/M/s example
  • Python stroke example
  • R M/M/s example
  • R stroke example

STARS

This resource has been developed as part of the project STARS: Sharing Tools and Artefacts for Reproducible Simulations in healthcare.

The project tackles the challenges of sharing, reusing, and reproducing discrete event simulation (DES) models in healthcare. Our goal is to create open resources using the two most popular open-source languages for DES: Python and R.

We have been developing tutorials, code examples, and tools to help researchers and practitioners develop, validate, and share DES models more effectively.

For more information on this project, check out the STARS page in the DES RAP Book.

View locally

This website is created using Quarto and hosted on GitHub pages. You can view the site locally. With quarto installed, you will need to:

1. Build the python environment

conda env create --file environment.yaml
conda activate des-rap-book

2. Build the R environment

renv::init()
renv::restore()

3. Create the book.

quarto render

Common reticulate error and solution

When rendering a Quarto document containing executable python code with reticulate, you might encounter:

Error in `use_condaenv()`:
! Unable to locate conda environment 'des-rap-book'.
Backtrace:
    ▆
 1. └─reticulate::use_condaenv("des-rap-book", required = TRUE)

This can occur when multiple Conda or Mamba installations exist (e.g. mambgaforge, miniconda3), or if R is using a different search path than the shell. By default, reticulate only looks in one location for environments, which can cause problems when environments are not where reticulate expects.

To fix this, set the RETICULATE_CONDA environment variable to the correct Conda or Mamba executable. To find the path to your executable, run:

conda env list

Look for your environment in the list. For example, if your environment is at /home/amy/mambaforge/envs/des-rap-book, then your Conda executable is likely at /home/amy/mambaforge/bin/conda.

Set the environment variable like so:

export RETICULATE_CONDA=/home/amy/mambaforge/bin/conda

Now render your book:

quarto render

To avoid needing to set RETICULATE_CONDA every time you open a new terminal, add the export command to an .Renviron file in your project directory. This file is not tracked by Git, and is specific to you. Create the file and add:

RETICULATE_CONDA=/home/amy/mambaforge/bin/conda

Citation

To cite this work, see the CITATION.cff file in this repository or use the "Cite this repository" button on GitHub.

Linting

To lint active Python and R code:

bash lint.sh

Note: inactive code (i.e. code that does not get run when building the book) will not be linted - though the R linter will enforce a terminal newline at the end of each .qmd file.

Funding

This project is supported by the Medical Research Council [grant number MR/Z503915/1].