knitr logo

knitr: elegant, flexible, and fast dynamic report generation with R

Options

Chunk options and package options

2017-02-03


The knitr package shares most options with Sweave, but some were dropped/changed and some new options were added. The default values are in the parentheses below. Note that the chunk label for each chunk is assumed to be unique, i.e., no two chunks share the same label. This is especially important for cache and plot filenames. Chunks without labels will be assigned labels like unnamed-chunk-i where i is the chunk number.

Chunk Options

Take Rnw files as an example: usually we write chunk options in the form tag=value like this:

<<mychunk, cache=TRUE, eval=FALSE, dpi=100>>=
@

And opts_chunk$set() can change the default global options in a document (e.g. put this in a code chunk: opts_chunk$set(comment=NA, fig.width=6, fig.height=6)), and \SweaveOpts{} will no longer be supported (it is good if you do not know what this means). A few special notes on the options:

  1. Chunk options must be written in one line; no line breaks are allowed inside chunk options;
  2. Avoid spaces and periods . in chunk labels and directory names; if your output is a TeX document, these characters can cause troubles (in general it is recommended to use alphabetic characters with words separated by - or _ and avoid other characters), e.g. setup-options is a good label, whereas setup.options and chunk 1 are bad; fig.path='figures/mcmc-' is a good prefix for figure output if this project is about MCMC, and fig.path='markov chain/monte carlo' is bad; non-alphanumeric characters except - and _ in figure filenames will be replaced with _ automatically;
  3. All option values must be valid R expressions just like how we write function arguments;
    • for example, options that take character values must be quoted as you do in R (e.g. should write fig.path="abc" instead of fig.path=abc, and out.width='\\textwidth' instead of out.width=\textwidth)
    • in theory, the chunk label should be quoted as well but the sake of convenience it will be automatically quoted if you did not quote it (e.g. <<2a>>= will become <<'2a'>>=)
    • for logical options, TRUE and FALSE are OK, and true/false will not work as you might have expected because true is not TRUE
    • you can write arbitrarily complicated expressions as you want as long as they are legitimate R code
    • Sweave users please read the transition page carefully because the syntax is different

Below is a list of chunk options in knitr. Note the options background and size only apply to .Rnw documents.

Code Evaluation

Text Results

Code Decoration

There is a hidden option indent which stores the possible leading white spaces of the chunk, e.g. for the chunk below, indent is a character string of two spaces:

  ```{r}
  rnorm(10)
  ```

Currently this option is only used to indent markdown output, because leading white spaces have special meanings in markdown.

Cache

Plots

Note any number of plots can be recorded in a single code chunk, and this package does not need to know how many plots are in a chunk in advance – it can figure out automatically, and name these images as fig.path-label-i where i is incremental from 1; if a code chunk does not actually produce any plots, knitr will not record anything either (the graphics device is open only when plots are really produced); in other words, it does not matter if fig.keep='high' but no plots were produced.

Low-level plotting commands include lines() and points(), etc. To better understand fig.keep, consider the following chunk:

<<test-plot>>=
plot(1)         # high-level plot
abline(0, 1)    # low-level change
plot(rnorm(10)) # high-level plot
## many low-level changes in a loop (a single R expression)
for(i in 1:10) {
    abline(v = i, lty = 2)
}
@

Normally this produces 2 plots in the output (i.e. when fig.keep='high'); for fig.keep='none', no plots will be saved; for fig.keep='all', 4 plots are saved; for fig.keep='first', the plot produced by plot(1) is saved, and for fig.keep='last', the last plot with 10 vertical lines is saved.

There are two hidden options which are not designed to be set by the 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 which 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 opts_knit; for example,

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

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

All package options are: