Chapter 10 R Markdown

In this last part we will learn one of the most nifty features of R, which is being able to create whole documents from the comfort of your R Studio. Because creating visualizations and statistics in R is great, but we need to able to show and report our work. Of course, results can be copied and plots can be exported, but the more steps one needs to take, the more prone to error the work becomes. When you write a report with this feature, analyses and plots can be embedded directly into the document. Basically, R Markdown is a text engine based on LaTeX that allows you to create documents, presentations, reports and much more. As I mentioned before, it can be used to write whole theses - an example of which you can see in the screenshot Figure 10.1 below!

Example Screenshot of a Thesis written in R Markdown.

Figure 10.1: Example Screenshot of a Thesis written in R Markdown.

There are many possibilities and luckily, there are also usually templates and guidelines to go along with them. For your first R Markdown document, you can create a demo Rmd with the "New File" menu as shown, or go to File > New File > R Markdown to create a new Rmd document. Give it a name or keep all the defaults for now. It will create a document with some demo content. When you click the "knit"-button below the main menu, you will need to save the file and it will create the output. Try to play around with the text and read the demo content - it explains the basic functions! You can use the document you create now as a sort of cheatsheet and template for what you can do later.

RMarkdown has some basics that need to be learned and might take some getting used to. It also has many features and powerful tools for layout and styling, so spending the time it takes to learn is a good investment. By default, RMarkdown can create HTML13 documents. Don't worry if that sounds like more programming to you - while it is possible to use special HTML tags in R Markdown, it is by no means necessary.

You can also create other types of documents, such as a pdf for which you need a special package to render . The most efficient is usually tinytex, which first needs to be installed as the package itself and afterwards it can run its own installation of everything you need for your reporting:

install.packages("tinytex")
tinytex::install_tinytex()

10.1 YAML header (Yet Another Markdown Language)

Apart from the document processors that are necessary, R Markdown files also follow a specific structure in order to be recognized as the right type of file. Every R Markdown document starts with the so-called YAML header, which stands for Yet Another Markdown Language. This defines most of the "hard facts" concerning our document, such the output format, e.g. html_document, title, subtitle, author, date... We can also define further characteristics, e.g. toc (table of content) or self-contained (this should be set to true, otherwise R will not copy images etc. and the document will not work properly on other devices).

The YAML header needs to be indented in a certain way, otheriwse the commands are not recognized! 

---
title: "My Title"
subtitle: |
    | A Super, Very,
    | Insanely Long
    | Awesome Subtitle
    | In Four Lines
author: "A Great Author"
date: "`r Sys.Date()`"
output: 
  pdf_document:
    toc: true
    self-containted: true
---

# First Chapter

Start text after a blank line!

As you can see above, the YAML header is surrounded by three minus signs --- and has quite specific formatting. Setting values like title and author are similar to assigning strings to variables - they have to be put in quotes. One exception to this rule can be seen in the subtitle, which starts with a vertical rule | - if that is the case, you can define very long text without the quotes and even control the exact format and line break. Another nifty feature is being able to use inline R Code, to e.g. insert today's date automatically with ` Sys.Date()`.

For the output, it is important to stick with this type of indentation, where every setting belonging to the document command is indented further than the document definition.

In the YAML header, true and false are not capitalized, unlike in the rest of R!

For different types of output there are some different features that may be stylish or useful. For example, in HTML you can format the table of contents to float with toc_float: true. In a pdf document, this option would not make sense so it will not work.

10.2 Markdown Basics

When you have defined the document basics to your liking, it is time to get started on the actual text. While other text processors offer buttons for text formatting, R Markdown requires this formatting to be included in the text. Think of Markdown as the back-end of your document and the output as the front-end!

Here is an overview of the most important formatting features:

  • italics with _italics_
  • bold with **bold**
  • bold and cursive with **_bold and cursive_**
  • Unordered lists are created with -
  • Ordered lists with 1., 2. ...

To structure your text, you can set headings with the # pound sign. The more pound signs, the smaller the heading (sub-levels).

# First Heading
## Sub Header 2. level
### Sub Header 3. level
#### 4th level
##### 5th level
###### 6th level

Realistically, we may want to go down to the 4th level heading, but usually no further.

Tables

To create tables, we also need to specify rows and columns with symbols right in the text. Anything above the line of minus signs is identified as the header and anything below as the table content. This is a fairly simple way to create automatically formatted, clean tables.

Header 1 | Header 2
-----|-----
Great content | Fantastic content

Becomes:

Header 1 Header 2
Great content Fantastic content

It is also possible to use inline Code to report statistics, although it may be more efficient for reporting to create tables with kable, which you can read more about here.

10.3 Special Features

  • Print mathematical equations
  • Show code and its output
  • Easily use automatic formatting
  • Profit from existing templates
  • General rule of thumb: Rmd documents are rendered depending on their output format
    • If you plan on creating an html, you can use plain html to make adjustments and use special features.
    • If you create a pdf, they will most likely not work and you should use notation.

10.3.1

Especially useful for writing equations:

  • $ \ alpha $ \(\rightarrow\) \(\alpha\)
  • $ \ beta $ \(\rightarrow\) \(\beta\)
  • $ R^2 $ \(\rightarrow\) \(R^2\)
  • and, by the way, $ \ rightarrow $ becomes \(\rightarrow\)
  • and $ \ LaTeX $ becomes
  • \ newline creates a new line and \ newpage creates a new page

10.3.2 HTML

Remember these tags should only be used when creating a html document!

  • < br > creates a new line (stands for "line break")
  • <span style="color: purple;"> This text will appear purple. </span>
    • This text will appear purple.
  • Simple tables can be created with html notation in most documents
    • Header 1 | Header 2
    • then a row of - - - | - - - to represent the lines
    • And the content separated | into as many columns as defined

10.4 Including R

  • Including R code can be achieved by either inserting so-called code chunks or using inline code
  • Code chunks are useful if several lines of code need to be evaluated and/ or shown
    • There are many options for code chunks
  • Inline code is useful if single outputs are to be shown
    • E.g. with functions you already know such as apa_print()

10.4.1 Code Chunks

  • Code chunks are inserted via the menu Code > Insert Chunk and should look like this:
  • ```{r}
    # code goes here
    ```
  • # code goes here
  • Or you can use the keyboard shortcut ctrl + alt + i / command + option + i

Chunk Options

  • Inside the curly brackets, you can specify many different options, for example:

    • fig.height = 3 will output a plot to a certain height (3 inches)
    • echo = F will show code output, but not the code
    • eval = F will show the code, but not its' output...

  • eval = F:

    head(iris, 1)

  • echo = F:

    #   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
# 1          5.1         3.5          1.4         0.2  setosa
error = TRUE
  • This option allows us to include erroneous code in our script
  • It will output the error message just like you would see in your R Studio console
  • By default, error = FALSE which means that your script cannot be rendered with errors in code chunks
mean(y)
# [1] 5.5

10.4.3 Inline Code

  • To simply include variables or values in text, we can use inline code `r code `
  • Simply type one back tick ` and r - the program will auto complete the command
  • Examples:
    • The average sepal length of iris flowers is
      `r mean(iris$Sepal.Length)` \(\rightarrow\) 5.843

Wrap-Up & Further Resources

  • RMarkdown allows you to create professional documents
  • You can use it like other text-generating programs (e.g. MS Word)
  • Embed plots, code and statistical results directly in your document
  • Show equations and use other special features


Shakespeare writing RMarkdown (AI generated using the bing image creator)
Shakespeare writing RMarkdown (AI generated using the bing image creator)

  1. HTML is used in most if not all websites and stands for hypertext markup language.↩︎