Reproducible Reports with Quarto

PSY 410: Data Science for Psychology

Dr. Sara Weston

2026-05-27

What is literate programming?

This is Session 7 (Week 4, Mon Apr 20), even though the file is numbered 16. Quarto was moved earlier in the curriculum so students use it for all assignments from A3 onward. Assignment 3 (Tidying, Import & Quarto) is assigned today. Structure: ~25 min lecture, ~15 min pair coding, ~20 min lecture part 2, ~10 min work time. Open with the callback to Session 1 — this is the payoff for the replication crisis discussion.

Remember Session 1?

We opened this course with a striking finding: only 36% of psychology studies replicated.

Part of the problem was that analyses couldn’t be reproduced — even by the original authors. Data was cleaned by hand. Numbers were copied into Word documents. Code only ran on one laptop.

Quarto is part of the solution. Today we learn to write documents where the analysis is the report.

Spend ~3 minutes on this opening. Let the callback land — they’ll remember the 36% stat from Session 1. The three-part incremental reveal builds the problem before offering the solution. Emphasize that this isn’t just an academic problem: “Data cleaned by hand” and “code only ran on one laptop” are things that happen in real labs right now.

Copy-paste workflows break when anything changes

Step 1: Analyze in R

# script.R
data <- read_csv("data.csv")
mean(data$depression)
# 18.5

Step 2: Copy to Word > “The mean depression score was 18.5 (SD = 5.2).”

Walk through this scenario concretely. Ask: “How many of you have written a paper where you ran the analysis in one program and typed the results into Word?” Most hands will go up. This is the problem Quarto solves. The two-column layout makes the disconnect visual — code on the left, Word on the right, no connection between them.

What goes wrong?

• Typos when copying numbers
• If data changes, you have to update manually
• No record of what code produced what result
• Can’t reproduce your own analysis in 6 months

Ask students to name other things that can go wrong. Common answers: forgetting to update a table, accidentally reporting results from an old version of the data, not remembering which script produced which figure. All of these are solved by having the code and the report in the same document.

Literate programming approach

One document contains:

• The code
• The results (automatically generated)
• The narrative (your interpretation)

Benefits:

• No copy-paste errors
• Data changes → results update automatically
• Complete record of what you did
• Easy to share with collaborators

The term “literate programming” comes from Donald Knuth (1984). You don’t need to go into the history, but if students ask, it’s the idea that programs should be written for humans to read, not just for computers to execute. The key concept: one document contains code, results, and narrative. No separation, no copying.

Introducing Quarto

Quarto is a publishing system that combines:

• Markdown for writing text
• R code chunks for analysis
• Output formats (HTML, PDF, Word)

It’s the evolution of R Markdown (same company, newer technology).

Students sometimes find R Markdown resources online and get confused. Reassure them: Quarto is the successor. The syntax is very similar, so R Markdown tutorials are mostly transferable. If they encounter .Rmd files, those are R Markdown; .qmd files are Quarto. For this course, we use Quarto exclusively.

Anatomy of a Quarto document

Three main components

1. YAML header — metadata (title, author, format)
2. Markdown text — your narrative
3. Code chunks — your R code

This section covers the three building blocks. Spend about 12 minutes total on YAML, markdown, and code chunks before moving to chunk options. Consider doing a live demo in RStudio alongside these slides — create a new .qmd file and walk through each component as you go.

YAML header

At the top of every .qmd file:

---
title: "My Analysis Report"
author: "Your Name"
date: "2026-05-27"
format: html
---

This controls:

• What appears at the top of the document
• What format to render (HTML, PDF, Word)
• Various options (table of contents, theme, etc.)

YAML (rhymes with “camel”) stands for “YAML Ain’t Markup Language.” Students will inevitably ask how to pronounce it. The key thing to emphasize: YAML is picky about indentation and spacing. Common errors include missing the closing ---, using tabs instead of spaces, or forgetting colons. If students get mysterious rendering errors, YAML formatting is the first place to check.

Markdown basics

Markdown is a simple way to format text:

# Heading 1
## Heading 2
### Heading 3

**bold text**
*italic text*

- Bullet point
- Another bullet

1. Numbered list
2. Second item

