23  Reproducible Reports with Quarto

A number read off the console and typed into a sentence takes four seconds, and it is a very reasonable thing to do. It also breaks the connection between the analysis and the claim. Suppose the data are corrected and the analysis is re-run. The figures update and the sentence does not, and nothing tells you so. Literate programming closes that gap. The sentence carries the code that computes its number, so the number cannot drift from the analysis. Quarto is the current tool for doing this in R. Most of this chapter is about the few places where it can still let a stale number through.

Let us change our traditional attitude to the construction of programs: Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

Donald E. Knuth, Literate Programming (1984)

Diagram of the analysis pipeline: six stages in order (Plan, Acquire, Wrangle, Analyze, Report, Share) above two bands that run under every stage (Version control and Environment). Highlighted for this chapter: Report.
Figure 23.1: Where this chapter sits: Quarto is the Report stage, which turns code and derived data into the document a reader sees.
NoteIn this chapter

Reading time. About 35 minutes.

You’ll need. Chapter 6 for an installed Quarto (quarto check confirms it), and Chapter 18 for the row-count check in the worked example. The executed code uses base R and the quarto command-line tool, so it needs no library() call.

You’ll be able to.

  • Replace every number typed into prose with inline code, and show that the numbers change when the data do.
  • Label figures, tables, and sections so that a reference to a missing one is reported at render time instead of going unnoticed.
  • Choose between freeze and cache for an expensive computation, and predict when each will serve a stale result.
  • Render one report per site from a single parameterized source.
  • Control where LaTeX places figures and tables in PDF output.
  • Diagnose a failing render from its log, and find the silent failures a successful render can hide.

Outline.

If these answers come quickly, skip to the next chapter. The answers are in Section 23.14.

  1. What is ‘literate programming’, and how does a .qmd file embody it?
  2. Given a Quarto document that contains R code and prose, what single command renders it to an HTML file, and how does Quarto decide which output format to produce?
  3. What is the purpose of execute: freeze: auto in a Quarto project, and what problem does it solve?
  4. Why do tables and figures in rendered PDFs often appear in unexpected places, and what do fig-pos and tbl-pos do?

23.1 Literate programming and the inline number

Donald Knuth’s idea (Knuth, 1984) was that source code and prose should live in one document, with the prose explaining the code as one person would explain it to another. Quarto implements it with code chunks and prose interleaved in a .qmd file. The part that matters most for a statistician is the smallest: an inline expression, which puts a computed value inside a sentence.

We compared the 30-day composite outcome between the randomized
arms.

```{r}
obs <- trial[!is.na(trial$event_30d), ]
rates <- tapply(obs$event_30d, obs$arm, mean)
```

Readmission or death within 30 days occurred in
`{{r}} round(100 * rates[["Usual care"]], 1)`% of patients
under usual care.

Rendering runs the chunk, evaluates the inline expression, and writes its value into the sentence. Re-render after the data change and the sentence changes with them. Copying the number into Word instead is where ‘I forgot to update Table 2’ comes from.

What to compute inline is the author’s decision, and the rule is simple: any number that depends on the data. That includes the sample size in the abstract, the count of exclusions in the methods, every estimate and interval, and the p-value that a reviewer will check against the table. A manuscript with p < 0.05 typed into it is correct only until the next extract.

23.1.1 The minimum document

---
title: "HF-HOME interim summary"
format: html
---

Some prose here.

```{r}
1 + 1
```

Save it as analysis.qmd and render it from the shell with quarto render analysis.qmd, which writes analysis.html. The format: key decides the output; with none, Quarto writes HTML. One source can produce several formats. That keeps a single source of truth for the website, the journal, and the collaborator who edits only in Word. The price is the set of constraints in Table 23.1.

Table 23.1: One source, three outputs. List several formats under format: to render them all at once.
Format Command What it cannot carry
HTML quarto render analysis.qmd --to html Nothing that matters here; it is the most capable target
PDF quarto render analysis.qmd --to pdf Interactive HTML widgets; needs a LaTeX installation (quarto install tinytex)
Word quarto render analysis.qmd --to docx Fine typographic control; LaTeX math is converted and may need checking

Question. Your manuscript says ‘The mean age was 67.3 years (SD 12.1)’, typed in from the console. What is wrong with this, and what is the Quarto fix?

Answer. The numbers are detached from the data. Re-run the analysis on corrected data and the prose still says 67.3 and 12.1, while every table beside it has moved. The fix is inline computation:

The mean age was `{r} round(mean(d$age, na.rm = TRUE), 1)`
years (SD `{r} round(sd(d$age, na.rm = TRUE), 1)`).

The prose is now computed at render time, so a re-render on new data updates it. It is still possible for the rendered document to be stale, if the code was not re-run; Section 23.3 is about when that happens.

23.1.2 Exercises

  1. Write the sentence ‘The mean age at index discharge was X years (SD Y), and Z patients were older than 89’ for the HF-HOME demographics file (file.path('..', 'data', 'raw_data', 'hfhome', 'demographics.csv')), with every number inline. Compute the values in a chunk so that you can check the rendered sentence against them.

The sentence, with its setup chunk:

```{r}
#| include: false
demo <- read.csv(file.path("..", "data", "raw_data", "hfhome",
                           "demographics.csv"),
                 colClasses = c(patient_id = "character"))
```

