Convince me to start using R Markdown

Publishing Your Results
7

This question actually sparked me to create an account here just so I could answer it! I am a professor and researcher, and R Markdown has totally changed the way I work. So here is my pitch.

For research projects, I use R Markdown documents versus R scripts for different purposes. I will typically use R scripts to do things like importing the data, cleaning up variables, typecasting variables, doing any tidying, etc. I have separate scripts for each tasks, named:

  1. 01-import

  2. 02-clean-names

  3. 03-tidy, etc.

These scripts are short and focused, and named according to the specific thing they do so that I can trouble-shoot more easily when something goes wrong (if you use R Markdown for this, your file could not knit, and it can sometimes take awhile to figure out what went wrong if you have tons of lines of code all in one long file).

Sometimes these scripts include plots so I can refine my code when I am actively working on the script, but typically once I get the code how I want it, the plots are not useful so they don't tend to appear in these R scripts (I use the RStudio IDE during my interactive work sessions).

Then for my analyses and visualizations, I switch to R Markdown. In that file, I call my R scripts for processing/cleaning/tidying at the top in a chunk that looks like this:

{r load_scripts, include = FALSE}
source('./scripts/01-import.R')
source('./scripts/02-clean-names.R')
source('./scripts/03-tidy.R')

These scripts typically have some comments in the code using # this is the problem this next chunk of code addresses, but these scripts don't need any narrative to be useful- they just need to work so I can move on.

Next, I make R Markdown documents. Some are primarily visualizations and results of analyses where all code chunks are hidden using global chunk options at the top of the Rmd file (because my collaborators don't know R and will be confused when they see code) like this:

{r setup, include=FALSE}
knitr::opts_chunk$set(echo = FALSE)

These docs typically use knitr::kable to create nicely formatted tables of output, and include lots of ggplot2 plots.

By only changing the above global chunk option to TRUE, I then have a complete printout of all my analyses and results, including the R code used to produce each analysis/plot, and the complete output. This is good for my collaborators that know R and can parse the code. The great thing is I don't have to create a different R Markdown files for each audience! Because I can annotate and include more narrative in the R Markdown files, I include explaining/teaching/discussion-provoking thoughts in those documents in between the R chunks.

For teaching statistics, I ask students to submit R Markdown files and a knitted version with echo = TRUE as a global option. This has made grading assignments so much easier, and the students can work in one document to analyze AND interpret data (rather than working in R console, and copying/pasting R code and output into a text editor or Word document, then adding narrative).

47 Likes