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] 3

Shell commands, which recur constantly in this book, are shown with a $ prompt that is not part of the command:

$ zzc status

Inline 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.

A short question testing comprehension of the just-read material.

The worked answer, with the reasoning that leads to it rather than the conclusion alone.

Callouts

Three kinds of callout appear, each with one job.

TipVerification

How to see that a claim actually holds, and, just as important, how to make it fail on purpose. A gate that cannot fail is not a gate.

WarningPitfall

A specific way the preceding technique goes wrong in practice, not a generic warning.

ImportantRestricted data

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.

ImportantThe honest level

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.