The mean age at index discharge was
`{{r}} round(mean(demo$age), 1)` years
(SD `{r} round(sd(demo$age), 1)`), and
`{{r}} sum(demo$age > 89)` patients were older than 89.

The values it should render:

demo <- read.csv(file.path("..", "data", "raw_data", "hfhome",
                           "demographics.csv"),
                 colClasses = c(patient_id = "character"))
c(mean = round(mean(demo$age), 1), sd = round(sd(demo$age), 1),
  over_89 = sum(demo$age > 89))
#>    mean      sd over_89 
#>    71.5    10.8   127.0

The count of patients over 89 matters beyond this chapter: ages above 89 are an identifier under the HIPAA (Health Insurance Portability and Accountability Act) Safe Harbor method (Chapter 4), so a de-identified extract would not let you compute it, and the sentence would have to change.

23.2 Chunks, cross-references, and citations

23.2.1 Chunk options

A chunk’s options sit at its top, one per line after #|:

```{r}
#| label: fig-outcome-by-arm
#| fig-cap: "30-day readmission or death by randomized arm"
#| fig-width: 6
#| echo: false

ggplot(obs, aes(arm, fill = factor(event_30d))) +
  geom_bar(position = "fill")
```
Table 23.2: Chunk options in common use.
Option Effect Typical use
echo: false Runs the code, shows the output, hides the code Papers; keep true for teaching and review
include: false Runs the code, shows nothing Setup chunks that read data and load packages
eval: false Shows the code, does not run it Code that must not execute, such as a deployment command
warning: false, message: false Suppresses warnings or messages A chunk whose warnings you have read and judged harmless
label: fig-... Names the chunk and makes it a cross-reference target Every figure and table you refer to
fig-cap, fig-width, fig-height Caption and size of the figure Every figure
cache: true Reuses the chunk’s stored result (Section 23.3) An expensive chunk in a single document

The front matter is the YAML (YAML Ain’t Markup Language) header between the --- lines at the top of the file. Set defaults for every chunk under its execute: key, for example echo: false, and override them per chunk.

WarningPitfall

A global warning: false hides the warnings that make failures loud. dplyr‘s many-to-many join warning (Chapter 18), glm()’s ’fitted probabilities numerically 0 or 1’, and a date parser’s ‘failed to parse’ are each the only sign of a wrong number. With warning: false set under execute:, none of them reaches the rendered document, where a reader would see it. Leave warnings on while the analysis is changing. Suppress them per chunk, after you have read them.

23.2.2 Cross-references

Label a figure, table, equation, or section, and refer to it by label; Quarto numbers it and writes ‘Figure 3’ or a link.

See @fig-outcome-by-arm for the outcome by arm.

```{r}
#| label: fig-outcome-by-arm
#| fig-cap: "30-day readmission or death by randomized arm"
ggplot(obs, aes(arm, fill = factor(event_30d))) + geom_bar()
```
Table 23.3: Cross-reference prefixes.
Prefix Labels Where the label goes
fig- Figures The chunk’s label: option
tbl- Tables The chunk’s label:, or {#tbl-...} after a pipe table’s caption
eq- Equations {#eq-...} after the closing $$
sec- Sections {#sec-...} after the heading, as in # Methods {#sec-methods}

The same source produces hyperlinks in HTML, numbered references in PDF, and field codes in Word.

23.2.3 Citations

Point the front matter at a BibTeX file and a citation style, and cite by key:

bibliography: references.bib
csl: https://www.zotero.org/styles/jama
This builds on prior work [@bryan2019happygit; @marwick2018rrtools].
@wickham2019advr discusses copy-on-modify in detail.

[@key] gives a parenthetical citation and @key a textual one; separate several keys with semicolons. The CSL (Citation Style Language) file sets the journal’s format, so changing journals means changing one line. Start the .bib file on the first day: backfilling the citations of a finished draft is slow, and a methods section whose references were typed by hand cannot be reformatted or checked.

Question. You write @fig-trajectory in the prose, but the chunk that should produce the figure is display-only, so the label never exists. What happens when you render, and why is that better than writing ‘Figure 3’?

Answer. Quarto prints WARN: Unable to resolve crossref @fig-trajectory and renders the reference as ?@fig-trajectory. The build completes, but the defect is visible in the log and in the output. Written as ‘Figure 3’, the reference is only a string. Insert a figure earlier and the sentence points at the wrong one, with nothing to warn you. Cross-references turn the errors that revision introduces into build warnings. Inline code does the same for numbers.

23.2.4 Exercises

  1. Convert a short .R script of yours into a .qmd that renders to both HTML and PDF, with one captioned figure, one cross-reference to it, and one citation from a .bib file.

A correct result renders both formats without a WARN line, shows ‘Figure 1’ (or a link) where you wrote the reference, and ends with a reference list in both outputs. Two failures are common. A reference rendered as ?@fig-... means the label is missing or misspelled, or the chunk did not run. A citation rendered as its bare key, with a ‘citation not found’ warning, means the key is not in the .bib file the front matter names. If the PDF fails with a LaTeX error, run quarto install tinytex.

23.3 Freeze and cache

A ten-second analysis can run on every render; a ten-minute bootstrap or an MCMC (Markov chain Monte Carlo) fit cannot. Quarto offers two ways to store a result and reuse it. They differ in scope, in what makes them re-run, and in when they are ignored (Table 23.4). The rule for both is the same. Store a result only when the computation is expensive and deterministic, and re-run anything that is cheap or could change.

Table 23.4: freeze and cache compared.
freeze (Quarto) cache (knitr)
Set with execute: freeze: auto in _quarto.yml or a document’s front matter cache: true on a chunk, or under execute:
Scope A whole document One chunk
Applies Only inside a Quarto project (a directory with _quarto.yml) In any document
Stored in _freeze/ at the project root A <document>_cache/ directory beside the document
Re-executes when auto: any change to the document’s source, even one character, re-runs the whole document; true: never during a project render; false (the default): always The chunk’s code or options change
Ignored when You render a single file or a subdirectory, which always executes Never ignored by the kind of render
Does not notice Changed data files, packages, or R version Changed data files, packages, or upstream chunks (unless dependson names them)
Commit to Git? Commonly, so that collaborators and automated builds reuse expensive results Usually not

The two consequences in the ‘Ignored when’ row often surprise people. First, quarto render analysis.qmd executes the document whatever freeze says, so freeze speeds up only full project renders. Second, a stand-alone .qmd outside any project has no _freeze/ at all. For chunk-level reuse there, use cache: true.

_freeze/ can be committed to Git. A collaborator or a continuous-integration (CI) build that renders the project then reuses the stored results instead of re-running a long analysis (Chapter 8 discusses the merge conflicts this can bring). We note that the stored results are whatever the last execution produced. A randomized chunk that sets its own seed reproduces them when it does re-run. One that does not set a seed will produce different numbers from the stored ones.

WarningPitfall

Neither freeze nor cache sees the data. Both decide whether to re-run by looking at code. Suppose you replace data/trial.csv with a new extract. A project render under freeze: auto then serves the old numbers, with no warning, because the .qmd did not change. A cached chunk that reads the file does the same. This is the typed-number failure again, one level down. The worked example below shows it happening. After a data change, render the document itself, or delete its entry in _freeze/. For a cached chunk, add cache.extra: !expr tools::md5sum("data/trial.csv"), which makes the file’s checksum part of what the cache compares.

Question. A project uses freeze: auto. You fix a typo in the discussion of results.qmd and run quarto render. Which chunks re-execute?

Answer. Every chunk in results.qmd, and none in any other document. Freeze works per document, so any change to the source, prose included, invalidates the whole document’s stored results. If you wanted only the expensive chunk protected, that is cache: true on the chunk, whose key is the chunk’s own code.

23.3.1 Exercises

  1. For each scenario, say whether the code re-executes:
    1. project render, freeze: auto, prose edited;
    2. project render, freeze: auto, data file replaced;
    3. quarto render report.qmd with freeze: true;
    4. cache: true chunk, an upstream chunk edited;
    5. cache: true chunk, its own code edited.
Table 23.5: Exercise 3 key.
Scenario Re-executes? Why
(a) Yes, the whole document auto watches the source, and prose is source
(b) No Freeze does not see data files; the results are stale
(c) Yes A single-file render ignores freeze
(d) No The cache key is the chunk’s own code; add dependson
(e) Yes The chunk’s code is its cache key

Scenarios (b) and (d) are the dangerous ones, because each produces a document that looks current.

23.4 Worked example: a report that survives a new extract

The example builds a one-paragraph HF-HOME report in a temporary Quarto project with freeze: auto, renders it against an interim extract, then replaces the data with the full extract and renders it twice more. It runs the real quarto command, so the output below is what you would see.1

1 The env argument passes this session’s library paths to the R process that Quarto starts, so that it finds the same packages. In a terminal you would type quarto render alone.

hf_dir <- file.path("..", "data", "raw_data", "hfhome")
read_hf <- function(file) {
  read.csv(file.path(hf_dir, file),
           colClasses = c(patient_id = "character"))
}
randomization <- read_hf("randomization.csv")
outcomes <- read_hf("outcomes.csv")
trial <- merge(
  randomization[c("patient_id", "site", "rand_date", "arm")],
  outcomes[c("patient_id", "event_30d")],
  by = "patient_id"
)
stopifnot(nrow(trial) == nrow(randomization),
          !anyDuplicated(trial$patient_id))

proj <- file.path(tempdir(), "hfhome-report")
unlink(proj, recursive = TRUE)
dir.create(file.path(proj, "data"), recursive = TRUE)
writeLines(c("project:", "  type: default",
             "execute:", "  freeze: auto"),
           file.path(proj, "_quarto.yml"))
writeLines(c(
  '---',
  'title: "HF-HOME: 30-day outcomes by arm"',
  'format: gfm',
  '---',
  '',
  '```{r}',
  '#| include: false',
  'd <- read.csv("data/trial.csv")',
  'obs <- d[!is.na(d$event_30d), ]',
  'pct <- function(a) round(100 * mean(obs$event_30d[obs$arm == a]), 1)',
  '```',
  '',
  'Of `r nrow(d)` patients randomized, `r nrow(obs)` had the',
  'primary outcome ascertained. Readmission or death within 30',
  'days occurred in `r pct("Usual care")`% under usual care and',
  '`r pct("Home health")`% with home health.'
), file.path(proj, "report.qmd"))

render_report <- function(target, ...) {
  r_libs <- paste0("R_LIBS=",
                   paste(.libPaths(), collapse = .Platform$path.sep))
  status <- system2("quarto", c("render", target, ..., "--quiet"),
                    env = r_libs)
  stopifnot(status == 0)
  md <- readLines(file.path(proj, "report.md"))
  paste(md[nzchar(md)][-1], collapse = " ")
}

The report’s inline expressions use the R Markdown spelling, a backtick, r, and a space, which Quarto’s knitr engine also accepts.2 In your own documents use the {r} spelling shown earlier in the chapter.

2 Quarto rewrites every {r} inline expression in a document before any chunk runs, including one inside a string in a chunk. A chapter written in Quarto therefore cannot write that spelling into a file this way.

The interim extract holds the patients randomized by the end of March 2025. Render the whole project, as a build script or CI would:

interim <- trial[trial$rand_date <= "2025-03-31", ]
write.csv(interim, file.path(proj, "data", "trial.csv"),
          row.names = FALSE)
render_report(proj)
#> [1] "Of 1555 patients randomized, 1458 had the primary outcome ascertained. Readmission or death within 30 days occurred in 22.4% under usual care and 22.1% with home health."

The full extract arrives. Replace the data file and render the project again:

write.csv(trial, file.path(proj, "data", "trial.csv"),
          row.names = FALSE)
stale <- render_report(proj)
stale
#> [1] "Of 1555 patients randomized, 1458 had the primary outcome ascertained. Readmission or death within 30 days occurred in 22.4% under usual care and 22.1% with home health."

The paragraph has not changed. Every number in it is computed, and every number is wrong. The reason is that freeze: auto saw an unchanged report.qmd and served the stored results. Render the document itself, which always executes:

current <- render_report(file.path(proj, "report.qmd"))
current
#> [1] "Of 2432 patients randomized, 2269 had the primary outcome ascertained. Readmission or death within 30 days occurred in 23.7% under usual care and 21.1% with home health."
TipVerification

Compute the counts independently of the report and confirm that the current render states them and the stale one does not.

obs <- trial[!is.na(trial$event_30d), ]
expected <- sprintf("Of %d patients randomized, %d had the",
                    nrow(trial), nrow(obs))
stopifnot(grepl(expected, current, fixed = TRUE),
          !grepl(expected, stale, fixed = TRUE))
expected
#> [1] "Of 2432 patients randomized, 2269 had the"

In your own project, the same check is a test (Chapter 27): read the rendered output and assert that it contains the numbers the analysis computes.

ImportantLLM prompt

Use a model to convert typed numbers to inline code, and check the result by changing the data.

Context. Below are the data dictionary for trial.csv (patient_id, site, rand_date, arm, event_30d) and the results paragraph of a Quarto report whose setup chunk reads data/trial.csv into d. Every number in the paragraph was typed by hand.

Constraints. Replace every number that depends on the data with an inline {r} expression computed from d, defining any helper objects in the setup chunk. Use base R. Do not change the wording, and do not write any data-dependent number as a literal, including denominators inside an expression.

Criteria. List each number you replaced and the expression that now computes it. The document must render, and every number in the paragraph must change when it is rendered against a different extract.

Failure mode. The model computes a value itself and writes it back as a literal. Or it writes sum(d$event_30d) / 2432, an inline expression with a typed denominator. That expression renders the right number today and a wrong one on the next extract. Check. Render against the interim and the full extracts, as above, and compare the two paragraphs number by number (regmatches(x, gregexpr("[0-9.]+", x)) lists them). A number that is the same in both is typed or must be justified. Then read each listed expression for constants. A dictionary and a paragraph hold no patient data, so they may go to any approved tool (Section 12.3).

Question. In the worked example, the stale render contained no typed numbers. Why did it still report the interim results, and why would no reviewer reading the output notice?

Answer. Inline code guarantees that a number is computed when the document executes. It says nothing about whether the document executed. freeze: auto skipped execution because the source was unchanged, so the computed numbers were from the previous run. The paragraph is internally consistent and plausible, which is what makes it dangerous (Habit 8). A line in the report that states which extract it used, as in Exercise 4, makes the staleness visible.

23.4.1 Exercises

  1. Add a sentence to the worked example’s report that states the extract it was computed from, using the latest randomization date in d, so that a stale render announces itself.
Computed from the extract of patients randomized through
`{{r}} max(d$rand_date)`.

The stale render in the worked example would then name a date in March 2025 beside numbers the reader believes are final. A reader can catch that. Stating provenance in the output is a cheap form of the assertion habit. It does not prevent the stale render. However, it turns a silent failure into a visible one.

23.5 Parameterized reports

A parameter lets one .qmd render against different inputs: one report per site in a multi-site trial, per sensitivity analysis, or per institution. Declare the parameter and its default in the front matter, and read it as params$site:

params:
  site: "All"

Render a variant from the shell (display-only):

quarto render report.qmd -P site:"Site C"

Or from R with the quarto package:

quarto::quarto_render("report.qmd",
                      execute_params = list(site = "Site C"),
                      output_file = "report-site-c.html")

A parameterized report renders the same document against different data; a website (Section 23.6) renders different documents into one whole. A multi-site trial may use both: one parameterized report per site, collected into a site with an overview page.

Question. Why give the report a site parameter rather than copying it into five files, one per site?

Answer. Five copies drift. A fix to the denominator made in one copy is missing from the other four, and nothing reports the difference. With a parameter there is one source, so a correction reaches every site’s report at the next render.

23.5.1 Exercises

  1. Give the worked example’s report a site parameter that defaults to "All" and, when set, restricts d to that site. Render it for Site C and check the patient count against the data.
site_report <- readLines(file.path(proj, "report.qmd"))
site_report <- append(site_report,
                      c("params:", '  site: "All"'), after = 3)
site_report <- sub(
  'd <- read.csv("data/trial.csv")',
  paste('d <- read.csv("data/trial.csv");',
        'if (params$site != "All") d <- d[d$site == params$site, ]'),
  site_report, fixed = TRUE
)
writeLines(site_report, file.path(proj, "report.qmd"))
site_c <- render_report(file.path(proj, "report.qmd"),
                        "-P", shQuote("site:Site C"))
site_c
#> [1] "Of 498 patients randomized, 462 had the primary outcome ascertained. Readmission or death within 30 days occurred in 23.9% under usual care and 18.5% with home health."
stopifnot(grepl(sprintf("Of %d patients", sum(trial$site == "Site C")),
                site_c, fixed = TRUE))

The default "All" keeps the unparameterized render unchanged, and the filter sits in the setup chunk, so every inline number below it is computed for the chosen site. The stopifnot() is the check: the count in the rendered sentence equals the count computed from the data.

23.6 Reference: front matter and websites

23.6.1 Front matter

The keys used in this chapter, with one example each:

Table 23.6: Front-matter keys. Each format has many more options; the Quarto reference for that format lists them.
Key Sets Example
title, author, date Title block date: today
format Output formats and their options html: {toc: true}, pdf: default
execute Defaults for every chunk echo: false, freeze: auto
bibliography, csl Citations and their style references.bib, a CSL URL
params Parameters and their defaults site: "All"

Authors take a list of names with optional affiliation and orcid fields. Format options nest under each format, so HTML and PDF can have different figure sizes from one source.

23.6.2 Websites

A directory of .qmd files governed by a _quarto.yml with project: type: website renders to a website: linked pages with shared navigation, theme, and search. This book is the same machinery with type: book. The minimum is a _quarto.yml naming the pages and an index.qmd landing page:

project:
  type: website
website:
  title: "HF-HOME analysis"
  navbar:
    left: [index.qmd, methods.qmd, results.qmd]

quarto render builds the site into _site/, quarto preview serves it with live reload, and quarto publish gh-pages (or netlify, quarto-pub, connect) publishes it. For a research team, a site is the natural form of an internal analysis portal. It carries every guarantee of this chapter. It is also rebuilt on every push by the CI workflow of Section 27.9, whereas a PDF that is emailed around goes stale.

23.7 Accessible documents

A document that renders without a warning can still be unusable to a reader on a screen reader or a magnifier. Quarto does not check this for you. It only gives you the markup. Used correctly, that markup lets assistive technology navigate the document the way a sighted reader scans it.

23.7.1 Heading levels and the document outline

A screen reader user commonly jumps between headings rather than reading linearly, the way a sighted reader skims a table of contents. That only works if the heading levels nest without skipping. That is, a ## section’s subsections are ###, never #### chosen because it looked like the right size. Quarto numbers # through ###### the same way regardless of level skipped. A rendered page can therefore look fine while its outline is unusable. The only way to catch a skipped level is to read the headings as a list. For example, use the browser’s accessibility tree or pandoc -t native on the rendered source. Use heading level for structure. Use .smallcaps, bold, or a callout for visual emphasis that is not a new section.

23.7.2 Caption every table, and keep its text with it

A {#tbl-...} caption (Table 23.3) lets you write @tbl-outcomes. A screen reader also announces the caption text together with the table. For some readers, that is the only description they get of what the columns contain. A pipe table or gt/gtsummary output with no caption reaches a screen-reader user as an unlabeled grid of numbers. Write the caption so it states what the table shows. This is the same discipline Section 20.5 asks of a figure’s fig-alt. A caption that merely repeats ‘Table 1’ states nothing a screen reader did not already announce.

23.7.3 Alt text for figures

Every figure needs a fig-alt string. What distinguishes a useful one from a decorative one is a figure-specific judgment about what a visualization does and does not need to say. Section 20.5 teaches that judgment with this book’s own figures as examples. The Quarto-specific part is only the chunk option itself. Set fig-alt on every chunk that produces output a reader cannot otherwise decode. That includes a table rendered as an image by some PDF pipelines (Section 23.8 touches a related PDF quirk).

23.7.4 Accessibility of HTML, PDF, and Word

Table 23.1 lists what each format cannot carry. The formats also differ in accessibility. HTML is the most accessible target. A modern screen reader reads its heading structure, table markup, and alt attributes directly, and the reader controls font size and contrast in the browser. PDF is the least accessible by default. Figures and non-tagged tables in a PDF can read as unlabeled images to assistive technology. Keyboard-only navigation by heading is unreliable even in a well-structured PDF, unless it was exported with tagging enabled. LaTeX-based PDF (the engine quarto render --to pdf uses by default) does not do that without extra configuration. Word sits between the two. fig-alt text and table captions both carry into the .docx’s accessibility metadata. A sighted reader with low vision also benefits from Word’s own zoom and high-contrast modes. However, heading navigation depends on the document using Word’s built-in heading styles rather than visual formatting. Quarto’s conversion uses those styles by default.

Suppose a document’s primary audience may include a screen-reader user, and the choice of format is yours to make. Then prefer HTML, and offer PDF as a secondary, print-oriented format rather than the only one. A report that must ship as PDF for a journal or a regulatory submission is not thereby exempt from headings, captions, and alt text. Those three practices are what a tagged, accessible PDF is built from. That holds even though Quarto’s default LaTeX pipeline does not produce the tagging automatically.

Question. A report renders to both HTML and PDF from one source, with every figure’s fig-alt set and every table captioned. Is the PDF now as accessible to a screen-reader user as the HTML?

Answer. Not necessarily. fig-alt and table captions are markup Quarto writes into both outputs. However, the default LaTeX PDF pipeline does not tag the PDF’s reading order, headings, or table structure the way HTML’s DOM (Document Object Model) does natively. A screen reader can therefore still read a LaTeX PDF’s content in the wrong order or miss its structure, even when every caption and alt text is present. The HTML output from the same source is more reliably accessible without further work.

23.7.5 Exercises

  1. Render a short document with one ## and one #### heading (no ### between them) to HTML, then inspect the heading outline (in a browser, the accessibility or document-outline panel; from the shell, pandoc -t native report.qmd | grep Header). What does the skipped level look like from each view, and why is the second check necessary even though the page looks fine?

Visually, a #### heading typically renders smaller than the ## before it, so a sighted reader sees two headings of decreasing size and nothing wrong. The outline view shows the skip directly: a level-2 heading followed immediately by a level-4 heading, with no level 3 in between. A sighted reader has no reason to notice a level is missing, because font size, not level, is what they see. Checking the outline (or the Pandoc AST) catches the defect. It is invisible on the page, but it breaks navigation for a screen-reader user who jumps by heading level.

23.8 Float placement in PDF

A figure you cite in the prose can appear two pages later. LaTeX treats figures and tables as floats and moves them to avoid awkward white space and bad page breaks. For a paper, let it; readers expect floating figures. For a report meant to be read top to bottom, force placement where the figure is declared.

The fix in knitr Rmd:

```{r demographics, fig.cap = "Demographics", fig.pos = "H"}
plot(...)
```

Or globally:

knitr::opts_chunk$set(fig.pos = "H")

In Quarto, fig-pos is a figure option rather than an execution option, so it goes under the PDF format (or in a single chunk as #| fig-pos: "H"):

format:
  pdf:
    fig-pos: "H"

H is from the float LaTeX package, meaning ‘place exactly here, do not float’. Add to the YAML:

header-includes:
  - \usepackage{float}

For tables, the equivalent is tbl-pos: 'H' in Quarto or kable_styling(latex_options = "HOLD_position") in knitr+kableExtra. Table 23.7 lists the placement codes.

Table 23.7: LaTeX float-placement codes. The default, htbp, lets LaTeX choose among the first four in that order.
Code Meaning
h Here, if possible
t Top of a page
b Bottom of a page
p On a separate page of floats
! Prefix: override LaTeX’s usual limits on float placement
H Exactly here, never float (requires the float package)

For HTML output, float placement is irrelevant; figures appear in source order.

Question. You write ‘Figure 3 shows demographics’ and the rendered PDF puts Figure 3 four pages later. Why, and what is the fix?

Answer. LaTeX defers floats when placing them at the source location would create awkward white space or break a paragraph, sometimes by pages. There are two fixes, and they are best combined. Use fig-pos: "H" (with \usepackage{float} in the header) to force exactly-here placement, for documents that must be read linearly. And refer to the figure by its cross-reference (see @fig-demographics) rather than by a typed ‘Figure 3’, so that the number and the link are correct wherever the figure lands.

23.8.1 Exercises

  1. In a Quarto PDF with three tables, make every table appear exactly where it is declared.

Set the option once for the format and load the package:

format:
  pdf:
    tbl-pos: "H"
header-includes:
  - \usepackage{float}

Verify in the PDF that each table follows the paragraph that precedes it in the source. A table that still floats was probably produced by a package that writes its own LaTeX float environment (for example kableExtra), which needs that package’s option (latex_options = "HOLD_position") instead.

23.9 Troubleshooting a render

A render fails in one of two ways. The loud failure stops it with an error and a message that names the chunk; the silent failure finishes, exits successfully, and leaves a defect in the output. Table 23.8 collects the common ones; the worked example after it shows how to read a real log.

Table 23.8: Common rendering failures. The first two block the render; the next two finish with a defect in the output.
Symptom (message excerpt) Cause Fix
Error: ! object 'x' not found, then Quitting from doc.qmd:14-18 [label] The object is created in a chunk that did not run (eval: false, or deleted) or runs later Read the Quitting from line for the failing chunk; make the defining chunk run, and run before it
could not find function A package is used but not loaded in the document Add the library() call to the document’s setup chunk; the render runs in a fresh session
Unable to resolve crossref @fig-x (a warning), and ?@fig-x in the output A missing or misspelled label, a label without its fig- or tbl- prefix, or a chunk that did not run Fix the label; grep the output for ?@ (Section G.3)
\@ref(fig:x) printed literally in the output A bookdown reference left unconverted Rewrite as @fig-x (Table G.1)
No TeX installation was detected PDF output needs LaTeX quarto install tinytex
LaTeX Error: File ... .sty not found A LaTeX package missing from a minimal TeX installation Install it (tinytex::tlmgr_install("float"), with the package’s name), or let TinyTeX install it on the next render
ModuleNotFoundError in a Python chunk Python packages not declared reticulate::py_require() (Section G.4)
unknown writer or an unknown format A misspelled format: name, or a Quarto older than the format Check the name; run quarto check and update Quarto
Figures pages away from their citation LaTeX float placement fig-pos (Section 23.8)
Every render slow Expensive chunks re-run every time freeze or cache (Section 23.3)
Old numbers after new data freeze or cache served stored results Render the document itself (Section 23.3)

23.9.1 Worked example: a render that fails, then succeeds wrongly

The example renders a one-figure HF-HOME report, from the trial table of Section 23.4, in a temporary directory, with two defects planted from real conversions: a setup chunk left at eval: false from drafting, and a figure label that kept its R Markdown name. It runs the real quarto command, so the log below is what you would see.3

3 As in the earlier worked example, the env argument passes this session’s library paths to the R process that Quarto starts. In a terminal you would type quarto render report.qmd alone.

dbg <- file.path(tempdir(), "debug")
unlink(dbg, recursive = TRUE)
dir.create(dbg)
write.csv(trial[c("patient_id", "arm", "event_30d")],
          file.path(dbg, "trial.csv"), row.names = FALSE)

doc <- c(
  "---", "title: 'HF-HOME: primary outcome'", "format: gfm", "---",
  "",
  "```{r}",
  "#| label: setup",
  "#| eval: false",
  "d <- read.csv('trial.csv')",
  "obs <- d[!is.na(d$event_30d), ]",
  "risk <- 100 * tapply(obs$event_30d, obs$arm, mean)",
  "```",
  "",
  "@fig-risk shows the observed risk in each arm.",
  "",
  "```{r}",
  "#| label: risk",
  "#| fig-cap: 'Observed 30-day risk by arm'",
  "barplot(risk, ylab = 'Risk (%)')",
  "```"
)

render_doc <- function(doc) {
  writeLines(doc, file.path(dbg, "report.qmd"))
  r_libs <- paste0("R_LIBS=",
                   paste(.libPaths(), collapse = .Platform$path.sep))
  log <- suppressWarnings(system2(
    "quarto", c("render", file.path(dbg, "report.qmd")),
    stdout = TRUE, stderr = TRUE, env = r_libs
  ))
  status <- if (is.null(attr(log, "status"))) 0 else attr(log, "status")
  log <- gsub("\033\\[[0-9;]*m", "", log)
  log <- sub("^WARNING \\(.*\\) ", "WARNING ", log)
  list(status = status,
       log = grep("Error|^!|Quitting|WARN", log, value = TRUE))
}

Render it:

first <- render_doc(doc)
first
#> $status
#> [1] 1
#> 
#> $log
#> [1] "Error:"                                      
#> [2] "! object 'risk' not found"                   
#> [3] "Quitting from report.qmd:16-20 [risk]"       
#> [4] "WARN: Error encountered when rendering files"

The render failed (a non-zero status), and the log says why in two lines. Read it from the bottom up. Quitting from names the file, the source lines, and the label of the chunk that failed, here risk. The error above it names what that chunk could not find. The object is defined in setup, which never ran. The fix is to let it run:

doc <- doc[doc != "#| eval: false"]
second <- render_doc(doc)
second
#> $status
#> [1] 0
#> 
#> $log
#> [1] "WARNING Unable to resolve crossref @fig-risk"

The status is now zero, and a build script or continuous integration would report success. The log still carries a warning. risk is not a figure label, because it lacks the fig- prefix, so the reference in the prose resolved to nothing. Look at the sentence Quarto wrote:

grep("shows the observed", readLines(file.path(dbg, "report.md")),
     value = TRUE)
#> [1] "**?@fig-risk** shows the observed risk in each arm."

This is the silent failure, and it is the more expensive of the two. The first defect stopped the render. This one produced a finished document with the defect inside it. Rename the label:

doc <- sub("#| label: risk", "#| label: fig-risk", doc, fixed = TRUE)
third <- render_doc(doc)
third
#> $status
#> [1] 0
#> 
#> $log
#> character(0)
TipVerification

A render is done when the status is zero, the log has no warning, and the output contains no unresolved reference.

out <- readLines(file.path(dbg, "report.md"))
stopifnot(
  third$status == 0,
  length(grep("WARN", third$log)) == 0,
  !any(grepl("?@", out, fixed = TRUE))
)
grep("shows the observed", out, value = TRUE)
#> [1] "<a href=\"#fig-risk\" class=\"quarto-xref\">Figure 1</a> shows the observed"

The first two conditions are the log; the third is the output, and it is the one that would have caught a converted paper sent to co-authors with ?@fig-flow in its methods section (Section G.1).

When a failure is not in Table 23.8, reduce it. Copy the document, delete chunks and prose until the error disappears, and restore the last thing you deleted. What remains is a minimal example, usually under twenty lines. It either shows you the cause or is ready to post to the Quarto discussion forum. quarto check reports the versions of Quarto, R, knitr, and LaTeX that belong in any such post.

ImportantLLM prompt

A model is good at reading a render log, provided you give it the right excerpt and forbid the fixes that hide the error.

Context. A Quarto document fails to render. Below are the last 30 lines of the log, the chunk named in the Quitting from line with the chunks before it that define its inputs, and the output of quarto check.

Constraints. Do not suggest error: true, eval: false, warning: false, try(), or reinstalling Quarto or R unless the log shows a version problem. Change as few lines as possible.

Criteria. Name the line that fails and the cause, and say what the log shows that supports the diagnosis. After your fix, the render exits with status zero, the log has no WARN line, and the output contains no ?@.

Failure mode. The suggested fix silences the symptom, by skipping the chunk or tolerating the error, and turns a loud failure into a silent one. Check. Apply the fix, re-render, and run this section’s Verification on the output. A log and chunk code are structure; if the error message prints data values, cut them before sending (Section 12.3).

Question. In the debugging example, the second render exited with status zero. Why is a zero status not enough to call a render correct, and what two further checks does the Verification add?

Answer. A zero status means the document compiled. Quarto treats an unresolved cross-reference as a warning, so a document can reach a reader with ?@fig-risk in its prose and a successful build behind it. The Verification also requires a log with no warning and an output with no ?@.

23.9.2 Exercises

  1. A render log ends with these lines. Which chunk failed, what is the likely cause, and where do you look first?
4/9 [fit-model]
Error:
! object 'analysis_set' not found
Quitting from paper.qmd:61-70 [fit-model]

The chunk labeled fit-model, at lines 61 to 70 of paper.qmd, uses analysis_set before anything has created it. Look first at the chunk that should define analysis_set: it is set to eval: false, it comes after fit-model, or it was deleted. If the document reads analysis_set from a file or a pipeline target, check that the reading chunk ran.

23.10 Rules of thumb

  1. Habit 10: every number in the prose is computed. Sample sizes, estimates, intervals, and p-values are inline expressions, and figures and tables are cross-referenced by label.
  2. Habit 8: a stale number is a plausible number, and a clean render is not a correct render. freeze and cache watch code, not data; after a data change, render the document itself and check the counts it reports. A zero exit status means the document compiled; grep the output for ?@ as well.
  3. Habit 2: the rendered document is a build product. Never edit the .html, .pdf, or .docx; change the source and render again.

23.11 Cumulative practice

  1. Cumulative (uses Chapter 18). Rebuild the worked example’s trial table with dplyr::left_join(), declaring the relationship and refusing unmatched keys, and assert that it has one row per randomized patient. Explain why the report’s first number depends on this join being right.
  2. On your own work (no key). Replace every typed number in a draft of yours with inline code. Render it, render it again against deliberately different data, and confirm that every number changed.
library(dplyr)

trial_joined <- randomization |>
  select(patient_id, site, rand_date, arm) |>
  left_join(select(outcomes, patient_id, event_30d),
            by = "patient_id",
            relationship = "one-to-one", unmatched = "error")
stopifnot(nrow(trial_joined) == nrow(randomization),
          identical(sort(trial_joined$patient_id),
                    sort(trial$patient_id)))
nrow(trial_joined)
#> [1] 2432

The report’s first sentence counts the rows of trial.csv. A join that dropped patients would shrink the denominator, and one that multiplied them would inflate it. In either case the sentence would go on rendering a plausible number. Declaring the relationship and the unmatched behavior makes either failure stop the build.

23.12 Cheat sheet

Table 23.9: Quarto at a glance.
Task Code Guards against
Render a document quarto render report.qmd A stale output (always executes)
Render a project quarto render Inconsistent pages (respects freeze)
Put a number in a sentence `{r} nrow(d)` Numbers typed from the console
Refer to a figure @fig-label ‘Figure 3’ pointing at the wrong figure
Cite a work [@key] Hand-typed, unformattable references
Reuse a whole document’s results execute: freeze: auto Re-running a slow analysis on every project render
Reuse one chunk’s result cache: true Re-running one slow chunk
Re-run a cached chunk when data change cache.extra: !expr tools::md5sum("data/x.csv") A cache that does not see the data
Render one variant quarto render report.qmd -P site:"Site C" Five drifting copies of one report
Force a figure in place (PDF) fig-pos: "H" with \usepackage{float} A figure pages away from its citation
Force a table in place (PDF) tbl-pos: "H" A table pages away from its citation
Find unresolved references grep -rn '?@' _book/ A clean render with broken references
Report versions for a bug report quarto check A bug report no one can reproduce

23.13 Further reading

  • The Quarto documentation at quarto.org, the canonical reference, in particular the guides to computations and to managing execution (freeze and cache).
  • (Wickham et al., 2023) Chapters 28 and 29, Quarto and its output formats.
  • (Knuth, 1984), the paper that named the idea this chapter implements.

23.14 Prerequisites answers

  1. Literate programming (coined by Knuth) interleaves code with the prose that explains it, so the same source file is the authoritative record of both the computation and its interpretation. A Quarto .qmd file embodies this by letting you write narrative Markdown and executable R (or Python, Julia) code chunks in one document. The render process produces a human-readable artifact (HTML, PDF, Word) with code, output, and prose interleaved.
  2. quarto render file.qmd produces the default output format declared in the document’s YAML format: key (HTML if no format: is present). To force a format, use quarto render file.qmd --to html (or --to pdf, --to docx).
  3. In a Quarto project, execute: freeze: auto stores each document’s executed results in _freeze/ when the project is rendered. Later project renders reuse them for every document whose source is unchanged. They re-execute a document in full when any part of it changes. This avoids re-running expensive code on every render and makes CI deployments fast. It does not apply to a single-file render, which always executes, and the default is freeze: false. Commit _freeze/ to Git so collaborators benefit from it.
  4. LaTeX treats figures and tables as floats and rearranges them by default to avoid bad page breaks. fig-pos: 'H' (requires the float package) and tbl-pos: 'H' in Quarto YAML tell LaTeX ‘place this exactly here, no reflow’. The default placement, htbp, means ‘try here, then top, then bottom, then a float page’ in order.