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 docxq2 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.
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.
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.
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.
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 reportsQ-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()forsource,output,message,warning,errororplotchanges 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 reportsQ-18-13. Cell options such asclass.output,attr.sourceandcollapsecan 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: 1orcache: 2. Its output appears on the rendered page but is not stored in the record. A cell that asks forcache: trueis recorded.