Conventions
On this page we summarize the visual and structural conventions used throughout the book.
Code
Two kinds of code appear. R code is shown in syntax-highlighted blocks; its output is prefixed with #> to make the boundary between input and output explicit:
mean(c(1, 2, 3, 4, 5))
#> [1] 3Shell commands, which recur constantly in this book, are shown with a $ prompt that is not part of the command:
$ zzc statusInline code is in monospace. File and directory names (renv.lock, analysis/) and command names (make, zzc) are also set in monospace.
The chapter card
Each numbered chapter opens with a card. The card gives an estimated reading time and names the earlier chapters and the statistical knowledge the chapter assumes. The time is computed, not guessed: the prose words before the exercises, plus ten words for each line of code, read at 200 words a minute and rounded to five minutes. It excludes the exercises, whose time depends on the reader. A test fails when a card drifts more than five minutes from the rule. It also lists three to five objectives, phrased as questions the reader should be able to answer by the end, and a short outline of what follows. A reader who already knows the material can check the objectives and skip ahead.
Where a chapter sits on the stack
A computational result rests on nine layers, from the hardware at the base to intrinsic non-determinism at the top (3 Levels of Reproducibility works through all nine). Most chapters open with a figure placing that chapter on the stack. In that figure the layers the chapter captures (pins for the first time, or pins more tightly than an earlier chapter did) are drawn in full color. The layers it validates (checks without itself pinning anything new) are outlined. Every such figure is a call to the same function, plot_determinant_stack(), and its alt text is computed from the same call that draws the figure, so the two cannot describe different layers.
The folded Check
Most numbered sections end with a folded Check: a short question testing comprehension of the section just read, with the answer folded inside it so that attempting the question is not optional. Expand the box to read the question, attempt an answer, and only then expand the Answer nested inside it. On paper a box cannot be folded, so the printed edition numbers the checks in each chapter and collects their answers at the end of the chapter, under ‘Answers to the checks’, with page references both ways. The example below keeps its answer in place.
Callouts
Three kinds of callout appear, each with one job.
A specific way the preceding technique goes wrong in practice, not a generic warning.
Where protected, identifiable, or data-use-agreement restricted data may and may not go: which endpoints, which tools, which repositories. This callout appears wherever a technique could tempt a reader into committing, depositing, or pasting such data.
A fourth, smaller device, the honest level, closes most chapters: one sentence naming the rung the chapter’s own practice reaches and what it still leaves exposed.
One sentence, specific to this chapter, not the whole ladder.
Habits
Seven numbered habits recur across the book, introduced in full in 1 Introduction: reproducibility as a computational problem and recalled in the closing chapter. A rule of thumb in a chapter cites its habit by number, for example ‘habit 4’, rather than restating it.
The two datasets
We use two datasets in the book, and each has a different job.
survival::diabetic is real. It holds 394 records from a randomized trial of laser photocoagulation for diabetic retinopathy, with one row per eye and two eyes per patient. It ships with every R installation, because survival is a recommended package, so no chapter that uses it adds a dependency the reader must install or the lockfile must pin. It carries the computation: where the book fits a model, draws a figure, or reports a number, that number comes from real data and the reader can regenerate it.
The incident-diabetes cohort is synthetic, and is written by analysis/scripts/simulate_cohort.R from a fixed seed. It carries two threads the real data cannot. The first is confidentiality: the extract holds record numbers, names, and dates of birth, so the chapter on version control can show a file that must never enter a repository’s history. No public dataset contains protected information, by construction, so that lesson requires an invented one. The second is data validation. The extract carries deliberate defects (two date formats in one column, a duplicated record, an implausible age, an inconsistently coded sex, and missing outcomes), so that the tests in 11 Testing and Code Quality have something to catch. Clean data would have to be broken on purpose in any case.
The synthetic choice is not a compromise, and we would make it again with real data available. A committed generator with a fixed seed is more reproducible than a downloaded extract. It has no external dependency, no link rot, and no access control, and a reader can regenerate it byte for byte in a second. What it gives up is friction. Invented messiness is tidier and stranger than the messiness of an actual registry export, and a reader who has only ever met generated data will be surprised by their first real one.
The cohort compendium is still taking shape across the book’s chapters, and not every chapter uses it yet. A reader who notices a chapter working from a different example is therefore seeing that work in progress, not a different design.
The one-quarter core path
The book is written for a one-quarter, ten-week course. The table below marks a core path through it; a chapter marked optional is not weaker material, only material a ten-week schedule has no room for. An instructor with more time, or a reader working alone, can take the whole book in order.
| Chapter | Status |
|---|---|
| Introduction | Core |
| The Reproducibility Crisis | Core |
| Levels of Reproducibility | Core |
| Version Control with Git and GitHub | Core |
| The Research Compendium | Core |
| Pinning Packages with renv | Core |
| Pinning the Environment with Docker | Core |
| Backends and Runtimes: Nix, Podman, and Apptainer | Optional |
| Literate Programming and the Rendered Report | Core |
| Automating the Analysis: Make and targets | Core for the Make section; targets, Snakemake, Nextflow, and workflowr are optional |
| Testing and Code Quality | Core |
| Continuous Integration and Verification | Core |
| Collaboration, Archiving, and Stewardship | Core |
Cross-references
Sections, figures, and tables are referenced by their Quarto label (@sec-levels, @fig-ladder, @tbl-tools). Literature is cited by @bibkey and collected in the References.