Overview
Inspired by Sweave, the knitrpackage was designed to be a transparent engine for dynamic report generationwith R, and combine features in other add-on packages into one package(knitr ≈ Sweave + cacheSweave + pgfSweave + weaver +animation::saveLatex() + R2HTML::RweaveHTML() +highlight::HighlightWeaveLatex() + 0.2 * brew + 0.1 * SweaveListingUtils +more).
- Transparency means that the user has full access to every piece of the inputand output, e.g.,
1 + 2produces[1] 3in an R terminal, and knitrcan let the user decide whether to put1 + 2between\begin{verbatim}and\end{verbatim}, or<div class="rsource">and</div>, and put[1] 3in\begin{Routput}and\end{Routput}; see the hookspage for details. - knitr tries to be consistent with users’ expectations by running R codeas if it were pasted in an R terminal, e.g.,
qplot(x, y)directly producesthe plot (no need toprint()it), and all the plots in a code chunk willbe written to the output by default. - Packages like pgfSweave and cacheSweave have added useful featuresto Sweave (high-quality tikz graphics and cache), and knitr hassimplified the implementations.
- The design of knitr allows any input languages (e.g., R, Python, andshell scripts) and any output markup languages (e.g., LaTeX, HTML, Markdown,AsciiDoc, and reStructuredText).
This package is developed on GitHub; forinstallation instructions and FAQ’s, seeREADME. This website serves as the fulldocumentation of knitr, and you can find the mainmanual, the graphics manual andother demos /examples here. For a more organizedreference, see the knitr book.
Motivation
Sweave was a clever and novel implementation of Literate Programming. Its majorproblem was that it was hard to extend. The knitr package tried tomodularize the whole process of weaving a document into small manageablefunctions, to make it easier to maintain and extend (e.g., easy to support HTMLoutput). On the other hand, knitr has many built-in features and it shouldnot be the case to have to hack at the core components of this package. By theway, several FAQ’s in the Sweave manual have been solved in knitr directly.
Let us change our traditional attitude to the construction of programs:Instead of imagining that our main task is to instruct a computer what to do,let us concentrate rather on explaining to humans what we want the computer todo.
— Donald E. Knuth, Literate Programming, 1984
Features
The ideas are borrowed from other packages, and some of them are re-implementedin a different way (such as caching). A selected list of features include:
faithful output: usingevaluate as the backend toevaluate R code, knitr writes everything that you see in an R terminalinto the output by default, including printed results, plots and evenwarnings, messages as well as errors (they should not be ignored in seriouscomputations, especially warnings)
- a minor issue is that for grid-based graphics packages like ggplot2or lattice, users often forget to
print()the plot objects,because they can get the output in an R terminal without reallyprint()ing; in knitr, what you get is what you expected
- a minor issue is that for grid-based graphics packages like ggplot2or lattice, users often forget to
built-in cache: ideas like cacheSweave but knitr directly uses baseR functions to fulfill cache and lazy loading, and another significantdifference is that a cached chunk can still have output (in cacheSweave,cached chunks no longer have any output, even you explicitly
print()anobject; knitr actually caches the chunk output as well)formatting R code: the formatR package is used to reformat Rcode automatically (wrap long lines, add spaces and indent, etc), withoutsacrificing comments as
keep.source=FALSEdoesmore than 20 graphics devices are directly supported: with
dev='CairoPNG'in the chunk options, you can switch to theCairoPNG()device inCairo in a second; withdev='tikz', thetikz()device intikzDevice is used; Couldanything be easier than that? These built-in devices (strictly speaking,wrappers) use inches as units, even for bitmap devices (pixels are convertedto inches by the optiondpi, which defaults to 72)even more flexibility on graphics:
- width and height in the output document of plots can be additionallyspecified (the
fig.widthoption is for the graphics device, andout.widthis for the output document; thinkout.width='.8\\textwidth') - locations of plots can be rearranged: they can either appear exactly inthe place where they are created, or go to the end of a chunk together(option
fig.show='hold') - multiple plots per code chunk are recorded, unless you really want tokeep the last plot only (option
fig.keep='last')
- width and height in the output document of plots can be additionallyspecified (the
R code not only can come from code chunks in the input document, but alsomay be from an external R script, which makes it easier to run the code asyou write the document (this will especially benefit LyX)
for power users, further customization is still possible:
- the regular expressions to parse R code can be defined, i.e., you do nothave to use
<<>>=and@or\Sexpr{}; if you like, you can use anypatterns, e.g.,%% begin.rcodeand%% end.rcode - hooks can be defined to control the output; e.g. you may want to puterrors in red bold texts, or you want the source code to be italic, etc;hooks can also be defined to be executed before or after a code chunk,and there are infinite possibilities to extend the power of this packageby hooks (e.g. animations, rgl 3D plots, …)
- the regular expressions to parse R code can be defined, i.e., you do nothave to use
Lots of efforts have been made to producing beautiful output and enhancingreadability by default. For example, code chunks are highlighted and put in ashaded environment in LaTeX with a very light gray background (theframed package), so they can stand out alittle bit from other texts. The reading experience is hopefully better than theverbatim or Verbatim environments. The leading characters > and +(called prompts) in the output are not added by default (you can bring themback by prompt=TRUE, though). I find them really annoying in the output when Iread the output document, because it is so very inconvenient to copy and run thecode which is messed up by these characters.
Acknowledgements
I thank the authors of Sweave, pgfSweave, cacheSweave, brew,decumar, R2HTML, tikzDevice, highlight, digest,evaluate, roxygen2 and of course, R, for the many inspiring ideas andtools. I really appreciate the feedbackfrom many early beta testers. This package was initiated based on the design ofdecumar.
FOAS
knitr is proudly affiliated with the Foundation for Open AccessStatistics (FOAS). FOAS is a nonprofit public benefitcorporation with a worldwide mission to promote free software, open accesspublishing, and reproducible research in statistics.
