Reproducible Research for the Health Sciences
Compendia, containers, and computational verification in R
Welcome

This is the online version of Reproducible Research for the Health Sciences by the rgtlab curriculum team, a graduate course textbook.
In this book we take a position that a health scientist will recognize from their own methodological training. Computational reproducibility is not a property of any single file. It is a property of the relationships among the operating system, the language runtime, the package set, the session configuration, the source code, and the data. A result reproduces when those relationships are captured well enough that another person, on another machine, at a later time, obtains the same answer. The mature tools of the R ecosystem each capture one or two of these relationships. The unsolved problem, and the subject of this book, is composing them into a single workflow that a working analyst can actually adopt.
We organize the book around three ideas that recur in every chapter. The first is a ladder of reproducibility levels. It runs from a merely locatable analysis (L0) through pinned packages (L1) and a pinned environment (L2) to a verified analysis whose recorded outputs have been shown to regenerate (L3). The second is a distinction between capturing reproducibility and validating it: pinning an environment captures a level, whereas continuous integration and verification confirm it. The third is the research compendium, a single directory that bundles data, code, and manuscript inside a structure that any reader can navigate and any machine can rebuild.
The concrete vehicle throughout is zzcollab, an open-source R framework built around the levels ladder. It composes the standard tools (renv or Nix for packages, Docker or a runtime alternative for the environment, a research-compendium package structure, continuous integration, testing, and data-integrity checking) into a single system. We teach the concepts first and the tool second. A reader who finishes the book should be able to reason about reproducibility with any toolchain, and to operate this one.
What the reader is assumed to know
- R at a working level: writing functions and scripts, installing packages, and rendering an R Markdown or Quarto document.
- Comfort at the command line: running a shell command, editing a text file, and using
gitat a basic level. - No prior experience with Docker, containers, continuous integration, or Nix is assumed. Each is built up from first principles.
The reader we have in mind is a graduate student or working analyst in public health, biostatistics, epidemiology, or a related quantitative health science. Such a reader produces analyses that others will need to trust, audit, and rebuild.
The Contents page lists every chapter on one page.
License
This book is licensed under Creative Commons Attribution 4.0 International. You may share and adapt it for any purpose, including teaching, provided you give attribution.
The code samples printed in this book are licensed under the MIT License. The repository code (package functions and build scripts) is licensed under GPL-3.