Reproducible Reports with Quarto

PSY 410: Data Science for Psychology

Dr. Sara Weston

2026-04-20

What is literate programming?

Session 7 (Week 4, Mon Apr 20). 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(here("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(here("data", "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.

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, 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. They don’t need to worry about inline code yet — that’s coming after the break.

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 — it’s built into ggplot2, just type mpg)
4. Create a visualization in its own chunk
5. Render to HTML

Time: 10 minutes

Solution: Create a mini-report

# Save this as a .qmd file, then click Render:

# ---
# title: "Car Fuel Efficiency Analysis"
# author: "Your Name"
# date: today
# format: html
# ---

# ## Introduction
# This report examines fuel efficiency using the `mpg` dataset.
# We explore the relationship between engine size and highway economy.

# ```{r}
# #| include: false
# library(tidyverse)
# ```

# ```{r}
# ggplot(mpg, aes(x = displ, y = hwy)) +
#   geom_point() +
#   geom_smooth(method = "lm") +
#   labs(x = "Engine size (L)", y = "Highway MPG") +
#   theme_minimal()
# ```

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(mean(depression_scores), 2)`

Without round(), you might get 15 decimal places. Always round inline results.

round() is the formatting function they’ll use most. Emphasize: if your inline code prints something like 19.0000000000001, you forgot to round. The second argument is the number of decimal places. This is a habit to build now — every inline number should be rounded.

A note on output formats

Quarto can also render to PDF and Word — but these require installing additional (free) software.

For this course, we’ll stick with HTML documents. They’re easy to create, easy to share, and work on any device.

Keep this brief. If students ask: PDF requires a LaTeX installation (TinyTeX), Word output works out of the box but has less control over formatting. Both are free but add setup complexity we don’t need right now. HTML is the simplest path and what they’ll submit for assignments.

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()

Table code goes inside a code chunk, just like plots. The knitr::kable() function turns a data frame into a nicely formatted table:

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 here() for file paths — here("data", "file.csv") always finds the project root

“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
├── my-analysis.html
└── data/
    └── survey_data.csv

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

Use here() to build file paths: read_csv(here("data", "survey_data.csv")) always works, no matter where RStudio thinks the working directory is.

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. Emphasize here() — it always finds paths relative to the project root, avoiding the “it works on my laptop but not yours” problem. They learned about here in Session 6 (Data Import); this is where it pays off.

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!
• Tables — knitr::kable() inside code chunks for formatted tables
• here() for file paths that always work
• 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 9: Layers

✅ Do:

• Start working on Assignment 3 — your first Quarto submission

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 Wednesday for Layers & Aesthetics — we’ll build on your ggplot skills with new geoms and customization options.

End-of-deck exercise

This exercise is a direct head start on Assignment 3 — A3 is the first Quarto submission, so students should leave class with a working .qmd skeleton that imports both A3 data files. Give ~10 minutes. They probably won’t finish, and that’s fine — priority is a successful first render. Walk around and help with rendering errors, especially YAML indentation and missing package loads, which will be frequent. Remind them this same workflow is used for every assignment from A3 onward.

Head start: Assignment 3

Assignment 3 is your first Quarto submission. Start scaffolding it now:

1. Create a new .qmd with a YAML header (title, author, format: html)
2. Add sections: Introduction, Data, Results
3. Setup chunk that loads tidyverse, readxl, and here (#| include: false)
4. Import the A3 data files using here() (e.g., read_csv(here("data", "survey_data.csv")))
5. glimpse() each in its own chunk
6. Report one summary statistic with inline code in the narrative
7. Render to HTML — fix any errors before you leave class

Tip

This is the workflow you’ll use for every assignment from A3 onward.

# --- SOLUTION EXAMPLE ---
# Save this as a .qmd file (e.g., assignment-3.qmd):

# ---
# title: "Assignment 3"
# author: "Your Name"
# date: today
# format: html
# ---

# ## Setup

# ```{r}
# #| label: setup
# #| include: false
# library(tidyverse)
# library(readxl)
# library(here)
# ```

# ## Introduction
# This report imports and explores two datasets related to [topic].

# ## Data

# ```{r}
# #| label: load-survey
# survey_data <- read_csv(here("data", "survey_data.csv"),
#                         na = "N/A")
# glimpse(survey_data)
# ```

# ```{r}
# #| label: load-demographics
# demographics <- read_excel(here("data", "demographics.xlsx"),
#                            sheet = 2)
# glimpse(demographics)
# ```

# ## Results
# The survey included `r nrow(survey_data)` participants.
# The mean age was `r round(mean(demographics$age, na.rm = TRUE), 1)` years.