R Tips

Home

Contact

Steven Holland

Sharing Your R Work Easily

28 February 2015

When we use R, we often wish to share our work. This might mean sending our plots, tables, and results, as well as our explanation of it all. We might also wish to share our code and data, and this quickly adds up to many files that can be hard to sort through. It would be great to bring all of this together, so that we could share our results, our explanations, and how we got to those results. R’s knitr package makes this incredibly simple.

What knitr allows us to do is write our R code, add some explanation and comments, tag those items with a minimum of markup, and turn them into a well-formatted web page that shows our code, our explanations, our results, even our figures. It makes our work reproducible, and it makes it open. It encourages the reader to experiment with our code.

As an example, knitr will take a simple text file like this, and turn it into this web page. All the formatting on the web page is done automatically for you.

Markdown and R Markdown

knitr can accept several kinds of input, but the simplest is R Markdown, based on John Gruber’s Markdown language. I will illustrate this simple language with a few basic items.

To make a heading, insert a pound sign before that line:

# My first heading

To make subheadings, add additional pound signs:

## A second-order heading ### A third-order heading

To make paragraphs of normal text, just follow them with two carriage returns. To italicize text, add an asterisk on either side *like this*. To make bold text, put two asterisks on either side **like this**.

There are many other tags you can add that are just a simple. There are tags for making numbered lists, unordered lists, web-page anchors, tables, quotes, and more. There are many cheatsheets available. I like Scott Born’s one-page reference and John Gruber’s original specification on his Daring Fireball blog.

R Markdown adds just a few tags to Markdown so that you can identify what is R code. The most common type is a code chunk, which is just a block of code. It looks like this:

```{r aCodeChunk} x <- c(2,3,4,7,9,23) mean(x) ```

On the line before your R code starts, begin with three backticks (the key above your tab key), followed by a curly brace, the letter r, and the name of your code chunks, which can be anything you wish. Finish it with a curly brace.

On the line following your R code, three back ticks will close the chunk. You will likely have multiple chunks; give them different names.

You can also include inline R code inside a line of text like this:

The sample size is `r length(x)`

A backtick and a lower case r open the R code, and a backtick closes it.

This will cover most of what you need to do. For more details, see Karl Broman’s guide.

knitr

To use knitr, write your R code as you have always done. Surround any chunks of code with the R Markdown tags. Add any headings and paragraphs of explanation using Markdown tags. You will quickly memorize these as there are so few. Save the file as a plain-text file with an .rmd suffix (for R Markdown; normal Markdown has a .md suffix).

To use knitr in R, you will need to install the rmarkdown and knitr packages, and be sure to install their dependencies. Load the libraries, be sure R is in the directory with your R Markdown file, then use knit2html() to build your html:

library(rmarkdown) library(knitr) knit2html("myRMarkdownFile.rmd")

If you automatically load these libraries in your startup file, all you need is the knit2html() command to turn your Markdown into a webpage. Hard to get any easier!

When you run knit2html(), it will make a plain Markdown file (.md) and an html file, both with the same name as your R Markdown file. If you generate any figures, a folder called ‘figure’ will be created with each of the figures as .png files.

To share your work, you need only send the html file, as the figures will be embedded in the html file itself.