Chapter 5 R Markdown in reproducible research

5.1 Five aspects explaining RMarkdown

  1. R Markdown belongs to the field of literate programming which is about weaving text and source code into a single document.
  2. R Markdown is one possible solution (an alternative are Jupyter Notebooks) which allows you to combine text written in Markdown and source code written in R (and other languages).
  3. You can do the entire analysis pipeline in an R Markdown document: Data (pre-)processing, analysis, outputs, visualisation.
  4. This document can be compiled into several output formats, such as PDF and HTML.
  5. Packages such as rticles (Allaire et al. 2018) include templates (e.g. ACM, Elsevier) which can be used to create submission-ready documents.

5.2 Five benefits of R Markdown for your daily scientific work

  1. You can keep an eye on text (the paper) AND the source code. These computational steps are essential to ensure computational reproducibility.
  2. You can easily share R Markdown documents with colleagues, as supplemental material, or as the paper under review. Thanks to the package knitr, others can execute the document with a single click and receive, for example, HTML or PDF renderings.
  3. Figures get automatically updated if you change the underlying parameters in the code. The error-prone task of exporting figures and uploading the right figure version to another platform is thus not needed anymore.
  4. If you do not make any changes to document after creating the output document, you can be sure that the paper was executable at least at the time of submission. Since Markdown is a text-based format, you can also use versioning.
  5. You can refer to the corresponding code lines in the methodology section making it unnecessary to use pseudo code, high-level textual descriptions, or just too many words to describe the computational analysis.

5.3 Creating RMarkdown documents in five easy steps.

5.3.1 Create a new RMarkdown file from template

5.3.2 Fill in the YAML header

You can add several other fields that are essential for typical papers, such as an abstract which gets formatted automatically.

5.3.3 Create code chunks and (scientific) text.

Including code to show how libraries were included is probably not interesting and can be left out.

Instead, it might be more interesting to see where the data comes from and what happened to it.

austria <- getData("GADM", country="Austria", level=2)
austria$randomData <- rnorm(n=nrow(austria), 150, 30)

And of course, how the map was computed. This way of publishing research results allows others to reuse your code and give you appropriate credit. For example, others might be interested in the same way of illustrating their data on the map, but for another region.

m <- leaflet() %>%
  addTiles() %>%  # Add default OpenStreetMap map tiles
  addPolygons(data = austria) %>%
  addMarkers(lng=16.376067, lat=48.207651, popup="Vienna calling")
m  # Print the map