[Link text](https://example.com)

Markdown in action

You write:

**Depression** is a common
mental health condition.

Our research questions:

1. Does CBT reduce depression?
2. Do effects persist?

You get:

Depression is a common mental health condition.

Our research questions:

1. Does CBT reduce depression?
2. Do effects persist?

Move through the markdown slides quickly — students pick this up fast and most have seen basic formatting before (Google Docs, Slack, Discord). The side-by-side “you write / you get” layout is effective here. Point out that markdown is used everywhere, not just Quarto — GitHub, Slack, Reddit, etc. If anyone has used those, they already know markdown basics.

Code chunks

Surround R code with three backticks:

```{r}
# Load data
data <- read_csv("depression_data.csv")

# Compute mean
mean(data$depression)
```

When you render, both the code and output appear in the document.

This is where the magic happens for students. Emphasize that the {r} tells Quarto “this is R code, run it.” The triple backticks mark the boundaries of the chunk. Common mistake: students forget the closing backticks, which causes everything below to be treated as code. If doing a live demo, type a chunk, run it, and show the output appearing right below.

Running code chunks

In RStudio:

• Run current chunk: Click green arrow or Ctrl/Cmd + Shift + Enter
• Run one line: Ctrl/Cmd + Enter (like in scripts)
• Run all chunks above: Button in toolbar

Emphasize the green arrow — students will use this constantly. Also note that Ctrl/Cmd + Enter works just like in scripts, so the workflow they already know still applies within chunks. “Run all chunks above” is useful for debugging when something breaks midway through a document.

Rendering the document

Render = convert your .qmd to the final output (HTML/PDF/Word)

Click the Render button (or Ctrl/Cmd + Shift + K)

Quarto will:

1. Run all the R code
2. Capture the output
3. Combine with your text
4. Create the final document

Key distinction students miss: running a chunk (green arrow) is for interactive development. Rendering (Render button) is for producing the final document. When you render, Quarto starts fresh — it doesn’t use objects from your environment. This is a common source of confusion: “It works when I run it but fails when I render.” The answer is always that something wasn’t loaded or created in the document itself.

Code chunk options

This is the most detail-heavy section. Spend about 8 minutes here. Students don’t need to memorize every option — they need to know where to look them up and understand the most common ones (echo, eval, include).

Controlling output

Add options with #| at the top of a chunk:

```{r}
#| echo: false
#| eval: true

# This code runs but doesn't show in the output
mean(depression_scores)
```

Point out the #| syntax — this is the “hash-pipe” and it’s Quarto-specific (R Markdown used chunk header options). Students sometimes forget the space after #|. The key concept: you can independently control whether code runs (eval) and whether code shows (echo). This gives four combinations, but only three are useful (there’s no point in showing code that doesn’t run AND hiding the output).

Common chunk options

Option	What it does	When to use
echo: false	Hide the code, show results	Final reports
eval: false	Show code, don’t run it	Example code
include: false	Run code, hide everything	Loading packages
message: false	Hide messages	Loading tidyverse
warning: false	Hide warnings	Final reports

Walk through the table row by row. The most confusing one for students is the difference between echo: false and include: false. The key: echo: false hides the code but shows the output (a figure, a number, a table). include: false hides everything — it’s as if the chunk doesn’t exist in the output, but the code still runs behind the scenes. This is exactly what they want for their setup chunk.

Figure options

```{r}
#| fig-width: 8
#| fig-height: 6
#| fig-cap: "Depression scores by condition"

ggplot(data, aes(x = condition, y = depression)) +
  geom_boxplot()
```

• fig-width / fig-height — size in inches
• fig-cap — adds a caption below the figure

Figure options are something students will use immediately in their assignments. Emphasize that fig-cap is how you add proper figure captions — not by writing “Figure 1: …” in your text. The caption is tied to the figure, so if you reorder things, the caption moves with the figure.

Example: Setup chunk

Every document should start with a setup chunk:

```{r}
#| label: setup
#| include: false

library(tidyverse)
library(here)
```

• include: false means the chunk runs but nothing shows in the output
• Load all your packages here so they’re available throughout

Emphasize the convention: every Quarto document should start with a setup chunk that loads packages and, optionally, reads in data. This is a habit they should build now. The label: setup name is conventional but not required; what matters is include: false so readers don’t see the library loading messages.

Inline code

This is the feature that sells Quarto to most students. When they see that they can type a formula in their text and have it automatically update when the data changes, it clicks. Spend ~5 minutes here and make sure the concept lands.

Embedding results in text

Never hard-code numbers!

❌ Bad:

The mean depression score was 18.5 (SD = 5.2).

✅ Good:

The mean depression score was `r mean(data$depression)`
(SD = `r sd(data$depression)`).

Why inline code matters

# Create sample data
depression_scores <- c(12, 18, 25, 22, 15, 20, 19, 21)

In your text, you write r expression and Quarto fills in the result.

The “never hard-code numbers” rule is the single most important Quarto habit. If a student writes “The mean was 18.5” in their report, they have a time bomb — the number will become wrong the moment anything about the data changes. Inline code means the number always matches the data. Students often ask: “But what if I know the number won’t change?” The answer: you never know that for certain. Build the habit now.

Inline code: before and after

You write:

The mean score was
`r mean(depression_scores)`
(SD = `r round(sd(depression_scores), 2)`).

Quarto renders:

The mean score was 19 (SD = 4.07).

The side-by-side layout shows the raw syntax on the left and the rendered result on the right. Point out the backtick-r pattern: backtick, the letter r, a space, then the R expression, then a closing backtick. Common mistake: students use regular backticks (code formatting) instead of the inline code syntax. If the expression shows as literal text instead of a number, they forgot the r.

Formatting inline results

Use round() to control decimal places:

`r round(cor(x,y), 2)`

Use scales::percent() for percentages:

`r scales::percent(0.653)`

Use scales::comma() for large numbers:

`r scales::comma(15234)`

These formatting functions are practical tools. round() is the one they’ll use most — without it, inline code might print 15 decimal places. scales::percent() and scales::comma() are nice to know but not essential. If short on time, just cover round().

Pair coding break

This is the main hands-on exercise. Give students 10 minutes. Walk around and help — the most common issues will be: YAML formatting errors (missing dashes, wrong indentation), forgetting to close code chunks, inline code syntax errors, and render failures because of missing packages or objects. Remind them to create a new .qmd file from the RStudio menu (File > New File > Quarto Document), not by hand.

Your turn: Create a mini-report

Create a new Quarto document (File → New File → Quarto Document):

1. Add a YAML header with your name and title
2. Write a short introduction (2-3 sentences)
3. Create a code chunk that loads tidyverse and a dataset (try mpg)
4. Create a visualization
5. Write a sentence with inline code reporting a summary statistic
6. Render to HTML

Time: 10 minutes

Output formats

Transition to the second half. Spend ~5 minutes on output formats — this is informational, not hands-on. For this course, students will primarily use HTML. But they should know that the same .qmd file can produce Word or PDF, which is relevant for their future work.

HTML (default)

---
title: "My Report"
format: html
---

Pros:

• Interactive (can include interactive plots)
• Easy to share (just send the file)
• Works on any device
• Can have code folding, tabs, etc.

Cons:

• Not suitable for print journals

HTML is the default and what students should use for this course. If students ask about sharing HTML files: the rendered .html is a single self-contained file that opens in any browser. No special software needed to view it.

PDF

---
title: "My Report"
format: pdf
---

Pros:

• Print-ready
• Professional appearance
• Standard for journals

Cons:

• Requires LaTeX installation
• Less flexible for complex layouts
• Not interactive

Students will inevitably ask about PDF. The honest answer: PDF requires a LaTeX installation (like TinyTeX), which can be finicky to set up. Don’t spend class time on it. If students want PDF for their final project, they can install TinyTeX with quarto install tinytex outside of class. For this course, HTML is fine.

Word

---
title: "My Report"
format: docx
---

Pros:

• Collaborators can edit with Track Changes
• Familiar to everyone
• Required by some journals

Cons:

• Less control over formatting
• Can be finicky with complex tables/figures

Multiple formats

You can render to multiple formats:

---
title: "My Report"
format:
  html:
    toc: true
  pdf:
    toc: true
  docx: default
---

Then choose which to render in RStudio dropdown.

Tables

Tables are a practical skill students need for their assignments and final project. Spend ~5 minutes here. The focus is on knitr::kable() — it’s simple, it works across all output formats, and it’s good enough for most purposes.

Simple tables with kable()

therapy_summary <- tibble(
  Condition = c("Control", "CBT", "Mindfulness"),
  N = c(30, 30, 30),
  Mean = c(18.2, 12.4, 14.1),
  SD = c(5.1, 4.8, 5.3)
)

knitr::kable(therapy_summary)

Show the contrast: without kable(), R prints a tibble with its default console formatting. With kable(), you get a proper HTML table. The difference is dramatic in the rendered output. If doing a live demo, show both versions side by side.

Simple tables with kable()

Condition	N	Mean	SD
Control	30	18.2	5.1
CBT	30	12.4	4.8
Mindfulness	30	14.1	5.3

Kable options

knitr::kable(
  therapy_summary,
  digits = 1,
  caption = "Depression scores by treatment condition",
  col.names = c("Condition", "N", "M", "SD")
)

Depression scores by treatment condition

Condition	N	M	SD
Control	30	18.2	5.1
CBT	30	12.4	4.8
Mindfulness	30	14.1	5.3

Point out the three most useful options: digits controls decimal places (students will need this), caption adds a table title, and col.names lets you rename columns for presentation without changing the underlying data. The col.names pattern is important — students should keep their data columns as clean variable names and only pretty-print them in the table output.

Fancier tables: gt package

For publication-ready tables:

library(gt)

therapy_summary |>
  gt() |>
  tab_header(title = "Treatment Outcomes",
             subtitle = "Post-intervention BDI-II scores") |>
  fmt_number(columns = c(Mean, SD), decimals = 1)

gt is powerful but beyond our scope — use kable() for now.

Mention gt briefly as something that exists for when they need fancier tables, but don’t dwell on it. For this course, kable() is sufficient. If students are curious, they can explore gt on their own.

Workflow tips

Best practices

1. Name your chunks — easier to find errors (#| label: load-data)
2. One setup chunk at the top — load all packages there
3. Render often — catch errors early

4. Use relative paths — here::here("data/file.csv")
5. Cache expensive computations — #| cache: true

“Render often” is the most important tip. Students who write an entire document and render at the end will hit a wall of errors and not know where they started. Encourage them to render after every new chunk or section. Also, naming chunks (#| label: something) means that when Quarto throws an error, it tells you which chunk failed — invaluable for debugging.

Structuring a psychology report

## Introduction
- Background
- Research question

## Method
- Participants
- Measures
- Procedure

## Results
- Descriptive statistics
- Main analyses
- Figures

## Discussion
- Interpretation
- Limitations

This maps directly to an APA-style paper. Point out that Quarto makes this structure natural — each heading becomes a section, and the code chunks live right next to the text that interprets them. Students should start structuring their final project .qmd file this way now. Emphasize that the Results section is where the code-narrative integration really shines.

Project organization

project/
├── my-analysis.qmd
├── data/
│   └── survey_data.csv
├── scripts/
│   └── helper_functions.R
└── output/
    ├── my-analysis.html
    └── figures/

Keep your .qmd file in the root, data in data/, outputs separate.

This connects back to Session 1’s filing cabinet metaphor. A well-organized project folder means anyone (including future you) can find the data, the code, and the output. The .qmd file goes in the root because it references everything else with relative paths. If students ask about here::here(), explain briefly that it always finds paths relative to the project root, avoiding the “it works on my laptop but not yours” problem.

End-of-deck exercise

This exercise is a head start on Assignment 3 and also scaffolds the final project. Give students ~10 minutes of work time. They probably won’t finish, and that’s fine — the point is to get started and identify questions. Walk around and help with rendering errors, which will be frequent.

Create your final project draft

Convert your final project draft to a Quarto document (.qmd):

1. Structure it with sections: Introduction, Method, Results, Discussion
2. Include a setup chunk, data import code, and 2-3 captioned visualizations
3. Report at least one summary statistic with inline code
4. Add a table of descriptive statistics with kable()
5. Render to HTML and review

This will become your final project report!

Wrapping up

Transition to the closing. Keep this section brisk — ~3 minutes to wrap up.

Why Quarto matters

For you:

• Never lose track of what code produced what result
• Update analysis when data changes
• Professional-looking reports with minimal effort

For science:

• Reproducibility — others can verify your work
• Transparency — full record of your analysis
• Sharing — collaborators can build on your work

This is the “why should I care?” slide. The personal benefits (no lost analyses, automatic updates) are immediate. The science benefits (reproducibility, transparency) are what they’ll appreciate later. Connect back to Session 1 one more time: if every researcher used Quarto, the replication crisis would be smaller.

Quarto beyond this course

Quarto can create:

• Books — entire textbooks with chapters
• Websites — personal sites, lab sites
• Presentations — like these slides!
• Dashboards — interactive data apps
• Journal articles — many journals accept Quarto

You’re learning a tool you’ll use for years.

This slide is motivational — “these slides” is a fun reveal (this very presentation was made with Quarto). If students are interested in making their own websites or presentations, point them to quarto.org. The main message: Quarto isn’t just a class requirement; it’s a professional tool with a long shelf life.

Key takeaways

• Quarto documents = YAML + markdown + code chunks
• Chunk options (echo, eval, include) control what appears
• Inline code embeds results in text — never hard-code numbers!
• Output formats — HTML, PDF, Word from the same source
• Tables — knitr::kable() for simple, gt for fancy
• Reproducibility — future you will thank you

Resources

• R4DS Ch 28: Quarto (comprehensive guide)
• Quarto website: quarto.org
• RStudio Quarto tutorial: posit.co/blog/quarto-rstudio/
• Markdown guide: markdownguide.org

Before next class

📖 Read:

• R4DS Ch 8: Workflow: getting help

✅ Do:

• Submit Assignment 8 — Create a complete reproducible report
• Continue working on your final project
• Practice rendering to different formats

The one thing to remember

Quarto means your analysis and your report are the same document. Change one, the other updates. That’s reproducibility.

See you Monday for practice & review!