Top 3 Ways To Make Your RMarkdown Better (Part 1)

Source

Last month I talked about the multiple ways of sharing RMarkdown analyses with your target audience. When you’re sharing your RMarkdown analysis, the most important aspect is the content itself, but formatting and aesthetic of the analysis is not far behind.

In this article, I am going to show you three simple things that can turn your analysis from a bland, flat file into a well organized, interactive document that people will want to read.

1. YAML Settings

The YAML section in an RMarkdown file is the very first section of code you see:

---
title: "Analysis"
output: html_document
---

The above YAML is at the most basic level, which just lists the title of the document (this shows up at the top when knitting/rendering), and then the output format. However, there are a huge amount of options that the YAML can take to help customize your document. Some of the ones I find most useful are using built-in themes, creating a table of contents and controlling code folding.

Built-in Themes

Using built-in themes is the easiest way to completely change the look of your entire document. This controls accent colors, font, and more.

---
title: "Analysis"
output:
  html_document:
    theme: yeti
---

The following themes are available: default, cerulean, journal, flatly, darkly, readable, spacelab, united, cosmo, lumen, paper, sandstone, simplex, and yeti.

Table of Contents

Another very useful option that can be added to the YAML is to include a table of contents. The code looks like this:

---
title: "Analysis"
output:
  html_document:
    theme: yeti
    toc: TRUE
    toc_float: TRUE
---

This creates a table of contents on the right side of the document which lets you click on any section of the document to skip through. I particularly like using the float option as this makes the table of contents cleaner by only showing you the current section, but letting you scroll through the other sections. The sections are created by using different level headers ( # vs. ##, vs. ###…etc.)

Code Folding

Code folding is another useful feature in case you want some of your target audience to be able to view the code which generated your analysis. The YAML option creates a clickable button at the beginning of the document to either show or hide all of the code:

---
title: "Analysis"
output:
  html_document:
    theme: yeti
    toc: TRUE
    toc_float: TRUE
    code_folding: hide
---

2. Tabset

Often, in your analysis you will be creating multiple variants of plots, tables or other items used for comparison. These can quickly cause clutter, and make the document a lot longer than it needs to be.

Something that has completely changed my analyses is adding a tabset option for document sections which I want to collapse into a set of tabs. To make it work, create a header (let’s use a level 2 header for example). Under that header, create a few sub-headers (these are the items that will be collapsed into tabs).

## Demographics {.tabset}
### Plot 1
"Insert Plot 1 here"
### Plot 2
"Insert Plot 2 here"
### Plot 3
"Insert Plot here"

The results look like this:

3. Plotly

Plotly is an interactive graphing library that allows for creating some really impressive interactive visuals. In order to get the best results, I would recommend using the syntax specific to Plotly. However, the Plotly package contains a ggplotly function which can take a ggplot object and make it interactive. While there are occasional bugs with this method, the ease of not needing to learn new syntax makes it worth it for many situations.

Here’s an example plot using just ggplot2 :

Now here is an example of the exact same plot, but wrapping it in a ggplotly function. I can hover my mouse over each individual point, and get the data associated with it. It also has a capability for zooming in closer to a set of points by just drawing a shape around the points you want to investigate.

There are also some arguments that can be tweaked inside the ggplotly function. The documentation can be found here.

These few examples will take your RMarkdown reports to the next level, but stay tuned for some more advanced techniques coming soon!