Compiling RMarkdown Documents

What does it mean to “compile” a document?

Rendering (from https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf)

Figure 1: Rendering (from https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf)

Often, when talking about “compiling” RMarkdown documents, you will find different words used for this process, such as “compiling”, “rendering”, and “knitting”.

The basic idea is that we are turning the .rmd file we are editing in RStudio into something much more reader-friendly, such as a .pdf, or an .html, or even a word file .docx.

If you open up the .rmd file from Lesson 1, and click the “knit” icon at the top of the document, you see lots of stuff happening below, and then a nicely formatted document will pop-up. (Note: If you have not already saved your RMarkdown document (hopefully you have!), then when you click “knit”, it will prompt you to save it first.)

Compiling a document

You may find that the document pops up in a separate window, or in the “viewer” pane in the bottom right of RStudio.
You can control this behaviour by looking in the top menu of RStudio for “Tools” > “Global Options” > “RMarkdown” > “Show output preview in:”.

Compiled Files

The compiled file will be in the same folder as where you have saved your .rmd file. If you are using an “Project”, or have set your working directory using setwd() (see r-bootcamp Lesson 2) then you can fine these easily in the Files tab of RStudio. You can also find these in your file-browser that you use to find all your other files on your computer.

Locating .rmd and compiled document when using a Project

You should now have TWO files on your computer with the same name but one is an .Rmd and one is a .html. You could email the .html file to someone and they could open it in their web browser. The .Rmd file can only be opened and understood by someone who has access to R.

Compiling and Sessions/Environments

When an RMarkdown document gets compiled, it does so as a self-contained process. This ensures reproducibility!

It doesn’t matter what you can see in your Environment, nor what packages you have loaded.
What matters is what is in the RMarkdown document.

When you click “knit”, the lines of code in your RMarkdown document will be evaluated one-by-one, and the document must contain everything required to evaluate each line.

For example:

Where is the RMarkdown looking for objects/functions, if not your environment? It’s looking in its own environment!

Demonstration of compiling without defining objects

The “setup” chunk

Because compiling an RMarkdown document requires everything necessary for all the code to run without errors to be included in the document and in the correct order, there is an optimum way to structure your document.
Immediately after the metadata (title, author etc), we specify the “setup” chunk (see below). In the setup chunk, we typically load all the packages we rely on in the rest of the document, so that they get loaded first.1 It is also typical to use this chunk to read in your data.
You can see an example below.

---
title: "this is my title"
author: "I am the author"
date: "13/08/2021"
output: html_document
---

```{r setup, include = FALSE}

library(tidyverse)
library(palmerpenguins)
somedata <- read_csv("https://edin.ac/2wJgYwL")
```
Note we now have some more stuff inside the brackets which start our code-chunk.
Instead of
```{r}
we now have
```{r setup, include = FALSE}
The first bit, setup is simply the name of our code-chunk. We can call it anything we want, for instance:
```{r peppapig}

The second bit, the include = FALSE is what is known as a “chunk-option”, and we will get to these later on. What this does is basically mean that neither this chunk of code nor its output will be visible in the compiled document.

  1. Don’t use install.packages() here - or it will re-install the package every time you compile. Just use install.packages() in the console.↩︎