Skip to main content

Running R with knitr

Overview

Quarto uses knitr to execute R code. A code block whose language is r in braces, as in ```{r}, is an executable cell, and knitr owns the r language by default, so a document with R cells needs no engine: key. Quarto runs each cell when it renders the document and puts the output in the page.

Here is a simple example:

airquality.qmd
---
title: ggplot2 demo
author: Norah Jones
date: 5/22/2021
format:
  html:
    code-fold: true
---

## Air quality

@fig-airquality explores the impact of temperature on ozone level.

```{r}
#| label: fig-airquality
#| fig-cap: "Temperature and ozone level."
#| warning: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) +
  geom_point() +
  geom_smooth(method = "loess")
```

The comments at the top of the cell are cell options. Here they give the figure a label and a caption, which makes it cross-referenceable.

A cell can produce a wide variety of output, including plots, tables from data frames, and plain text such as the printed result of a statistical summary. The execution options control what appears, and a value can also be computed inside a sentence with an inline expression.

Rendering

Render the document from a shell:

q2 render airquality.qmd
q2 render airquality.qmd --to docx

q2 preview airquality.qmd renders the document and keeps the page up to date as you edit.

Installation

To run R cells you need R and the rmarkdown package:

install.packages("rmarkdown")

Installing rmarkdown also installs knitr, so it provides everything needed to render a document that contains R code. Quarto requires knitr 1.44 or later.

Quarto finds R by looking for Rscript on the system PATH. To use a different R, set the QUARTO_R environment variable to the directory that holds the Rscript binary, or to the binary itself.

How Quarto picks knitr

Quarto sends any cell whose language is r to knitr. You don’t need an engine: or knitr: key to select it. A document with both {r} and {python} cells runs the Python cells through reticulate, because knitr takes Python only when it is already running for the R cells.

NoteMigrating from Quarto 1

Quarto 1 chose one engine for the whole document, and it chose knitr whenever the document had an {r} cell. In Quarto 2 each language goes to the engine that owns it, so {r} cells run in knitr whatever else the document contains. The engines page describes how to change which engine owns a language, and Running R cells on Ark shows how to run {r} cells on a Jupyter kernel instead.

Cell options

Cell options are #| comment lines at the top of a cell, written in YAML:

```{r}
#| echo: false
#| fig-cap: "Air Quality"

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) +
  geom_point() +
  geom_smooth(method = "loess", se = FALSE)
```

Putting each option on its own line keeps long values such as fig-cap, fig-subcap and fig-alt readable, and lets editors change an option without parsing the cell header.

NoteMigrating from Quarto 1

Quarto 1 accepted options on the first line of the cell too, as in

```{r, echo = FALSE}. Quarto 2 does not. A header like that is rejected with error Q-2-36, and the fix is to move each option to a #| line.

Option values use YAML syntax, not R syntax. To compute a value with R, start it with !expr:

#| echo: !expr Sys.getenv("SHOW_CODE") == "yes"

!expr is a YAML tag, and it must be followed by a single YAML flow scalar: see the YAML specification for how double-quoted, single-quoted and unquoted strings work.

NoteMigrating from Quarto 1

In Quarto 1, !expr also worked in caption options. In Quarto 2 the caption options fig-cap and tbl-cap do not evaluate it: a caption written #| fig-cap: !expr paste("Air", "Quality") appears as that text. To compute a caption, use the cross-reference div syntax with an inline expression.

Cell labels

Set a label for a cell with the label option:

```{r}
#| label: convert
airquality$TempC <- (5 / 9) * (airquality$Temp - 32)
```

Unless you want a cross-reference, avoid the reserved cross-reference prefixes (fig-, tbl- and the others) for labels.

Execution options

The execute front matter key sets a default for a whole document, and a #| line overrides it for one cell. For example, to hide the code in every cell and show it in one:

---
title: Knitr Document
execute:
  echo: false
---

