03: Reporting with R Markdown

R Markdown files

An R Markdown file is a plain text file, with some rules and special syntax that allow you to write code and text together. When it is “knitted,” the code will be evaluated and executed and the text formatted so that it creates a reproducible report or document that is nice to read and contains all your work.

This is really critical to reproducibility since it automates the creation of a paper or report, which also has the side effect of saving time. Since the document will recreate the figures and text each time you knit it, you won’t need to copy-paste plots between R and Word, LaTeX or whatever tool you are using to write your report each time you make some trivial change.

Now let’s create a new R Markdown file. In RStudio you can use the menu bar:

A new window will open where you can optionally complete with your name, author and the output format. Let try HTML output first. A new file with a template document will open up when you click OK. This includes a brief demonstration of R Markdown capabilities. You can try to “knit” the file to see the output document.

File structure

Any R Markdown file will have 3 sections or areas:

• The top part is called the header and uses YAML syntax and includes the title and the output type (which in this case is an HTML document) and other metadata.

• Below the heather goes the document proper, which has white and grey sections. These are the two main sections that make up an R Markdown file:

  • Grey sections are code chunks. They will be evaluated in order and any output will be inserted in the output document.

  • White sections are text sections and support markdown for styling.

Header

The header is a series of instructions organized between three dashes (---) that define the global properties of the document, such as the title, the output format, authorship information, etc. You can also change options associated with the output format, such as the style of the table of contents or index. The heather will grow much much larger as you start using templates and customised reports.

The YAML format allows you to define hierarchical lists in a humanly readable way. For example:

---
title: "My first markdown"
output: 
  html_document:
    code_download: true
    toc: true
    toc_float: false
---

Code chunks

The R code is written inside code “chunks”. Code chunks start with ```{r label} (where “label” is an optional and unique name) and end with ```. Everything you include between these delimiters will be interpreted by R as code and will be executed it when the file is knitted. Any output (graphics, tables, text, etc..) will be inserted into the final document in the same order as they are in the R Markdown file (or “roughly in the same order” if you’re knitting to PDF).

While the code will run line by line when you knit the file, during writing it is very convenient to run individual chunks interactively as if it were in the console.

To run the line where your cursor is use the shortcut:

But you can also run the code of the whole chunk with:

By default, the output will appear immediately below the chunk.

Text

The plain text sections of an R Markdown files is interpreted as Markdown. You can get a guide to rmarkdown in this cheat sheet, but here is a minimum syntax to get you started:

• headers start with # or ## and so on (it’s important to put a space after the last #).
• bold text is surrounded with ** or __.
• and italic text, with * or _.

You can also add equations and other symbols with LaTeX in line (`$E = mc^2$` looks like \(E = mc^2\)) or in its own line as:

$$
y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon
$$

It looks like:

$$ y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon $$

temperature <- 18

Chunk control

You may have noticed that code chunks in the template document include some information between the {r }. Besides the chunk name you can also add options to control how the chuck will behave when the file is knitted. Usually the code chunk will be included in the output, which is fine when you or the person that will read the report wants to see the code that generates those results, but it might not be what the final audience of the report might need. It’s up to you to decide if you want to show the code or not.

To change the options of a code chunk, all you have to do is list the options inside the square brackets. For example:

```{r chunk-name, echo = FALSE, message = FALSE}

```

A particularly important set of options are the ones that control whether the code is executed and whether the result of the code will remain in the report or not:

• echo = FALSE runs the code chunk and displays the results, but hides the code in the report. This is useful for writing reports for people who do not need to see the R code that generated the graph or table.

• include = FALSE runs the code but hides both the code and any output. It is useful to use in general configuration chunks where you load libraries.

• eval = FALSE prevents the code chunk from being run at all. Naturally, it will not display results either. It is useful for displaying example code if you are writing, for example, a document to teach R or if you want to suppress specific parts of your code.

If you are writing a report where you don’t want any code to be shown, adding echo = FALSE to each new chunk becomes tedious. The solution is to change the option globally so that it applies to all chunks. This is done by the knitr::opts_chunk$set() function, which sets the global options of the chunks that follow it. You’ll find this function on the first “setup” chunk.

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

Managing references

If you are here to use rmarkdown to write papers or reports, you may need to add references to other papers or sources. Similarly to LaTeX, you’ll need a .bib file with all the references you want to include in the document. While we don’t have time to explore tools to create and manage this type of file, we recommend you to explore Zotero (open source) or Mendeley.

Provided you have the references.bib file in your project, you need to include that in the yaml of the file:

---
title: "My first markdown"
output: 
  pdf_document
bibliography: references.bib
---

Each reference will have a key that defines it. To insert a reference with, use @key, or [@key] or [@key; @key2] to insert them inside parenthesis.

It is also possible to use the LaTeX syntax but we prefer the markdown syntax to be able to knit the report to many type of outputs.

R Markdown Templates

Using rticles

If you have to write a report or document for your institution or maybe a paper for a scientific journal, you may want to use a template to change the look of the final document. Depending on the output format, templates will be different. In this section will focus on PDF files.

For scientific journals you may find the rticles package very useful. This package includes several templates –most of them contributed by the R community– so you can create journal-specific PDFs directly from RMarkdown. We recommend installing the development version from GitHub, which often includes new or updated article formats.

After installing rticles you’ll need to restart RStudio for its templates to be available in the UI.

To use rticles from RStudio, you can access the templates through File -> New File -> R Markdown. This will open the dialogue box where you can select from one of the available templates:

This will create a folder containing a Rmd file using the corresponding output format and all the assets required by it.

Beyond the usual templates

Now, what happens if rticles doesn’t have the template you need? Usually, journals provide LaTeX templates that you can use and adapt to use within R Markdown. This will require some knowledge of LaTeX and Pandoc templates, and some patience and coffee/tea/mate to deal with knitr errors. If you go through the trouble of adapting a template, consider contributing it to rticles so that others can benefit from your sweat and tears.

Resources

R Markdown cheatsheet

R Markdown: The Definitive Guide

rticles package documentation