LSMA

LONDON SCHOOL OF MULTIOMICS & AI

Free course

Free course

0 of 25 lessons

Lesson 6 of 7

Module 2 · Statistics

A reproducible workflow

A reproducible workflow

A reproducible workflow

An analysis is only finished when someone else, or you in six months, can run it again and get the same answer. This lesson organises an analysis into a project that does exactly that.

⏱ 11 min readModule 2 · StatisticsFree
Lesson at a glance3 steps · about 11 min
  1. One folder, clear parts
  2. Reports that rebuild themselves: Quarto
  3. Record what you used

One folder, clear parts

A reproducible analysis is one that gives the same results when someone runs the same code on the same data. That sounds automatic, but in practice analyses break for ordinary reasons: a file was edited by hand and nobody remembers how, a script depends on an object that only existed in last week's session, or a package changed between versions. A tidy project folder is the first defence. Here is one layout that works well:

birthweight-analysis/ ├── birthweight-analysis.Rproj ├── data/ raw inputs, never edited ├── scripts/ 01_clean.R, 02_models.R, 03_figures.R ├── results/ tables written by the scripts ├── figures/ figures written by the scripts └── report.qmd the write-up

How to read this layout

  • birthweight-analysis.Rproj is the RStudio Project file. Double-clicking it opens RStudio with the working directory set to this folder (Setting up R and RStudio).
  • data/ holds the inputs exactly as you received them. Treat it as read-only: scripts read from it but never write to it.
  • scripts/ holds the code, numbered in the order it runs: 01_clean.R prepares the data, 02_models.R fits the models, 03_figures.R draws the figures.
  • results/ and figures/ hold only things the scripts create. Because they can always be rebuilt, they can safely be deleted.
  • report.qmd is the written report, which pulls its numbers from the code.

The rule that raw data are never edited is what makes the rest possible. If a birth weight was mistyped, the fix belongs in 01_clean.R, as a line of code with a comment saying why, not in the spreadsheet. The raw file then still shows what you received, the script shows exactly what you changed, and anyone can check both. A correction made by hand in Excel leaves no trace, and the next person to receive the data will have to find the same error again.

For this module's data, 01_clean.R would read the raw file, make the labelled factors from Describing data, and save the result for the next script. In Data frames and files you read and wrote tables with read.csv() and write.csv(). Those are right for raw inputs and for tables people will open, but a CSV file stores only text and numbers: the factor levels, and their order, are lost when it is read back. For files that only scripts will read, saveRDS(bw, "results/bw_clean.rds") keeps the object exactly as it was, factors included, and readRDS() brings it back.

A reproducible workflow · LSMA free course Raw data in the data folder is read by three numbered scripts. The scripts write tables to the results folder and figures to the figures folder. The Quarto report uses both and renders to HTML. 1 · RAW DATA 2 · SCRIPTS 3 · OUTPUTS 4 · REPORT data/ never edited 01_clean.R 02_models.R 03_figures.R results/ figures/ report.qmd renders to HTML Each step reads from the left and writes to the right; nothing is copied back by hand.
Raw data enters on the left and is never changed; everything to its right is produced by code and can be deleted and rebuilt. Schematic, not to scale.

A relative path such as data/birthwt.csv describes where a file is from the project folder. An absolute path such as C:/Users/anna/Desktop/project/data/birthwt.csv describes it from the root of one particular computer, and fails everywhere else. Inside a Project, relative paths are all you need.

You may see scripts that begin with setwd("C:/Users/…") to set the working directory. That line ties the script to one computer, which is exactly what a Project avoids; if you open the project file, as in Setting up R and RStudio, the working directory is already right. Another common first line, rm(list = ls()), deletes the objects in memory but leaves packages loaded and settings changed, so it is not a clean start. Restarting R is.

Create the project with File › New Project in RStudio, so paths are always relative to its folder. Number scripts in the order they run. Each one reads from data/ or results/ and writes to results/ or figures/. Nothing is ever edited by hand.

