EVOLUTION-MANAGER
Edit File: knit.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Knit a document</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for knit {knitr}"><tr><td>knit {knitr}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Knit a document</h2> <h3>Description</h3> <p>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 (<code>purl()</code> is a wrapper to <code>knit(..., tangle = TRUE)</code>). The <code>knitr.purl.inline</code> option can be used to also tangle the code of inline expressions (disabled by default). </p> <h3>Usage</h3> <pre> knit( input, output = NULL, tangle = FALSE, text = NULL, quiet = FALSE, envir = parent.frame(), encoding = "UTF-8" ) purl(..., documentation = 1L) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>input</code></td> <td> <p>Path to the input file.</p> </td></tr> <tr valign="top"><td><code>output</code></td> <td> <p>Path to the output file for <code>knit()</code>. If <code>NULL</code>, this function will try to guess a default, which will be under the current working directory.</p> </td></tr> <tr valign="top"><td><code>tangle</code></td> <td> <p>Boolean; whether to tangle the R code from the input file (like <code>utils::<a href="../../utils/html/Sweave.html">Stangle</a></code>).</p> </td></tr> <tr valign="top"><td><code>text</code></td> <td> <p>A character vector. This is an alternative way to provide the input file.</p> </td></tr> <tr valign="top"><td><code>quiet</code></td> <td> <p>Boolean; suppress the progress bar and messages?</p> </td></tr> <tr valign="top"><td><code>envir</code></td> <td> <p>Environment in which code chunks are to be evaluated, for example, <code><a href="../../base/html/sys.parent.html">parent.frame</a>()</code>, <code><a href="../../base/html/environment.html">new.env</a>()</code>, or <code><a href="../../base/html/environment.html">globalenv</a>()</code>).</p> </td></tr> <tr valign="top"><td><code>encoding</code></td> <td> <p>Encoding of the input file; always assumed to be UTF-8 (i.e., this argument is effectively ignored).</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>arguments passed to <code><a href="knit.html">knit</a>()</code> from <code>purl()</code></p> </td></tr> <tr valign="top"><td><code>documentation</code></td> <td> <p>An integer specifying the level of documentation to add to the tangled script. <code>0</code> means to output pure code, discarding all text chunks); <code>1</code> (the default) means to add the chunk headers to the code; <code>2</code> means to add all text chunks to code as roxygen comments.</p> </td></tr> </table> <h3>Details</h3> <p>For most of the time, it is not necessary to set any options outside the input document; in other words, a single call like <code>knit('my_input.Rnw')</code> 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. </p> <p>First the filename of the output document is determined in this way: ‘<span class="file">foo.Rnw</span>’ generates ‘<span class="file">foo.tex</span>’, and other filename extensions like ‘<span class="file">.Rtex</span>’, ‘<span class="file">.Rhtml</span>’ (‘<span class="file">.Rhtm</span>’) and ‘<span class="file">.Rmd</span>’ (‘<span class="file">.Rmarkdown</span>’) will generate ‘<span class="file">.tex</span>’, ‘<span class="file">.html</span>’ and ‘<span class="file">.md</span>’ respectively. For other types of files, if the filename contains <span class="samp">_knit_</span>, this part will be removed in the output file, e.g., ‘<span class="file">foo_knit_.html</span>’ creates the output ‘<span class="file">foo.html</span>’; if <span class="samp">_knit_</span> is not found in the filename, ‘<span class="file">foo.ext</span>’ will produce ‘<span class="file">foo.txt</span>’ if <code>ext</code> is not <code>txt</code>, otherwise the output is ‘<span class="file">foo-out.txt</span>’. If <code>tangle = TRUE</code>, ‘<span class="file">foo.ext</span>’ generates an R script ‘<span class="file">foo.R</span>’. </p> <p>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 <code>all_patterns</code> (call it <code>apat</code>). First <span class="pkg">knitr</span> will try to decide the pattern list based on the filename extension of the input document, e.g. <span class="samp">Rnw</span> files use the list <code>apat$rnw</code>, <span class="samp">tex</span> uses the list <code>apat$tex</code>, <span class="samp">brew</span> uses <code>apat$brew</code> and HTML files use <code>apat$html</code>; 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 <code><a href="knit_patterns.html">knit_patterns</a></code> object or the <code><a href="pat_fun.html">pat_rnw</a></code> series functions in advance and <span class="pkg">knitr</span> will respect the setting. </p> <p>According to the output format (<code>opts_knit$get('out.format')</code>), a set of output hooks will be set to mark up results from R (see <code><a href="output_hooks.html">render_latex</a></code>). 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). </p> <p>The name <code>knit</code> comes from its counterpart <span class="samp">weave</span> (as in Sweave), and the name <code>purl</code> (as <span class="samp">tangle</span> in Stangle) comes from a knitting method ‘knit one, purl one’. </p> <p>If the input document has child documents, they will also be compiled recursively. See <code><a href="knit_child.html">knit_child</a></code>. </p> <p>See the package website and manuals in the references to know more about <span class="pkg">knitr</span>, including the full documentation of chunk options and demos, etc. </p> <h3>Value</h3> <p>The compiled document is written into the output file, and the path of the output file is returned. If the <code>text</code> argument is not <code>NULL</code>, 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. </p> <h3>Note</h3> <p>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 <code>read.table()</code>), 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 <code><a href="opts_knit.html">opts_knit</a>$set(root.dir = ...)</code> so all paths in code chunks are relative to this <code>root.dir</code>. It is not recommended to change the working directory via <code><a href="../../base/html/getwd.html">setwd</a>()</code> 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 <code>setwd()</code>, please note that <span class="pkg">knitr</span> will always restore the working directory to the original one. Whenever you feel confused, print <code>getwd()</code> in a code chunk to see what the working directory really is. </p> <p>If the <code>output</code> argument is a file path, it is strongly recommended to be in the current working directory (e.g. ‘<span class="file">foo.tex</span>’ instead of ‘<span class="file">somewhere/foo.tex</span>’), 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 ‘<span class="file">foo.Rmd</span>’ and the expected output is ‘<span class="file">out/foo.md</span>’, you can write <code>setwd('out/'); knit('../foo.Rmd')</code> instead of <code>knit('foo.Rmd', 'out/foo.md')</code>. </p> <p>N.B. There is no guarantee that the R script generated by <code>purl()</code> can reproduce the computation done in <code>knit()</code>. The <code>knit()</code> process can be fairly complicated (special values for chunk options, custom chunk hooks, computing engines besides R, and the <code>envir</code> argument, etc). If you want to reproduce the computation in a report generated by <code>knit()</code>, be sure to use <code>knit()</code>, instead of merely executing the R script generated by <code>purl()</code>. This seems to be obvious, but some people <a href="http://bit.ly/SnLi6h">just do not get it</a>. </p> <h3>References</h3> <p>Package homepage: <a href="https://yihui.org/knitr/">https://yihui.org/knitr/</a>. The <span class="pkg">knitr</span> <a href="https://yihui.org/knitr/demo/manual/">main manual</a>: and <a href="https://yihui.org/knitr/demo/graphics/">graphics manual</a>. </p> <p>See <code>citation('knitr')</code> for the citation information. </p> <h3>Examples</h3> <pre> 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 unlink(c("knitr-minimal.tex", "knitr-minimal.R", "figure"), recursive = TRUE) </pre> <hr /><div style="text-align: center;">[Package <em>knitr</em> version 1.29 <a href="00Index.html">Index</a>]</div> </body></html>