knitr — Dynamic Report Generation with R

Introduction

knitr is an R package by Yihui Xie that implements literate programming for R. It reads documents containing a mix of prose and code chunks, executes the code, and replaces each chunk with its output (text, tables, figures). knitr is the execution engine that powers R Markdown, bookdown, blogdown, and most reproducible reporting workflows in R.

What knitr Does

• Parses documents for code chunks delimited by special markers and executes them in an R session
• Captures output, warnings, messages, errors, and plots from each chunk
• Supports R, Python, SQL, Bash, Julia, and 30+ other language engines
• Provides chunk options to control execution, display, caching, figure dimensions, and error handling
• Caches chunk results to avoid re-executing expensive computations on subsequent renders

Architecture Overview

knitr uses a pattern-based parser to identify code chunks in source documents. For each chunk, it evaluates the code in a shared R environment, captures all side effects, and formats the results according to the output document type. Output hooks transform raw results into format-specific markup (Markdown, LaTeX, HTML). The caching system stores chunk results keyed by chunk content and options, invalidating the cache when code changes. knitr produces an intermediate document (e.g., .md from .Rmd) that Pandoc or LaTeX then converts to the final format.

Self-Hosting & Configuration

• Install from CRAN: install.packages("knitr")
• Set global chunk options with knitr::opts_chunk$set(echo = TRUE, fig.width = 7, fig.height = 5)
• Enable caching with cache = TRUE per chunk or globally to skip unchanged computations
• Use engine chunk option to run Python, SQL, Bash, or other languages
• Customize output hooks with knitr::knit_hooks$set() for format-specific rendering

Key Features

• Language-agnostic: 30+ built-in engines let you mix R, Python, SQL, and shell code in one document
• Chunk options provide fine-grained control: show/hide code, control figure size, set timeouts, handle errors
• Caching system speeds up iterative rendering by reusing results from unchanged chunks
• Child documents allow modular report composition by including sub-documents
• Custom output hooks enable specialized formatting for any target format

Comparison with Similar Tools

• Sweave (R) — the original R literate programming tool; knitr is its successor with more features, caching, and language support
• Jupyter (Python) — notebook-based execution; knitr is document-based and produces cleaner source files for version control
• Org-Babel (Emacs) — multi-language literate programming in Org Mode; knitr is more accessible outside the Emacs ecosystem
• Quarto — uses knitr as one of its execution engines alongside Jupyter; knitr can be used independently
• nbdev (Python) — develops libraries from notebooks; knitr focuses on report generation rather than package development

FAQ

Q: What is the relationship between knitr and R Markdown? A: knitr is the execution engine; R Markdown is the document format. R Markdown uses knitr to process code chunks, then Pandoc to convert the result to HTML, PDF, or Word.

Q: How does chunk caching work? A: When cache = TRUE, knitr saves each chunk's results to disk. On subsequent renders, unchanged chunks load from cache instead of re-executing. If the chunk code or its dependencies change, the cache is invalidated.

Q: Can I use knitr without RStudio? A: Yes. knitr is a standalone R package. Call knitr::knit() from any R console or script.

Q: How do I include Python code in a knitr document? A: Use a code chunk with engine = "python". The reticulate package enables data sharing between R and Python chunks.

Sources

• https://github.com/yihui/knitr
• https://yihui.org/knitr/