Numbering also tells a newcomer where to start, and splitting the work into steps means you can rerun only the step you changed. If 02_models.R needs the cleaned data, it should read the file that 01_clean.R wrote to results/, not rely on an object left in memory. A good test is to restart R (Session › Restart R in RStudio) and run the scripts in order; if anything fails, a step depended on something it did not create itself.

Small habits of naming help too. Use lower-case file names without spaces, such as bw_clean.rds, because spaces and capitals cause errors on some systems and in code. Write dates as year-month-day, such as 2026-03-14, so that files sort in date order. And add a short plain-text README at the top of the folder saying where the data came from, what each script does and how to run it. It takes five minutes and is the first file a colleague, or you in a year, will open.

Go deeper: never save the workspace

When you quit, RStudio may offer to save your workspace, every object in memory, to a hidden file called .RData in the project folder. Next time the project opens, those objects come back automatically. That feels convenient, but it hides exactly the problem a clean restart is meant to catch: a script can seem to work only because an object made weeks ago, perhaps by code you have since deleted, is still in memory.

Switch it off once, in Tools › Global Options › General: untick "Restore .RData into workspace at startup" and set "Save workspace to .RData on exit" to Never. Your scripts and the files they write are the record; memory is temporary. If a step is slow, save its result on purpose with saveRDS(fit, "results/fit.rds") and read it back in the next script with readRDS("results/fit.rds"), so the dependency is written in the code.

Reports that rebuild themselves: Quarto

Quarto (built into RStudio) mixes text and code in one document. When you render it, the code runs and the results and figures appear in the report, so the numbers in your text can never fall out of date. Create one with File › New File › Quarto Document.

The idea behind it is called literate programming: the explanation and the code that produces each result live in one file, in reading order. Compare the usual alternative: copying numbers from the console into a word processor. Every time the data or the model changes, each copied number must be found and updated by hand, and one is always missed. A Quarto report is rebuilt from scratch each time you press Render, so every number comes from the current run.

Rendering has a feature that surprises most people at first: Quarto runs the code in a fresh R session, not in the session you are typing in. An object you made in the console, or a package you loaded there, does not exist for the report. A report that fails with "object not found" is telling you that it depended on something it did not create, the same problem a clean restart catches for scripts. Fix it by adding the missing step to a chunk.

Chunks accept options written as special comments on their first lines. #| echo: false runs the code but hides it, which suits a report for readers who do not use R; #| message: false hides package start-up messages. For a long analysis the report does not need to refit everything: a chunk can read what the numbered scripts saved, with readRDS(), so the report stays quick to render while still taking every number from code.

report.qmd
---
title: "Maternal smoking and birth weight"
format: html
---

## Methods
Birth weights (MASS::birthwt, n = 189) were compared by maternal smoking
with Welch's t-test and a linear model adjusted for weight and recorded race.

```{r}
library(MASS)
fit <- lm(bwt ~ lwt + factor(smoke) + factor(race), data = birthwt)
round(coef(fit)["factor(smoke)1"])
```

The adjusted difference was `r round(coef(fit)["factor(smoke)1"])` g.

What this file contains, part by part

  1. The lines between the two --- markers are the header, written in a format called YAML. title sets the report's title, and format: html asks for a web page; pdf and docx are other options.
  2. ## Methods is ordinary text with a heading. The ## marks a second-level heading in Markdown, a simple way of formatting plain text. MASS::birthwt names the dataset with its package, in the same package::object form you met with dplyr::select().
  3. The block that starts with ```{r} and ends with ``` is a code chunk. When the report renders, R runs it and places the code and its output in the page. It loads MASS, fits the same linear model as Correlation and linear regression, and prints the smoking coefficient rounded to whole grams.
  4. Here the model uses factor(smoke) and factor(race) directly on the raw codes, so R names the smoking coefficient factor(smoke)1: level 1 (smoker) compared with level 0. coef(fit)["factor(smoke)1"] picks out that one coefficient by its name.
  5. The final sentence contains `r …`, inline R code, which is replaced by its result.

