2 Starting with RMarkdown

RMarkdown is a frameowork for high quality reproducible documents. In this training we focus on rendering PDF dynamic reports (including both code a narratives), but RMarkdown allows to render into a number of formats, for instance slides, html dynamic reports, dashboards, e-books and blogs. Because it is a markup language, you need to code into your Markdown document how you want to format the content. This cheatsheet includes the commands you need for this training, but you can learn more about authoring documents in RMarkdown from Authoring books with RMarkdown or Reporting with RMarkdown. If you are familiar with \(\LaTeX\), you can also integrate \(\LaTeX\) code in your RMarkdown.

2.1 Creating a new document

Install the RMarkdown package by typing to console install.packages('rmarkdown') or clicking on the install button 2.1:

The intall panel

Figure 2.1: The intall panel

To create a new RMarkdown file (.Rmd) click on File>New File>RMarkdown. This prompts the panel 2.2 to be filled with title, author’s name and format on the final document.

YAML panel

Figure 2.2: YAML panel

We will always use PDF, but you can switch any time to another format when rendering your RMarkdown.

The knit button: Click here to render your document

Figure 2.3: The knit button: Click here to render your document

To render your file you can run \rmarkdown::render("myRMarkdown.Rmd") or click on the Knit button (Figure 2.3). If you look at the Rmd file that you created, you might notice that the parameters that you specify in 2.2 populate the header of your document (what is called the the YAML):

---
title: "My Report"
author: "DDSlab"
date: "5/10/2017"
output: pdf_document
---

You can always change the content of the YAML. For example, changing output: pdf_document to output: word_document renders your RMardown into a Word file when running knitr::render('myreport.Rmd'), which is equivalent to selecting “Knit to Word” when clicking on the button knit.

2.2 Code chunks and narratives

An RMarkdown document has two main type of content: static and dinamic. Static output is the content of your document that you want not to change, such as narratives, figures or formatting attributes. Dynamic output instead comes in handy when you want to tight the output to your data, for instance when rerunning the exact same report on a different dataset. To tell RMarkdown that something should be interpreted as dynamic output (R code for us), you need to wrap your code in a code chunk with a call to the appropriate language engine. You can either click on Insert>R, or use the shortcuts Ctrl+Alt+i on Windows and Ctrl+Alt+i on MacOS. A R chunck will look like the one below:

```{r}
your R script goes here
```

{r} calls the R engine, but you could also call SQL, Python, CSS, JavaScript, etc. engines. To adjust the look of dynamic output, you can use the appropriate parameters in the {r} call. Some of most useful are:

  • echo = FALSE: to show only the output of the code (but hide the code itself)
  • eval = FALSE: to show the code without executing it
  • warning = FALSE: to hide warning messages generated while executing the code
  • message = FALSE: to hide hide other (non warning or error) messages generated while executing the code