Elegant, Reproducible R Documents with knitr/Sweave

Sweave and knitr are engines for generating reports with R which are elegant, flexible, and fast dynamic. Sweave is a package in R that enables integration of R code into LaTeX or LyX documents. Developed by Yihui Xie, knitr combines features from Sweave with other add-on packages to enable integration of R code into not only LaTeX and LyX, but also Markdown, HTML, bookdown and other document types.
Access the documentation on knitr at yihui.name/knitr.

On the 30th of May, 2018 we held a meetup to introduce the R community to knitr and Sweave, and showcase some of their applications. During the event, R-markdown, HTML, LaTeX and bookdown examples were presented. Keep reading to hear about each of the presentations given at the event!

R-Markdown

Meirian began the event by introducing Sweave and knitr, and demonstrating how to easily create a R-markdown document in RStudio.

R-markdown enables you to create documents that contain all your code and results, making your data analysis entirely reproducible. However, R-markdown can do much more than that! It allows you to create a script with all your data analysis pipeline, which you can play with as you try different statistical or visualisation methods. The great advantage, as opposed to standard R-scripts, is that you can add text amongst your code to create amazing documents that you can personalise with just a few clicks! Pablo Franco @jpablofranco

There are a few useful cheat sheets available online. I recommend this one, because it outlines the steps to produce your own R-markdown document.

After viewing a demonstration, participants were then encouraged to create their own R-markdown document, and challenged to reproduce the following example:

The *mean* car speed was `r mean(cars$speed)`mph.
The mean car speed was 15.4mph.

HTML

Next, Pablo gave an example of how to create HTML files which contain R code. To demonstrate, he shared an example he had prepared.

Participants had hands-on experience on how to modify the document to generate three types of reports:
  1. Show everything on the script: A document that shows all your code and output. This is excellent for reproducibility, and great for sharing with collaborators.
  2. Show only results: A document that shows only the output from your analysis. Also great for sharing with collaborators.
  3. Show only the relevant parts: Choose what pieces of the code and which outputs to show. Not everyone is interested in the complete process. This functionality allows you to personalise exactly what you want to share.
At the end of the exercise, we were able to create amazing html files that included interactive plots (using the plotly package) and even good-looking regression tables (using stargazer and pander packages). – Pablo Franco @jpablofranco

LaTeX

LaTeX is a programming language for high-quality, beautiful typesetting. Tim showed us how we can also create beautiful documents in LaTeX which contain our R code.

One of the best parts of having a science degree is the way it empowers us in our mundane lives outside of academia. When a housemate needed clarification about how much they should pay each fortnight in rent and bills, I helped them out with a beautiful and reproducible expenditure summary using Sweave, version controlled with Git. Sweave smushes together R and LaTeX in the spirit of “literate programming” as espoused by Donald Knuth. – Timothy Rice @resnomicon

Tim’s budget is now hosted at notabug.org/cryptarch/budget.git
If you would like to learn more about typesetting your R code in LaTeX, I recommend the tutorial on ShareLaTeX.

bookdown

Finally, we saw another impressive application of R documentation from David, who had created a bookdown project, which was itself an R tutorial!

Several R packages have been developed to take advantage of R’s RMarkdown functionality, and one of those is bookdown. bookdown lets you compile a series of RMarkdown files (with a couple of bookdown specific ones for formatting) into either a traditional book as a pdf or, as in my case, a website. Using materials I had developed for a beginner R workshop as an example, my presentation showed the general structure of a bookdown project, how to compile it into a book/website, and how to make use of GitHub’s gitbook functionality to host my course material online as a website free of charge. bookdown serves as an accessible middle ground between basic RMarkdown documents and full blown LaTeX documents, and with the ability to embed R code it becomes a viable option for writing up your thesis! – David Wilkinson

You can check out the result of David’s hard work online here. The corresponding bookdown project can also be viewed, on GitHub.

This blogpost was created by Meirian Lovelace-Tozer, who is a Research Community Co-ordinator and LaTeX trainer at Research Platforms Services @ResPlat.