Control code

The knitr package gives you options for controlling how your source code looks and works.

We just learned about how the knitr package is responsible for both executing code and knitting the output back into the document. The knitr package has some special code chunk options to control how your code both works and looks.

Using chunk options

All knitr chunk options are placed between the curly braces {} on the first line of each code chunk. This line is called the chunk header, and it must be a single line without line breaks.

The option name goes on the left, with the value on the right. You may include spaces around the equal sign if you wish.

```{r echo=FALSE}
...code goes here...
```

Multiple options can be separated by commas. You may include or exclude extra spaces around the comma, too.

```{r echo=FALSE, error=TRUE}
...code goes here...
```

Careful! The r part is the code engine. While other engines are possible, when you edit the chunk header, be sure not to touch the code engine.

In total, there are 53 options, so we’ll highlight those with the highest payoff. Chunk options specific to controlling figures are covered in the next section.

Control what appears in the output

By default, all source code, output, warnings, and messages are printed faithfully by knitr in the output file. The most important knitr chunk options help you gain control over what appears in your output when you knit. By combining options, you can have the output display just the code, just the results, both, or neither. For example:

echo = FALSE hides code (but not results) from appearing in the output file. This is a useful way to embed figures.
results = FALSE hides text results from appearing in the output file (the corollary option for figures is fig.show = 'hide')
message = FALSE hides messages generated by the chunk from appearing in the output file.
warning = FALSE hides warnings generated by the chunk from appearing in the output file.
include = FALSE hides code, results, warnings, and messages from appearing in the output file. The code in the chunk is still executed invisibly, and the results can be used by other chunks.

Each of these options takes TRUE or FALSE (no quotes) as its input value, with TRUE as the default value.

Control how code is executed

Two additional code chunk options help you control how your code is executed when you knit. Note that these do not affect how your code chunk run interactively in RStudio.

error = TRUE allows the knitting process to keep going if the chunk produces an error.
eval = FALSE skips executing code in a chunk, often used for chunks where the code calls functions like install.packages() or View(), which should not be run when you knit.

If you find yourself with an .Rmd where you want to set error=TRUE or eval=FALSE for all remaining code chunks, you may want to insert code chunk strategically using knit_exit(). After that chunk, knitr will exit the knitting process, and all subsequent chunks will be ignored.

```{r include=FALSE}
knitr::knit_exit()
```

The rest is scrap work.

Control your whole document

It can get repetitive to reset chunk options individually, when sometimes you’d like to override the default values for a whole .Rmd document. To set global options that apply to every chunk in an .Rmd, call knitr::opts_chunk$set in a code chunk.

The setup code chunk affects all code chunks in the same .Rmd document. It is called a global chunk option for that reason.

The chunk option for the setup chunk itself is typically include=FALSE so that no one sees it but you.

```{r setup, include = FALSE}
knitr::opts_chunk$set(
  comment = "#>",
  collapse = TRUE,
  echo = FALSE,
  warning = FALSE,
  message = FALSE
)
```

Knitr will treat each option that you pass to knitr::opts_chunk$set as a global default that can be overwritten in individual chunk headers. You can (and should) use individual chunk options too, but setting up some nice ones that apply to all code chunks can save you time and can lessen your cognitive load as you develop your code.

A few notes on what the above chunk options do:

comment = "#>" sets the character on the far left of all printed output such that a reader could copy/paste a block of code into their console and run it (that is, the pasted code with printed output will not produce errors).
collapse = TRUE fuses your chunk’s code and output together into a single block (by default, they are written to separate blocks).

Below is a side-by-side changing this chunk option for an individual chunk.

Naming and finding code chunks

Caching

If document rendering becomes time consuming due to long computations you can use knitr caching to improve performance. Knitr chunk and package options describes how caching works and the Cache examples provide additional details.

What’s next

See the R Markdown Reference Guide for a complete list of knitr chunk options. Style your figures w/ knitr chunk options (out.width, fig.show, fig.align, fig.asp, fig.cap, fig.alt)