Dyr og Data

Dynamic documents — Quarto

Gavin Simpson
gavin@anivet.au.dk

Aarhus University

Mona Larsen
mona@anivet.au.dk

Aarhus University

Wednesday, 19 August 2026

Quarto

Quarto provides an authoring systemfor data science, combining your code, its results, and your narrative text

Unlike previous tools, Quarto is a separate command line tool run outside of R

It needs to be installed like R, rather than as an R package

No documentation via ?

Quarto

Several technologies are involved

When your document contains R code:

  1. Quarto runs your document through knitr, which executes the R code and renders the output as markdown (.md) plus generated files (e.g. images)
  2. Quarto then runs this markdown file through pandoc to generate the required output document(s)

Source: Wickham, Çetinkaya-Rundel, & Grolemund (2023) R for Data Science

R code chunks

Include a code chunk by surrounding code in ```

The code language is given in {} on the opening line, e.g. ```{r}

The chunk is ended by ``` on a line of its own

Arguments to the chunk include the chunk label, plus key value pairs, are given in the chunk, after ```{r}, and are prefixed with #|:

Some amazing prose that shows I'm a gifted writer should go here.
And some more. Interesting aside.

```{r}
#| label: chunk-name
#| key: value
#| key: value
# code here <--- this is a normal R comment
foo <- bar()
```

Woah! Look at that; some R code!

Chunk label

```{r}
#| label: chunk-name
#| key: value
#| key: value
# code here <--- this is a normal R comment
foo <- bar()
```

The chunk label is optional but if used it must be unique

You can also use the chunk label to navigate your document in RStudio

Chunk options

Tailor how knitr outputs the results of executing the code in each chunk

Many possible options controlling output, figures, etc.

See this Quarto help page for a list of allowed options

Chunk options

Important options are:

  • eval: false prevents the code being evaluated by R. There is no output generated but the code in the chunk is still echoed into the document
  • echo: false prevents the code in the chunk being output to the document. For a report, thesis, or manuscript you typically don’t want the code displayed
  • include: false this would allow code to be evaluated (with eval: true) but neither the code nor the output are shown in the document
  • message: false & warning: false prevent warnings or messages from being output into the document
  • results: hide hides printed (text) output, while fig.show: hide hides any plots created by the chunk
  • error: false causes the document to continue rendering even if the code results in an error. Not often useful but is helpful when debugging the code and the document, or when teaching and you deliberately want to raise an error

Tables

Tables are difficult to typeset — instead, create them using R data frames and then output the to the document using knitr::kable()

knitr::kable(head(mtcars), caption = "A knitr kable")
A knitr kable
mpg cyl disp hp drat wt qsec vs am gear carb
Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4
Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4
Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1
Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1
Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2
Valiant 18.1 6 225 105 2.76 3.460 20.22 1 0 3 1

Images

Images can be inserted into the document using knitr::include_graphics()

This allows you to apply the same chunk options to images as you would to plots that are created by R code.

knitr::include_graphics("assets/standards.png")

Caching

The entire .qmd document is rendered in a single R session

Each chunk is re-run each time you render the document

This may be inefficient if you have many chunks or some long-running ones

knitr has a caching system which can store the results of a chunk, which we can make use of

Caching

We turn on caching using the execute top-level element in the YAML header

execute:
  cache: true

The cached results are output to the document instead of rerunning a cached chunk

If the chunk is changed in some way the cache is invalidated and the chunk is rerun during the next render

Caching

You can also turn on caching at the chunk level

Use cache = true to cache specific individual chunks

```{r}
#| label: long-running-model
#| cache: true
# some long running code
model <- glm(y ~ x + z, data = df, family = poisson())
```

Use dependson = "chunk-label" to manually indicate which chunks depend on one another

```{r}
#| label: summarise-long-running-model
#| cache: true
#| dependson: long-running-model
# some long running code
summary(model)
```

Caching

Normally code chunks are not dependent on external files

For example, if a dataset is loaded from my_data.xlsx file, the code won’t be run if my_data.xlsx file is update

To add a dependency on an external file use cache.extra

```{r}
#| label: load-data
#| cache: true
#| cache.extra: !expr file.mtime("my_data.xlsx")
library("readxl")
data <- read_xlsx("my_data.xlsx", sheet = 1)
```

Global options

Rather than set chunk options on each chunk manually, you can override the default globally

Add these to the YAML header, under the knitr: top-level element

knitr:
  opts_chunk: 
    echo: true
    message: false
    fig.align: center
    fig.height: 6
    fig.width: 10.6666
    comment: "#>"

See the knitr 📦 website for a list of all chunk options: yihui.org/knitr/options/

Inline code

Often you want code to run and return output right in the middle of a sentence of the narrative text

Do this using `{r} x` instead of plain backticks ` `

For example, if this is our narrative text in the .qmd

We have data about `{r} nrow(diamonds)` diamonds. Only
`{{r}} nrow(diamonds) - nrow(smaller)` are larger than 2.5 carats.

we’d get this output:

We have data about 53940 diamonds. Only 126 are larger than 2.5 carats.

Rendering documents

You have three ways to render a Quarto document

  1. from within RStudio (or other editor)
  2. from the terminal / command line
  3. from the R console using the quarto 📦

Rendering documents

Use the Render button

Rendering documents

Use the quarto CLI tool

quarto render document.qmd # all formats
quarto render document.qmd --to pdf
quarto render document.qmd --to docx

Rendering documents

Use the quarto 📦 within R

library("quarto")
quarto_render("document.qmd") # all formats
quarto_render("document.qmd", output_format = "pdf")

Going further

Quarto is a new-ish tool that is under rapid development

There isn’t as much help out there for Quarto compared to RMarkdown