The last line uses inline code: the number in the sentence is calculated when the report renders, so it always matches the analysis.

This is the same model as lm1 in Correlation and linear regression, so the smoking coefficient is −399.8 and the rendered sentence will read "The adjusted difference was -400 g." If you later correct an error in the data and render again, the sentence updates itself. In a real report you might write the sentence so that the sign reads naturally, for example "babies of smokers were 400 g lighter", by reversing the sign inside the inline code.

For this model, `r -round(coef(fit)["factor(smoke)1"])` would give 400, so the sentence could read "babies of smokers were `r …` g lighter". The same approach works for every number in the text: sample sizes from nrow(), confidence limits from confint(), p-values from a test's $p.value. Report them as the earlier lessons in this module recommend: the effect with its confidence interval, the exact p-value, and the name of the test. A Methods section that names the tests, the factors in each model and the software versions lets a reader repeat the analysis without asking you.

Record what you used

  • set.seed() at the top of any script that uses random numbers, as in Multiple testing and power.
  • sessionInfo() at the end of the report lists R and every package version.
  • The renv package goes further: renv::init() records exact versions, and renv::restore() recreates them on another computer.
  • Git and GitHub keep a history of every change. RStudio has a Git tab built in.

A little more on each. Random numbers matter because simulations, random splits of data and some clustering methods all use them; without a seed, a rerun gives slightly different numbers and nobody can tell whether a change is real. sessionInfo() prints the R version, the operating system and every loaded package with its version number, so a reader knows exactly which software produced the results. renv stores those versions in a file called a lockfile (renv.lock) inside the project, which you share with the code. Git is a version control system: each time you commit, it saves a snapshot of your files with a short message, so you can see what changed, when and why, and go back if something breaks. GitHub is a website that stores a copy of that history online, for backup and sharing.

Keep raw data out of a public GitHub repository if it contains anything identifiable about patients. The code can be shared openly while the data stays where its approvals say it must.

A file called .gitignore in the project folder lists files and folders that Git should not track, such as data/ when the data cannot be shared, or the generated results/ and figures/ that the scripts can rebuild. With renv, the routine is short: renv::init() once when the project starts, renv::snapshot() after you install or update a package to record the new version, and renv::restore() on any other computer to install the recorded versions.

One warning about seeds. A seed makes a random result repeatable; it does not make it right. Trying seed after seed until a simulation or a random split gives a pleasing answer is the same mistake as trying test after test until p falls below 0.05, which Comparing two groups warned against. Choose the seed once, before you look, and if a conclusion changes with the seed, the conclusion was never stable.

Sandve et al. 2013, "Ten simple rules for reproducible computational research" (PLOS Computational Biology), is a short, widely cited summary of the habits in this lesson. The idea of mixing explanation and code comes from Donald Knuth's "Literate programming" (The Computer Journal, 1984). Quarto is documented at quarto.org; its predecessor is covered in Xie, Allaire & Grolemund, R Markdown: The Definitive Guide (Chapman & Hall/CRC, 2018). Cite renv with citation("renv"). One caveat: renv records package versions and the R version, but it does not install R itself or the system libraries beneath it, so a project can still behave differently on a much newer computer.

Key point

The test of a reproducible analysis: delete results/ and figures/, run everything from the top, and get the same report.

An even stronger test is to give the project folder to a colleague, or open it on a second computer, and ask them to render the report without any help from you. Any step that needs you to explain something, such as "first run this line in the console" or "the file is on my desktop", is a step to fix in the scripts.

Further reading · Module 2Greenland et al. 2016: 25 common misreadings of p-values and confidence intervals. · All reading for this course

Check your understanding

1. Why keep raw data in a folder you never edit?

2. What is the main advantage of a Quarto report?

3. What does sessionInfo() record?

Up next

Project

Risk factors for low birth weight

Ask BioTutor

Create a free website with Framer, the website builder loved by startups, designers and agencies.