knit
Knit a document
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
wrapper to knit(..., tangle = TRUE)
).
Usage
knit(input, output = NULL, tangle = FALSE, text = NULL, quiet = FALSE,
envir = parent.frame(), encoding = getOption("encoding"))purl(..., documentation = 1L)
Arguments
- input
- path of the input file
- output
- path of the output file for
knit()
; ifNULL
, this function will try to guess and it will be under the current working directory - tangle
- whether to tangle the R code from the input file (like
Stangle
) - text
- a character vector as an alternative way to provide the input file
- quiet
- whether to suppress the progress bar and messages
- envir
- the environment in which the code chunks are to be evaluated
(for example,
parent.frame()
,new.env()
, orglobale
- encoding
- the encoding of the input file; see
file
- ...
- arguments passed to
knit()
frompurl()
- documentation
- an integer specifying the level of documentation to go
the tangled script:
0
means pure code (discard all text chunks);1
(default) means add the chunk headers to code;2
means add all text chunks to code as roxygen
Details
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 a 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:
ext
is not txt
, otherwise the output is tangle = TRUE
,
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 apat
). First
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 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
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
the hooks).
See the package website and manuals in the references to know more about
Value
- The compiled document is written into the output file, and the path
of the output file is returned, but if the
output
path isNULL
, the output is returned as a character vector.
Note
The name 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
recursively. See knit_child
.
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 (like
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
.
The arguments input
and output
do not have to be restricted
to files; they can be stdin()
/stdout()
or other types of
connections, but the pattern list to read the input has to be set in
advance (see pat_rnw
), and the output hooks should also be
set (see render_latex
), otherwise
If the output
argument is a file path, it is strongly recommended to
be in the current working directory (e.g. setwd('out/'); knit('../foo.Rmd')
, instead of
knit('foo.Rmd', 'out/foo.md')
.
N.B. There is no guarantee that the R script generated by purl()
can
reproduce the computation done in knit()
. The knit()
process
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
References
Package homepage:
See citation('knitr')
for the citation information.
Examples
library(knitr)
(f = system.file("examples", "knitr-minimal.Rnw", package = "knitr"))
knit(f) # compile to tex
purl(f) # tangle R code
purl(f, documentation = 0) # extract R code only
purl(f, documentation = 2) # also include documentation