This function takes an input file, extracts the R code in it according to a
list of patterns, evaluates the code and writes the output in another file.
It can also tangle R source code from the input document (
purl() is a
knit(..., tangle = TRUE)). The
option can be used to also tangle the code of inline expressions (disabled
1 2 3 4
Path to the input file.
Path to the output file for
Boolean; whether to tangle the R code from the input file (like
A character vector. This is an alternative way to provide the input file.
Boolean; suppress the progress bar and messages?
Environment in which code chunks are to be evaluated,
Encoding of the input file; see
arguments passed to
An integer specifying the level of documentation to add to
the tangled script.
For most of the time, it is not necessary to set any options outside the
input document; in other words, a single call like
knit('my_input.Rnw') is usually enough. This function will try to
determine many internal settings automatically. For the sake of
reproducibility, it is better practice to include the options inside the
input document (to be self-contained), instead of setting them before
knitting the document.
First the filename of the output document is determined in this way:
‘foo.Rnw’ generates ‘foo.tex’, and other filename extensions like
‘.Rtex’, ‘.Rhtml’ (‘.Rhtm’) and ‘.Rmd’
(‘.Rmarkdown’) will generate ‘.tex’, ‘.html’ and ‘.md’
respectively. For other types of files, if the filename contains
_knit_, this part will be removed in the output file, e.g.,
‘foo_knit_.html’ creates the output ‘foo.html’; if _knit_ is
not found in the filename, ‘foo.ext’ will produce ‘foo.txt’ if
ext is not
txt, otherwise the output is ‘foo-out.txt’. If
tangle = TRUE, ‘foo.ext’ generates an R script ‘foo.R’.
We need a set of syntax to identify special markups for R code chunks and R
options, etc. The syntax is defined in a pattern list. All built-in pattern
lists can be found in
all_patterns (call it
knitr will try to decide the pattern list based on the filename
extension of the input document, e.g. Rnw files use the list
apat$rnw, tex uses the list
apat$tex, brew uses
apat$brew and HTML files use
apat$html; for unkown extensions,
the content of the input document is matched against all pattern lists to
automatically determine which pattern list is being used. You can also manually
set the pattern list using the
knit_patterns object or the
pat_rnw series functions in advance and knitr will
respect the setting.
According to the output format (
opts_knit$get('out.format')), a set of
output hooks will be set to mark up results from R (see
render_latex). The output format can be LaTeX, Sweave and HTML,
etc. The output hooks decide how to mark up the results (you can customize
knit comes from its counterpart weave (as in Sweave),
and the name
purl (as tangle in Stangle) comes from a knitting
method ‘knit one, purl one’.
If the input document has child documents, they will also be compiled
See the package website and manuals in the references to know more about knitr, including the full documentation of chunk options and demos, etc.
The compiled document is written into the output file, and the path
of the output file is returned. If the
text argument is not
NULL, the compiled output is returned as a character vector. In
other words, if you provide a file input, you get an output filename; if
you provide a character vector input, you get a character vector output.
The working directory when evaluating R code chunks is the directory of
the input document by default, so if the R code involves external files
read.table()), it is better to put these files under the same
directory of the input document so that we can use relative paths. However,
it is possible to change this directory with the package option
opts_knit$set(root.dir = ...) so all paths in code chunks are
relative to this
root.dir. It is not recommended to change the
working directory via
setwd() in a code chunk, because it may
lead to terrible consequences (e.g. figure and cache files may be written to
wrong places). If you do use
setwd(), please note that knitr
will always restore the working directory to the original one. Whenever you
feel confused, print
getwd() in a code chunk to see what the working
directory really is.
output do not have to be restricted
to files; they can be
stdout() or other types of
connections, but the pattern list to read the input has to be set in
pat_rnw), and the output hooks should also be
render_latex), otherwise knitr will try to
guess the patterns and output format.
output argument is a file path, it is strongly recommended to
be in the current working directory (e.g. ‘foo.tex’ instead of
‘somewhere/foo.tex’), especially when the output has external
dependencies such as figure files. If you want to write the output to a
different directory, it is recommended to set the working directory to
that directory before you knit a document. For example, if the source
document is ‘foo.Rmd’ and the expected output is ‘out/foo.md’,
you can write
setwd('out/'); knit('../foo.Rmd') instead of
N.B. There is no guarantee that the R script generated by
reproduce the computation done in
can be fairly complicated (special values for chunk options, custom chunk
hooks, computing engines besides R, and the
envir argument, etc). If
you want to reproduce the computation in a report generated by
knit(), be sure to use
knit(), instead of merely executing
the R script generated by
purl(). This seems to be obvious, but some
people just do not get it.
citation('knitr') for the citation information.
1 2 3 4 5 6 7
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.