Reproducible reports

Andrew Irwin, a.irwin@dal.ca

2026-02-24

Plan

  • What is reproducibility?

  • Why should you care?

  • Specific role of

    • Quarto or R markdown
    • git and GitHub

  • Skills to learn today

  • Communication, trust, and error detection

What makes work reproducible?

  • Clear documentation of all steps and tools used

  • Ease of reproducing the work

  • Consider the consequences of small changes to

    • data
    • visualization formatting

  • Consider the consequences of a change in team membership

Why do I care if my work is reproducible?

  • Helps “future you”

  • Lets you make changes, update data, fix errors easily

  • Improves communication

  • Increases value of your work

What is the role of Quarto?

Combines

  • explanation

  • R code

  • results

Allows you to generate a final report.

Easy to detect if a report is complete (Does it render without errors?)

What is the role of git and GitHub?

  • Allows you to make versions, track changes in code, data, and report

  • Makes it easy to share with others

  • Facilitates team work

Detailed observations for this course

  • Always check that your document can be rendered (to HTML)

  • Don’t use absolute paths to files on your computer (/Users/airwin/Documents/xxx)

    • Use Rprojects and here instead

  • Carefully format text in R markdown reports

    • Headings with #
    • Bullet points with indented * or -
    • Bold and italics formatting with *, ** around words

  • Control output from R with “chunk options”

Ten simple rules

  1. Track how results were produced
  2. Avoid manual manipulation of data
  3. Version control
  4. Hierarchical analysis output, revealing layers of detail
  5. Connect explanatory text to underlying results
  6. Record intermediate results in standard formats
  7. Archive exact versions of software
  8. Record random number seeds
  9. Store the raw data used to make plots
  10. Provide public access to scripts and results

Adapted from Sandve et al. 10.1371/journal.pcbi.1003285

Further reading

The course notes are quite different from these slides. They emphasize practical skills and tips.

The course notes contain specific suggestions for using Quarto or R markdown which will be explored in the task for this lesson.

Exercise

  • Practice specific tasks for formatting Quarto documents from course notes