```{r}
#| echo: true
summary(airquality)
```

The options that decide what appears are eval, echo, output, warning, error and include. Set output: asis when R writes markdown that Quarto should not wrap:

```{r}
#| echo: false
#| output: asis

cat("# Heading 1\n")
cat("## Heading 2\n")
```

Data frames

The df-print option sets how data frames print. Set it in the format:

---
title: "Document"
format:
  html:
    df-print: paged
---
Option Description
default Use the default S3 method for the data frame.
kable A Markdown table, made with knitr::kable().
tibble A plain text table, made with the tibble package.
paged An HTML table that pages long rows and columns, made with rmarkdown::paged_table().

paged is available in HTML formats. In any other format Quarto prints the data frame with kable.

Knitr options

To set knitr’s own chunk options once, for a whole document, put them under the knitr key:

---
title: "My Document"
format: html
knitr:
  opts_chunk:
    collapse: true
    comment: "#>"
    R.options:
      digits: 3
---

The knitr key also works in a project’s _quarto.yml, where it sets the defaults for every document in the project.

The R.options chunk option is a convenient way to set R options that apply only while the chunk runs. knitr sets them with options() before the chunk and restores them afterward.

Inline expressions

Knitr cells can compute a value inside a sentence, with either the brace spelling `{r} x` or knitr’s own `r x`. The two differ in how they insert the value, and Inline expressions describes both.

Caching

The knitr cache works per cell rather than per document, so you are responsible for tracking dependencies between cells (for example, with dependson).

Enable the cache for a document or a project with the execute option:

---
title: "My Document"
format: html
execute:
  cache: true
---

Or enable it for a single cell, and leave the document option unset:

```{r}
#| cache: true

summary(cars)
```

The other cell options that affect knitr’s cache, such as cache.path, dependson and cache.rebuild, work as they do in knitr. Yihui Xie’s article on cache invalidation explains how knitr decides that a cache is out of date.

NoteMigrating from Quarto 1

The command line options --cache and --cache-refresh are accepted by q2 render but do not change caching in Quarto 2. To force a refresh, delete the cell’s cache directory, or set cache.rebuild on the cell.

If you are caching to shorten a slow render, execute: enabled: false skips execution while you work on prose, and freeze keeps results from documents you have not changed.

Chunks that keep knitr’s markdown

When Quarto runs a document it can keep what the code produced as an execution record, so that q2 preview and hub can redisplay the page without rerunning R. For most cells, the record stores each output knitr produced separately: source code, printed text, messages and plots.

For some cells, there are no structured outputs for Quarto to save. In that case it stores knitr’s rendered markdown in the execution record as a single output with the MIME type text/x-quarto-markdown. The rendered page comes out identical, but tools that read the record directly, such as Positron, find one block of Quarto markdown instead of the cell’s individual outputs, so they won’t display those outputs or populate them from their own cache.

These cells keep knitr’s markdown:

  • A cell that includes another document with child=. Quarto reports Q-18-14.
  • A cell in another language run by knitr. This covers bash, sql, Python through reticulate, and engines you define yourself.
  • Every cell from the point where the document replaces a knitr hook. A call to knitr::knit_hooks$set() for source, output, message, warning, error or plot changes what knitr writes for a cell, and Quarto cannot know what the new hook does. The cell that replaces the hook and every cell after it keep knitr’s markdown, and Quarto reports Q-18-13. Cell options such as class.output, attr.source and collapse can replace a custom hook for most purposes, and they don’t cause this fallback.
  • Every cell, when the output format isn’t yet supported by execution records. Supported formats are HTML, Reveal.js, EPUB, Typst, Word (docx), PowerPoint (pptx) and GitHub Flavored Markdown (gfm). Other formats, such as PDF, keep knitr’s markdown for every cell.
  • A cell that asks for cache: 1 or cache: 2. Its output appears on the rendered page but is not stored in the record. A cell that asks for cache: true is recorded.