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:
- Chunk options must be written in one line; no line breaks are allowed inside chunk options;
- 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, whereassetup.options
andchunk 1
are bad;fig.path='figures/mcmc-'
is a good prefix for figure output if this project is about MCMC, andfig.path='markov chain/monte carlo'
is bad; non-alphanumeric characters except-
and_
in figure filenames will be replaced with_
automatically; - 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 offig.path=abc
, andout.width='\\textwidth'
instead ofout.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
andFALSE
are OK, andtrue
/false
will not work as you might have expected becausetrue
is notTRUE
- you can write arbitrarily complicated expressions as you want as long as they are legitimate R code
- if you come from the Sweave land, please read the transition page carefully because the syntax is different
- for example, options that take character values must be quoted as you do in R (e.g. should write
All built-in options in knitr are:
Code Evaluation
eval
: (TRUE
; logical) whether to evaluate the code chunk; it can also be a numeric vector to select which R expression(s) to evaluate, e.g.eval=c(1, 3, 4)
oreval=-(4:5)
Text Results
echo
: (TRUE
; logical or numeric) whether to include R source code in the output file; besidesTRUE
/FALSE
which completely turns on/off the source code, we can also use a numeric vector to select which R expression(s) to echo in a chunk, e.g.echo=2:3
means only echo the 2nd and 3rd expressions, andecho=-4
means to exclude the 4th expressionresults
: ('markup'
; character) takes three possible valuesmarkup
: mark up the results using the output hook, e.g. put results in a special LaTeX environmentasis
: output as-is, i.e., write raw results from R into the output documenthide
hide results; this option only applies to normal R output (not warnings, messages or errors)- note
markup
andasis
are equivalent toverbatim
andtex
in Sweave respectively (you can still use the latter two, but they can be misleading, e.g.,verbatim
does not really mean verbatim in R, andtex
seems to be restricted to LaTeX)
warning
: (TRUE
; logical) whether to preserve warnings (produced bywarning()
) in the output like we run R code in a terminal (ifFALSE
, all warnings will be discarded)error
: (TRUE
; logical) whether to preserve errors (fromstop()
) (by default, the evaluation will not stop even in case of errors!!)message
: (TRUE
; logical) whether to preserve messages emitted bymessage()
split
: (FALSE
; logical) whether to split the output from R into separate files and include them into LaTeX by\input{}
or HTML by<iframe></iframe>
include
: (TRUE
; logical) whether to include the chunk output in the final output document; ifinclude=FALSE
, nothing will be written into the output document, but the code is still evaluated and plot files are generated if there are any plots in the chunk, so you can manually insert figures; note this is the only chunk option that is not cached, i.e., changing it will not invalidate the cache
Code Decoration
tidy
: (TRUE
; logical) whether R code should be tidied up using the functiontidy.source()
in the formatR package; if it failed to tidy up, original R code will not be changed;tidy=TRUE
is likekeep.source=FALSE
in Sweave, but it also tries not to discard R comments (N.B. this option does not work in certain cases; see https://github.com/yihui/formatR/wiki for more information)tidy.opts
: (NULL
; list) a list of options to be passed totidy.source()
, e.g.tidy.opts=list(keep.blank.line=FALSE, width.cutoff=60)
; these formatR options can also be set globally viaoptions()
prompt
: (FALSE
; logical) whether to add the prompt characters in the R code (seeprompt
andcontinue
in?base::options
; note that adding prompts can make it difficult for readers to copy R code from the output, soprompt=FALSE
may be a better choicecomment
: ('##'
; character) the prefix to be put before source code output; default is to comment out the output by##
, which is good for readers to copy R source code since output is masked in comments (setcomment=NA
to disable this feature)highlight
: (TRUE
; character) whether to highlight the source code (it isFALSE
by default the output is markdown or Sweave or listings)size
: ('normalsize'
; character) font size for the default LaTeX output (see?highlight
in the highlight package for a list of possible values)background
: ('#F7F7F7'
; character or numeric) background color of chunks in LaTeX output (passed to the LaTeX package framed); the color model isrgb
; it can be either a numeric vector of length 3, with each element between 0 and 1 to denote red, green and blue, or any built-in color in R likered
orspringgreen3
(seecolors()
for a full list), or a hex string like#FFFF00
, or an integer (all these colors will be converted to the RGB model; see?col2rgb
for details)
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
cache
: (FALSE
; logical) whether to cache a code chunk; when evaluating code chunks, the cached chunks are skipped, but the objects created in these chunks are (lazy-) loaded from previously saved databases (.rdb
and.rdx
) files, and these files are saved when a chunk is evaluated for the first time, or when cached files are not found (e.g. you may have removed them by hand); note the filename consists of the chunk label with an MD5 digest of the R code in the chunk (the MD5 string is a summary of the chunk text, and any changes in the chunk will produce a different MD5 digest); unlike the cacheSweave package which uses stashR, this package directly uses internal functions in base R for cache, and another difference is that results of the code will still be included in the output even when cache is used (whereas cacheSweave has no output when a chunk is cached), because knitr also caches the printed output of a code chunk as a character stringcache.path
: ('cache/'
; character) a prefix to be used for the names of cache files (by default they are saved to a directory namedcache
relative to the current working directory; you can also use an absolute dir here, e.g./home/foo/bar-
orD:\\abc\\mycache
, but it is not recommended since such absolute directories may not exist in other people's systems, therefore it is recommended to use relative directories)cache.vars
: (NULL
) a character vector of variable names to be saved in the cache database; by default all variables created in the current chunks are identified and saved, but we can manually set the variables to be saveddependson
: (NULL
; character or numeric) a character vector of chunk labels to specify which other chunks this chunk depends on; this option applies to cached chunks only -- sometimes the objects in a cached chunk may depend on other cached chunks, so when other chunks are changed, this chunk must be updated accordingly- if
dependson
is a numeric vector, it means the indices of chunk labels, e.g.dependson=1
means this chunk depends on the first chunk in the document, anddependson=c(-1, -2)
means it depends on the previous two chunks (negative indices stand for numbers of chunks before this chunk, and note they are always relative to the current chunk)
- if
autodep
: (FALSE
; logical) whether to figure out the dependencies among chunks automatically by analyzing the global variables in the code (may not be reliable) so thatdependson
does not need to be set explicitly
Plots
fig.path
: ('figure/'
; character) prefix to be used for figure filenames (fig.path
and chunk labels are concatenated to make filenames); it may contain a directory likefigure/prefix-
(will be created if it does not exist); this path is relative to the current working directoryfig.keep
: ('high'
; character) how plots in chunks should be kept; it takes five possible values (see the end of this section for an example)high
: only keep high-level plots (merge low-level changes into high-level plots);none
: discard all plots;all
: keep all plots (low-level plot changes may produce new plots)first
: only keep the first plotlast
: only keep the last plot
fig.show
: ('asis'
; character) how to show/arrange the plots; three possible values areasis
: show plots exactly in places where they were generated (as if the code were run in an R terminal);hold
: hold all plots and output them in the very end of a code chunk;animate
: wrap all plots into an animation if there are mutiple plots in a chunk;
dev
: ('pdf'
for LaTeX output and'png'
for HTML/markdown; character) the function name which will be used as a graphical device to record plots; for the convenience of usage, this package has included all the graphics devices in base R as well as those in Cairo, cairoDevice and tikzDevice, e.g. if we setdev='CairoPDF'
, the function with the same name in the Cairo package will be used for graphics output; if none of the 20 built-in devices is appropriate, we can still provide yet another name as long as it is a legal function name which can record plots (it must be of the formfunction(filename, width, height)
); note the units for images are always inches (even for bitmap devices, in which DPI is used to convert between pixels and inches); currently available devices arebmp
,postscript
,pdf
,png
,svg
,jpeg
,pictex
,tiff
,win.metafile
,cairo_pdf
,cairo_ps
,CairoJPEG
,CairoPNG
,CairoPS
,CairoPDF
,CairoSVG
,CairoTIFF
,Cairo_pdf
,Cairo_png
,Cairo_ps
,Cairo_svg
,tikz
and a series ofquartz
devices includingquartz_pdf
,quartz_png
,quartz_jpeg
,quartz_tiff
,quartz_gif
,quartz_psd
,quartz_bmp
which are just wrappers to the functionquartz()
with different file types- the three options
dev
,fig.ext
anddpi
can be vectors (shorter ones will be recycled), e.g.<<foo, dev=c('pdf', 'png')>>=
creates two files for the same plot:foo.pdf
andfoo.png
- the three options
dev.args
: (NULL
) more arguments to be passed to the device, e.g.dev.args=list(bg='yellow', pointsize=10)
; note this depends on the specific device (see the device documentation); whendev
has multiple elements,dev.args
can be a list of lists of arguments with each list of arguments to be passed to each single device, e.g.<<dev=c('pdf', 'tiff'), dev.args=list(pdf = list(colormodel = 'cmyk', useDingats = TRUE), tiff = list(compression = 'lzw'))>>=
fig.ext
: (NULL
; character) file extension of the figure output (ifNULL
, it will be derived from the graphical device; seeknitr:::auto_exts
for details)dpi
: (72
; numeric) the DPI (dots per inch) for bitmap devices (dpi * inches = pixels
)fig.width
,fig.height
: (both are7
; numeric) width and height of the plot, to be used in the graphics device (in inches) and have to be numericout.width
,out.height
: (NULL
; character) width and height of the plot in the final output file (can be different with its realfig.width
andfig.height
, i.e. plots can be scaled in the output document); depending on the output format, these two options can take flexible values, e.g. for LaTeX output, they can be.8\\linewidth
,3in
or8cm
and for HTML, they may be300px
(do not have to be in inches likefig.width
andfig.height
; backslashes must be escaped as\\
); for LaTeX output, the default value forout.width
will be changed to\\maxwidth
which is defined hereout.extra
: (NULL
; character) extra options for figures, e.g.out.extra='angle=90'
in LaTeX output will rotate the figure by 90 degrees; it can be an arbitrary string, e.g. you can write multiple figure options in this option; it also applies to HTML images (extra options will be written into the<img />
tag, e.g.out.extra='style="display:block;"'
)resize.width
,resize.height
: (NULL
; character) the width and height to be used in\resizebox{}{}
in LaTeX; these two options are not needed unless you want to resize tikz graphics because there is no natural way to do it; however, according to tikzDevice authors, tikz graphics is not meant to be resized to maintain consistency in style with other texts in LaTeX; if only one of them isNULL
,!
will be used (read the documentation of graphicx if you do not understand this)fig.align
: ('default'
; character) alignment of figures in the output document (possible values areleft
,right
andcenter
; default is not to make any alignment adjustments)fig.env
: ('figure'
) the LaTeX environment for figures, e.g. setfig.env='marginfigure'
to get\begin{marginfigure}
fig.cap
: (NULL
; character) figure caption to be used in a figure environment in LaTeX (in\caption{}
); ifNULL
orNA
, it will be ignored, otherwise a figure environment will be used for the plots in the chunk (output in\begin{figure}
and\end{figure}
)fig.scap
: (NULL
; character) short caption; ifNULL
, all the words before.
or;
or:
will be used as a short caption; ifNA
, it will be ignoredfig.lp
: ('fig:'
; character) label prefix for the figure label to be used in\label{}
; the actual label is made by concatenating this prefix and the chunk label, e.g. the figure label for<<foo-plot>>=
will befig:foo-plot
by defaultfig.pos
: (''
; character) a character string for the figure position arrangement to be used in\begin{figure}[fig.pos]
fig.subcap
: (NULL
) captions for subfigures; when there are multiple plots in a chunk, and neitherfig.subcap
norfig.cap
is NULL,\subfloat{}
will be used for individual plots (you need to add\usepackage{subfig}
in the preamble); see 067-graphics-options.Rnw for an exampleexternal
: (TRUE
; logical) whether to externalize tikz graphics (pre-compile tikz graphics to PDF); it is only used for thetikz()
device in the tikzDevice package (i.e., whendev='tikz'
) and it can save time for LaTeX compilationsanitize
: (FALSE
; character) whether to sanitize tikz graphics (escape special LaTeX characters); see documentation in the tikzDevice package
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
interval
: (1
; numeric) number of seconds to pause between animation framesaniopts
: ('controls,loop'
) extra options for animations; see the documentation of the animate package
Chunk Reference
ref.label
: (NULL
; character) a character vector of labels of the chunks from which R code is borrowed (see the demo for chunk reference)
Child Documents
child
: (NULL
; character) a character vector of filenames of child documents to be run and input into the main document
Language Engines
engine
: ('R'
; character) the language name of the code chunk; currently other possible values are'python'
and'awk'
/'gawk'
; the objectknit_engines
in this package can be used to set up engines for other languages
Option templates
opts.label
: (NULL
; character) the label of options set inopts_template
(see?opts_template
); this option can save some typing efforts for sets of frequently used chunk options
Package Options
The package options can be changed using the object opts_knit
; for example,
opts_knit$set(progress = TRUE, verbose = TRUE)
All package options are:
animation.fun
: (hook_ffmpeg_html
) a hook function to create animations in HTML output; the default hook uses FFmpeg to convert images to an MP4 videoaliases
: (NULL
) a named character vector to specify the aliases of chunk options, e.g.c(h = 'fig.height', w = 'fig.width')
tells knitr that the chunk optionh
really meansfig.height
, andw
is an alias forfig.width
; this option can be used to save some typing efforts for long option namesbase.dir
: (NULL
) an absolute directory under which the plots are generatedbase.url
: (NULL
) the base url for HTML pageschild.path
: (''
) the search path for child documents; by default child documents are searched for relative to the directory of the parent documentconcordance
: (FALSE
) whether to write a concordance file to map the output line numbers to the input line numbers; this enables one to navigate from the output to the input and can be helpful especially when TeX error occurs (this feature is mainly for RStudio)eval.after
: (NULL
) a character vector of option names; these options will be evaluated after a chunk is evaluated, and all other options will be evaluated before a chunk (e.g. for chunk optionfig.cap=paste('p-value is', t.test(x)$p.value)
, it will be evaluated after the chunk according to the value ofx
ifeval.after='fig.cap'
)header
: the text to be inserted into the output document before the document begins (e.g. after\documentclass{article}
in LaTeX, or<head>
in HTML); this is useful for defining commands and styles in the LaTeX preamble or HTML header; the beginning of document is found using the pattern defined inknit_patternss$get('document.begin')
out.format
: (NULL
) possible values arelatex
,sweave
,html
,markdown
andjekyll
; it will be automatically determined based on the input file, and this option will affect which set of hooks to use (see?render_latex
for example); note this option has to be set beforeknit()
runs (i.e. it does not work if you set it in the document), or alternatively, you can use therender_*
series inside the document to set up the hooksprogress
: (TRUE
) whether to display a progress bar when running knitr; note it also depends on the R optionKNITR_PROGRESS
(it this variable is set toFALSE
viaoptions(KNITR_PROGRESS = FALSE)
, theprogress
option will be set toFALSE
when knitr is loaded)root.dir
: (NULL
) the root directory when evaluating code chunks; ifNULL
, the directory of the input document will be usedself.contained
: (TRUE
) whether the output document should be self-contained (TeX styles written in the tex document, and CSS styles in HTML document)stop_on_error
: (0L
) an integer (0L
,1L
or2L
) to be passed to the evaluate package to decide the behavior of errors in code chunks; see?evaluate::evaluate
for detailsupload.fun
: (identity
) a function that takes a filename as its input, processes it and returns a character string when the output format is HTML or Markdown; typically it is a function to upload a image and return the link to the image, e.g.opts_knit$set(upload.fun = imgur_upload)
can upload a file to http://imgur.com (see?imgur_upload
)use.highlight
: (FALSE
) whether to use the highlight packageverbose
: (FALSE
) whether to show verbose information (e.g., R code in each chunk and message logs) or just show chunk labels and options