Options

Chunk options and package options

2020-06-30

The knitr package provides a lot of chunk options for customizing nearly all components of code chunks, such as the source code, text output, plots, and the language of the chunk. It also offers some options at the package level to customize the knitting process. This page documents all chunk options and package options available in knitr. The default values of these options are in parentheses in the list items.

Chunk Options

Chunk options are written in chunk headers. The syntax for chunk headers depends on the document format, e.g., for .Rnw documents (R + LaTeX), chunk headers are written with << >>=, and for .Rmd documents, chunk headers are written with ```{r}. The examples below are primarily for .Rmd documents (R Markdown), but in most cases, the chunk options can be used with any document format.

Chunk options are written in the form tag=value like this:

```{r, my-chunk, echo=FALSE, fig.height=4, dev='jpeg'}
```

A special chunk option is the chunk label (e.g., my-chunk in the above example). Only the chunk label does not need a tag (i.e., you only provide the value). If you prefer the form tag=value, you could also use the chunk option label explicitly, e.g.,

```{r, label='my-chunk'}
```

The chunk label for each chunk is assumed to be unique within the document. This is especially important for cache and plot filenames, because these filenames are based on chunk labels. Chunks without labels will be assigned labels like unnamed-chunk-i, where i is an incremental number.

You may use knitr::opts_chunk$set() to change the default values of chunk options in a document. For example, you may put this in the first code chunk of your document:

```{r, setup, include=FALSE}
knitr::opts_chunk$set(
  comment = '', fig.width = 6, fig.height = 6
)
```

Below are a few more tips about chunk options:

  1. The chunk header must be written on one line. You must not break the line.

  2. Try to avoid spaces, periods (.), and underscores (_) in chunk labels and paths. If you need separators, you are recommended to use hyphens (-) instead. For example, setup-options is a good label, whereas setup.options and chunk 1 are bad; fig.path = 'figures/mcmc-' is a good path for figure output, and fig.path = 'markov chain/monte carlo' is bad.

  3. All option values must be valid R expressions. You may think of them as values to be passed to function arguments.

    • For example, options that take character values must be quoted, e.g., results = 'asis' and out.width = '\\textwidth' (remember that a literal backslash needs double backslashes).
    • In theory, the chunk label should be quoted, too. However, for the sake of convenience, it will be automatically quoted if you did not (e.g., ```{r, 2a} will parsed as ```{r, '2a'}).
    • You can write arbitrarily complicated expressions as long as they are valid R code.

Alternatively, you can write chunk options in the body of a code chunk after #|, e.g.,

```{r}
#| my-chunk, echo = FALSE, fig.width = 10,
#| fig.cap = "This is a long long
#|   long long caption."

plot(cars)
```

For this syntax, chunk options must be written on continuous lines (i.e., all lines must start with the special comment prefix such as ⁠#|⁠) at the beginning of the chunk body. The blank line between the options and code is optional. This syntax allows for hard-wrapping the options. You can break the options onto as many lines as you wish. If the same option is provided in both the chunk body and in the chunk header (inside ```{}), the former will override the latter. You can also use the YAML syntax to write options inside a chunk in the form tag: value. Normally you have to provide only one option per line, e.g.,

```{r}
#| echo: false
#| fig.width: 10
```

If you choose to use the YAML syntax, the option values must be valid YAML values instead of raw R expressions.

Below is a list of chunk options in knitr documented in the format “option: (default value; type of value)”.

Code evaluation

Text output

Code decoration

Cache

Plots

There are two hidden options that are not designed to be set by users: fig.cur (the current figure number or index when there are multiple figures), and fig.num (the total number of figures in a chunk). The purpose of these two options is to help knitr deal with the filenames of multiple figures as well as animations. In some cases, we can make use of them to write animations into the output using plot files that are saved manually (see the graphics manual for examples).

Animation

Code chunk

Child documents

Language engines

Option templates

Extracting source code

Other chunk options

Package Options

The package options can be changed using the object knitr::opts_knit (not to be confused with knitr::opts_chunk). For example:

knitr::opts_knit$set(progress = TRUE, verbose = TRUE)

See ?knitr::opts_knit for the alternative approach to setting package options using the R base function options().

Available package options are as follows:

Global R Options

Global R options are set with options() in base R. Below is a list of options that affect the behavior of knitr: