Using parameters in Rmarkdown

Nothing new or original here, just something that I learned about quite recently that may be useful for others.

One of my more “popular” code repositories, judging by Twitter, is – well, Twitter. It mostly contains Rmarkdown reports which summarise meetings and conferences by analysing usage of their associated Twitter hashtags.

The reports follow a common template where the major difference is simply the hashtag. So one way to create these reports is to use the previous one, edit to find/replace the old hashtag with the new one, and save a new file.

That works…but what if we could define the hashtag once, then reuse it programmatically anywhere in the document? Enter Rmarkdown parameters.

Here’s an example .Rmd file. It’s fairly straightforward: just include a params: section in the YAML header at the top and include variables as key-value pairs:

---
params:
  hashtag: "#amca19"
  max_n: 18000
  timezone: "US/Eastern"
title: "Twitter Coverage of `r params$hashtag`"
author: "Neil Saunders"
date: "`r Sys.time()`"
output:
  github_document
---

Then, wherever you want to include the value for the variable named hashtag, simply use params$hashtag, as in the title shown here or in later code chunks.

```{r search-twitter}
tweets <- search_tweets(params$hashtag, params$max_n)
saveRDS(tweets, "tweets.rds")
```

That's it! There may still be some customisation and editing specific to each report, but parameters go a long way to minimising that work.

Moving from RPubs to Github documents

If you still follow my Twitter feed – I pity you, as it’s been rather boring of late. Consisting largely of Github commit messages, many including the words “knit to github document”.

Here’s why. RPubs, an early offering from RStudio, has been a great platform for easy and free publishing of HTML documents generated from RMarkdown and written in RStudio. That said, it’s always been very basic (e.g. no way to organise documents by content, tags). There’s been no real development of the platform for several years and of late, I’ve noticed it’s become less reliable. Bugs, for example, such as one document overwriting another when published from RStudio.

I think it’s unlikely that issues will be addressed, given that RStudio are now focused on RStudio Connect. So I’ve removed as many documents as I can and rewritten them as Github documents. These render as HTML when pushed to Github, generating attractive reports. Here’s an example.

I’ve done my best to update all blog posts here with links to the new reports. If you do come across old broken links to RPubs reports, just remember that the content is probably now at Github.

I’ve left a small number of reports at RPubs for now – those ones are interactive and use Javascript-based libraries such as Highcharter or Leaflet.