Publishing documents in R

category: R,markdown
date: July 02, 2016

R document publishing for reproducible research

An R document is a file containing:

plain text combined with markup code,
formulas,
and R code chunks.

Publishing an R document means compiling it into an easily readable pdf or HTML file, together with tables and plots produced from executing the R code chunks. The output document should be produced without having to copy and paste objects from different sources.

Compiling R documents into readable documents is part of a reproducible research framework, because it allows for easily reproducing the published documents from its source R file, together with tables and plots produced from executing the R code chunks embedded in the source.

Over the years, two different frameworks for publishing documents have emerged:

The first is the older PostScript framework, created by Adobe Systems for desktop publishing and printing. In the PostScript framework documents are published as pdf files, and they can’t be interactive.
The second is the newer HTML framework, created for web publishing. In the HTML framework documents are published as HTML files, and they can be interactive.

The publishing of R documents has followed the same pattern, and there are now two different frameworks for publishing R documents:

The first is the older Sweave framework for producing pdf files,
The second is the newer R Markdown framework for producing HTML and pdf files.

There are consequently two types of R documents: Sweave files and R Markdown files.

Publishing R documents using the Sweave framework

A Sweave document is a file (usually with extension Rnw) containing:

plain text combined with LaTeX markup code,
formulas written in LaTeX,
and R code chunks.

Publishing a Sweave document means compiling it into a pdf file, together with tables and plots produced from executing the R code chunks.

Sweave documents can be compiled into pdf documents using the knitr package. The knitr function knit2pdf() compiles an Rnw file into a pdf file, for example:
knitr::knit2pdf("statistics.Rnw")
Sweave documents can’t be compiled into HTML format, so they can’t incorporate interactive plots.

Many examples of Sweave documents can be found in algoquant’s GitHub repository of lecture slides: algoquant’s lecture slides on GitHub

Publishing R documents using the R Markdown framework

An R Markdown document is a file (with extension Rmd) containing:

a YAML header,
plain text combined with markdown code,
formulas written in LaTeX, nested between either ‘$’ or ‘$$’ symbols,
and R code chunks, nested between either single ‘' or quadruple '```’ backtick symbols.

Publishing an R Markdown document means compiling it into a pdf or HTML file, together with tables and plots produced from executing the R code chunks. R Markdown documents are compiled using the markdown package, and can be compiled into HTML documents, so they can incorporate interactive plots. The R Markdown framework is relatively easy to use because it relies on the simple markdown markup language, which is close to plain text and is therefore easy to read.

The function render() from package rmarkdown compiles an Rmd file into either a pdf or HTML file:

rmarkdown::render("R-publishing.Rmd")

The type of file produced by render() depends on the YAML header in the Rmd file. If the YAML header includes:
output: pdf_document then a pdf document is produced.
If the YAML header includes:
output: html_documentthen a HTML document is produced.

This post is an R Markdown document that was compiled into an HTML document, and can be found in algoquant’s GitHub repository here: R publishing

Resources for publishing R documents

Links to books, blogs, and tutorials about publishing R documents using the knitr package:

Links to books, blogs, and tutorials about publishing R documents using the rmarkdown package:

Links to books, blogs, and tutorials about publishing R documents and reproducible research: