Knit a document

Description

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)). The knitr.purl.inline option can be used to also tangle the code of inline expressions (disabled by default).

Usage

knit(input, output = NULL, tangle = FALSE, text = NULL, quiet = FALSE, 
    envir = parent.frame(), encoding = getOption("encoding"))

purl(..., documentation = 1L)

Arguments

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 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 apat). First 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 the hooks).

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.

See the package website and manuals in the references to know more about knitr, including the full documentation of chunk options and demos, etc.

Value

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.

Note

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. 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.

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 knitr will try to guess the patterns and output format.

If the 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 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 just do not get it.

References

Package homepage: https://yihui.name/knitr/. The knitr main manual: and graphics manual.

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