At the 2018 RStudio conference in San Diego, my colleague Jon and I gave a talk about how we use R Markdown to quickly go from nothing, to analysis, to a branded report that we can pass off to clients. This workflow took some time to set up, but like most automation tasks, has ultimately saved us more time and headache than it cost. If you want to skip to the talk,
- Here are the slides
- Here is the repo with a short and long version
- Here is a video (complete with my cringeworthy Hadley joke)
- And here is the package we describe
Ten Years Ago
These talks describe our current workflow, but I like to compare the present to the past. I have no way to quantify this, but I feel like R is uniqe in how quickly its packages and IDE have evolved the last few years. I’m sure there are other examples of this, but R must be in the upper quartile of ancillary developments, e.g., the Tidyverse, RStudio v1, Shiny, and our topic, R Markdown. In evolutionary terms, we skipped from Xbox to Xbox One X.
When I began as an analyst in local government, there was no easy way to go from code to output. It was common to create a bunch of graphs with a vanilla R script and then painstakingly add them to either a word document or PowerPoint. There were, of course, those who mastered LaTeX as part a painful dissertation writing process, but most people divided workflows between coding and presentation.
Then came Knitr. Yihui’s work to integrate R with HTML, LaTeX, Markdown and other formats opened up a plethora of possibilities. For instance, I found a way to create a dashboard by knitting analysis into Rhtml. It was difficult to integrate the two, writing <!--rinline I(data) --> everywhere that took a vector. But that simple method has sustained a city dashboard for years now. Without Yihui, I don’t think any of this would have been possible.
Simultaneously, data science was advancing with iPython notebooks. For the first time, the notebook format closely integrated code and output, allowing analysts to see results in-line and easily share their work as HTML files. Modeled after the scientific process, notebooks took off, despite their challenges. When R Markdown Notebooks came along and solved things like version control, it was a monumental improvement.
Branding
Today with RMarkdown in RStudio, it is easy to turn your analysis into a presentation. We use ioslides with a little javascript to brand them. But in San Diego, Yihui said that they are close to adding PowerPoint as an output format.
For reports, we use Word because it is very simple to customize things like headers, fonts, and colors. In the talk we gave, I went over an example of how to use a Word template to include page breaks. This is part of a more general approach to branding that involves iterating on a template until your document looks just right.
Branding a Website
Blogdown is the apotheosis of branding with Rmd. Granted, my site looks similar to the thousands of other websites based on Hugo Academic. But that’s only because it is insanely easy to get started with Blogdown, in general, and the Academic theme in particular. All it takes is this line of code: blogdown::new_site(theme = "gcushen/hugo-academic"). So far, I have not made any changes to CSS - just a replaced a few hero images and icons - and it already feels unique.
There are others who have done a much better job at putting their own mark on Hugo themes. My favorite is Amber Thomas’ site. She is a contributing author to the Blogdown book with a keen eye for design.
Automating
For presentations at work, my colleagues and I fell into a routine. We would copy and paste Rmd documents, adding customizations to the header every time we wanted a new feature. After a while, though, we found that the document headers were growing out of control. There were more than 100 lines that did things like,
- Load libraries
- Set knitr/rmarkdown options
- Set directories
- Define branded color names
- Customize ggplot themes and geoms
- Define custom functions
This made it difficult to create a single report, let alone automate dozens of them.
To remedy the problem, my colleague Jon created an R package with all of our branding and custom functions. This allowed us to take advantage of the draft function and the RStudio features that support document templates.
This video shows how quickly and easily we can create a new report now:
With all of that in place, it is much easier to use a single template to create a series of reports. This for loop is what we used when we were requested to build a unique report showing data trends in every county in Utah.
for (county in unique(utah$County)) {
try(render('./county_report.Rmd',
output_file = paste(county, "County Report.docx"),
output_dir = "./County_Reports/"))
}To summarize, it is easier than ever to brand your analysis with Rmarkdown. Creating a custom package will allow you to cut down on clutter, and make templates easily accessible. From there, it is simple to automate reports that output to Word, Ioslides, HTML, or any of a dozen other formats.