Skip to Content

Increasing Readability of R Output with Markdown

Printer-friendly versionPrinter-friendly version
Issue: 
Fall 2014

--John Porter, Virginia Coast Reserve LTER

The R statistical package has many statistical and graphical capabilities and a large and active user base, making help easy to find on the Internet.  However, raw R output is relatively bare-bones making it difficult to display in easily interpretable forms – especially after a long time has elapsed.

One solution that helps increase the readability of R is Markdown. Using Markdown you can create dynamic documents that integrate text, R code, R results and R graphics into a single HTML, PDF or Word document.  Markdown is integrated into the popular RStudio user interface for R, but can also be run directly from the command line.

Describing Markdown may best be shown with a simple example.  Here is the "default" R MarkDown (.rmd) document supplied by RStudio:

---
title: "R_Markdown_Demo"
date: "Thursday, December 04, 2014"
output: html_document
---

This is an R Markdown document. Markdown is a simple formatting syntax for
authoring HTML, PDF, and MS Word documents. For more details on using R
Markdown see <http://rmarkdown.rstudio.com>.

When you click the **Knit** button a document will be generated that
includes both content as well as the output of any embedded R code chunks
within the document. You can embed an R code chunk like this:

```{r}
summary(cars)
```

You can also embed plots, for example:

```{r, echo=FALSE}
plot(cars)
```

Note that the `echo = FALSE` parameter was added to the code chunk to
prevent printing of the R code that generated the plot.

Hitting the "Knit HTML" button in RStudio or using the rmarkdown::render function from the command line, produces an HTML output that looks like this:

The Markdown language is relatively simple. R code appears in triple single backquotes labeled with {R} and options for whether the code will be echoed or not. A single asterix (*) can be used to produce *italics* (e.g., italics) double asterix "**" delimit the start and end of bold - thus **bold** comes out bold. Although not show in the example, proceeding text with a # makes it into a large heading (## and ### make successively smaller headings) and preceeding text with a single hyphen ("-") makes it appear as a bulleted list item and a plus ("+") a numbered list item. There are also options for including tables, hyperlinks and even LaTeX style equations.  See http://rmarkdown.rstudio.com/authoring_basics.html for details. 

Markdown makes it relatively easy to generate ready-to use outputs showing data displays for posting on the web or including in reports as WORD documents. However, I also use it to provide more attractive and readable commentary regarding my R code than the simple comments embedded in the code itself. If using RStudio, you can also select and run individual chunks of R code for testing and debugging. This is helpful because "kniting" large and complex documents takes slightly longer than running the R code alone.