knitr logo

knitr: elegant, flexible, and fast dynamic report generation with R

knitr

Elegant, flexible, and fast dynamic report generation with R


Overview

The knitr package was designed to be a transparent engine for dynamic report generation with R, solve some long-standing problems in Sweave, 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).

This package is developed on GitHub; for installation instructions and FAQ’s, see README. This website serves as the full documentation of knitr, and you can find the main manual, the graphics manual and other demos / examples here. You can also watch a 5-min video introduction. For a more organized reference, see the knitr book.

Motivation

One of the difficulties with extending Sweave is we have to copy a large amount of code from the utils package (the file SweaveDrivers.R has more than 700 lines of R code), and this is what the two packages mentioned above have done. Once the code is copied, the package authors have to pay close attention to what is changing in the version in official R – apparently an extra burden. The knitr package tried to modularize the whole process of weaving a document into small manageable functions, so it is hopefully easier to maintain and extend (e.g. easy to support HTML output); on the other hand, knitr has many built-in features and it should not be the case to have to hack at the core components of this package. By the way, several FAQ’s in the Sweave manual are 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 to do.

— Donald E. Knuth, Literate Programming, 1984

Features

The ideas are borrowed from other packages, and some of them are re-implemented in a different way (like cache). A selected list of features include:

Lots of efforts have been made to producing beautiful output and enhancing readability by default. For example, code chunks are highlighted and put in a shaded environment in LaTeX with a very light gray background (the framed package), so they can stand out a little bit from other texts. The reading experience is hopefully better than the verbatim or Verbatim environments. The leading characters > and + (called prompts) in the output are not added by default (you can bring them back by prompt=TRUE, though). I find them really annoying in the output when I read the output document, because it is so very inconvenient to copy and run the code 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 and tools. I really appreciate the feedback from many early beta testers. This package was initiated based on the design of decumar.

FOAS

knitr is proudly affiliated with the Foundation for Open Access Statistics (FOAS). FOAS is a nonprofit public benefit corporation with a worldwide mission to promote free software, open access publishing, and reproducible research in statistics.