Chapter 10 R Markdown

R Markdown allows you to combine R code, analytical and graphical results, and text narrative into a single document. Instead of copying your R results into Word, think of this as moving your Word writing into R. You can use it to generate nicely formatted HTML (webpage), Microsoft Word, and PDF documents that can be shared with team members and other collaborators. If you update your analysis, you can create an updated output file with the click of a button. With a little work, R Markdown keeps you from having to copy and paste results from R into a Word doc, keeping both in step with each other and saving you from having to keep track of updates.

As you might expect, R Markdown has become a very popular and powerful integration into the R and R Studio universe. It does have its own syntax and quirks, though, so this chapter is designed to help you get through those.

NOTE: If your instructor is not requiring you use to R Markdown, you should be able to skip this chapter. However, if you think you might be taking more advanced statistics courses - or just want a cool skill to talk about at parties - learning R Markdown is far easier than learning R itself and definitely worth the time.

How R Markdown Works

R Markdown files are text files that can be opened and edited in R Studio the same way an R script file can, though R Markdown files have the extension Rmd10. They are an extension of the Markdown language for formatting documents, built to incorporate R code and results into the document. Combining R code, results, and text into a single file essentially creates a complete report of a data analysis in one place. If you need to adjust code, or if new data comes in, you can re-run the code and update the entire report in real time. This makes R Markdown an extremely powerful tool for modern statisticians and data analysts.

In order to create the output file, you need to “knit” your Rmd file. There is a button to do this in R Studio (the Knit button, with a picture of a ball of yarn, is near the Save, Spell check, and Search buttons), so it seems like a relatively easy process. However, there are many steps under the hood. First, the Rmd file needs to be parsed to ensure all the syntax is understandable and the R code works. Then the file is processed by a program called pandoc which will write the output file, assuming you have the correct software. For example, if you want to create a Word file, you need Word on your computer. If you want to create a PDF file, you need a TeX editor on your computer11.

Writing an R Markdown file

Formatting Text

One you are past the header, you are into the body of the document. Markdown was designed to be an easy to use and read formatting system. That means it is kind of limited in what it can do, but it can be learned pretty quickly. The main special code parts you need to know are:

  • Sections: Start a line with a hashtag # followed by a space then the section name.
  • Subsections: Start a line with two hashtags ## followed by a space and the subsection name.
  • Paragraphs: Leave a blank line between paragraphs.
  • Bulleted list: Leave a blank line before starting the list, then start each line with a dash - followed by a space and the content of the point. Start a new point on a new line with a new dash. Leave a blank line after the list.
  • Ordered list: Similar to above, but start lines with numbers or letters followed by a period instead of a dash. For example, 1., 2., 3., etc. or A., B., C., etc.
  • Italic text: If you want text to look italic when knitted, surround it with asterisks like *italic text here*.
  • Bold text: If you want text to look bold, surround it with two asterisks **bold text here**.

An example using some of this formatting is below:

# Problem 1

## Part a

1. My name is **Travis**
2. I study *statistics*

## Part b

This is the first paragraph of this part.

This is the second paragraph.

These few bits of code formatting should be able to get 90% of what you need for your classes. If you need more, there are plenty of cheat sheets and cookbooks you can find online.

Including R Code

The biggest benefits of R Markdown come from mixing your R code with the text explaining the code and results all in one document. To include R code, you need to create a code chunk. There are couple ways to do this. The first is to code the chunk directly. First, leave a blank line after your paragraph of text. Then begin the chunk with a line of three back-ticks and {r} and end the chunk with a line of three back-ticks.

The lines inside the code chunk are treated as R code and evaluated line by line. Additionally, you can use the code chunk button in R Studio (a white C in a green box) and select R. Doing this will place the starting and ending lines for the code chunk in your document for you.

You can have as many code chunks in your document as you want, and they can be as long as you want them to be. The code will be run continuously from the first line of the first chunk to the last line of the last chunk, so values and objects that you save in earlier chunks can be referenced and used in later chunks, but not vice versa. Any output generated from the R code will appear directly below the line of code that created it.

Knitting an R Markdown file

When you click the Knit button in R Studio, you are starting a very complex process that is supposed to be mostly hidden from you. The Markdown syntax is read and formatted while the R code is evaluated and output is generated.

There are a growing list of output formats, but the standard ones are HTML, Microsoft Word, and PDF. You can see the output type in the header line that starts output:, which will be followed by html_document, word_document, or pdf_document, respectively, for the three formats. You can change the output format by editing the header directly or by clicking on the small down arrow next to the Knit button and choosing your format. If you have knitted your Rmd file to mutliple formats, the header will look like:

output:
  html_document
  word_document
  pdf_document

and when you click Knit, you will get the first output format on the list.

IMPORTANT: When you knit an Rmd file, you need to ensure that all the code you need for your analysis is in the Rmd file itself. That means any packages you need to load or data you need to read in are explicit in the code chunks of your Rmd file. When you knit a file, a new R session opens in the background of your R Studio program. This session is blank before it runs through your code. If you don’t read in data within the Rmd file itself, it won’t be read in when the code is evaluated during the knit. This is true even if the data already exists in the evironment in your visible R Studio session. The point is that the file should be able to be run from any computer without any additional work, so it needs to be entirely self-contained.

If the knitting works, the output file will appear in the same directory as your Rmd file with the same file name, distinguished only by the file extension (.html, .docx, or .pdf). If you get an error knitting (which will be very common early on, hopefully getting less common as you get more familiar), you will need to address the issue and try to knit again. Some common R and R Markdown error messages and their solutions are described in the next chapter.

  1. From here on, I will use “Rmd” when describing an R Markdown file and “R Markdown” when describing the R Markdown language↩︎

  2. You can install the R package tinytex for this purpose, allowing you to run everything through R without having to learn an entirely new computer language.↩︎

  3. The Rmd header uses YAML, which stands for YAML Ain’t Markup Language. If you search for information about Rmd files, you’re likely to come across the acronym YAML, which essentially means the header. I had to lookup what YAML meant to write this - I had never seen it before.↩︎