Introduction to RMarkdown

Rstudio is for more than just data analysis and plotting. You can use it to write entire reports, create lecture/conference slides, or even make websites (like this one!). You can do this my writing in a markup language called Markdown. If you’re familiar with html or LaTeX, then these are both markup. Markdown was design as a lightweight alternative to html. But RStudio has built in a couple of extra tools that make RStudio’s flavour of Markdown (called RMarkdown) a lightweight alternative to LaTeX

Basic Markdown

Being a markup language, RMarkdown requires you to mark your plain text to indicate formatting. The most straight examples of text formatting are bold and italics. To make bold and italics you simple surround your text with *. One * on either side for italics or two for bold.

For example:

• *italics* would render as italics

• and **bold** would render as bold

The next most import thing are headings. To make headings we just use #s to indicate the level of the heading.

For example:

• # Level 1 would render as a level 1 heading

• ## Subheading would render a a level 2 heading

And finally, the final building block of basic Markdown is the list. To make a list you just you just use - before items for an numbered list or numbers like 1. or a numbered list.

For example:

This is a numbered list

1. Item 1
2. Item 2

This is a unnumbered list

- Item 1
- Item 2

Before we start writing Markdown in R we can use the box below to try out some of these examples.

More advanced typesetting is also possible in RMarkdown. For example, RMarkdown also provides support for full LaTeX style equations. For example:

$$p(Y) = \int_\Theta p(Y|\theta)p(\theta)d(\theta)$$

Would render as:

\[p(Y) = \int_\Theta p(Y|\theta)p(\theta)d(\theta)\]

Writing Markdown in R

Now that we have the basics under our belt we can create our first RMarkdown document. To create an Rmarkdown document go to the File > New File > R Markdown to open up a new RMarkdown document.

You’ll first be shown a dialog box like the one below:

You don’t have to fill in any information for now, because we can change that after the document has been created.

Our new document fill already be filled will the text below:

---
title: "Untitled"
output: html_document
---

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

## R Markdown

This is an R Markdown document. Markdown is a simple formatting syntax   
for authoring HTML, PDF, and MS Word documents. For more details on   
using R Markdown see .  

When you click the **Knit** button a document will be generated that includes  
both content as well as the output of any embedded R code chunks within the  
document. You can embed an R code chunk like this:  


```{r cars}  
summary(cars)  
```  

## Including Plots  

You can also embed plots, for example:  

```{r pressure, echo=FALSE}  
plot(pressure)  
```    
Note that the `echo = FALSE` parameter was added to the code chunk to  
prevent printing of the R code that generated the plot.  

Parts of a RMarkdown file

Our new RMarkdown file is made up of several parts. The first is the header:

---
title: "Untitled"
output: html_document
---

This is just the document’s meta-data. It’s tells us the documents title (Untitled) and what kind of document our end result will be (html_document). In addition to html documents, it’s possible to produce pdfs (pdf_document) and word documents (word_document)

You should be able to spot two level 2 headings. One of the them reading ## R Markdown and the other reading ## Including Plot.

Finally, you’ll see little sections that look like R code:

```{r cars}  
summary(cars)  
```  

These sections are called Code Chunks, and these bits of code will actually run when you render or knit our file.

Rendering our file

To knit our document, we just clik on the little icon that looks like a ball of wool

Let’s go a head and click and see what happens!

You should end up with an html file that looks like the one below.

You’ll notice that where your .Rmd previously had R code, it now has the output from that code, including some summary statistics and a plot.

Working with Code chunks

The parts of .Rmd file that contain R code are called code chunks. You might notice that in your RStudio editor these chunks may appear highlighted in a slightly different colour. Any code that is written into these chunks will automatically be run and included (together with any output) in the final document. To create a new code chunk using the menu go to Code > Insert Chunk. However, it’s just a easy to type it. You basic code chunk is just written as follows:

Copy markdown

```{r}
 
```

Let’s pick somewhere near the end of our document and insert a new code chunk. Once you’ve interested your chunk, you’re notice a little gear icon and a green triangle

The green arrow runs any code that is in the code chunk, while the gear icon allows us to set some options for the code chunks.

When you click on the gear, a menu will pop up that will allow you set some options. The first option, is the label or Chunk Name. If we type in a label (for example, our first code chunk), you notice that text appears in your code chunk header. The next options to set are labelled Output. The Output options determine what is included in our final document.

The output menu has the following options:

1. Show output only: Selecting this will add echo=FALSE to ou code chunk heading. This option means that only the output from the code will be included in the final output, but the code inside the code chunk won’t be.

2. Show output and code: Selecting this will add echo=TRUE to our code chunk heading. This option means that the output from the code chunk and the actual R code itself will be included.

3. Show nothing (run code): Selecting this will add include=FALSE to our code chunk heading. This option means that the output from the code, and the code itself, won’t be included in the final document, but the code will still get run. If the code in this chunk, for example, produces or modifies a variable, then that variable will be accessible in later chunks.

4. Show nothing (don’t run code): Selecting this will add eval=FALSE, include=FALSE to the code chunk heading. This option means that the code itself won’t be including in the final document, and the code won’t be executed (so there won’t be any output). This means that if, for example, the code in this chunk was to create a variable, then because the code won’t actually be run, the variable will never be created.

The setup chunk

The code chunk at the start of the document labelled setup is a special code chunk. Not only is it the first code chunk that is run when we knit the document, but it also gets run whenever we manually run one of the other code chunks in our document. Because of these features of the setup chunk, it’s the ideal place to load any packages that we might be using. Another feature of the setup chunk, is that if we used the chunk options menu to set options for that the setup chunk (e.g., setting include=FALSE etc), then those options will be set as default options for all the code chunks in our document.

Let’s go ahead and load the packages we’ll need by adding the following code to the end of the setup chunk.

Copy code

xfun::pkg_attach2("teachingtools","afex","apa","knitr","tidyverse")

Adding an analysis chunk

Now that we’ve got our packages loaded in the setup, let’s clear the rest of the document, and add a code chunk from our ANOVA session.

Copy markdown

```{r}
aov_factorial <- afex::aov_ez(id = "id", 
             dv = "anxiety",  
             between = c("group","gender"),
             data = aov_data_factorial)
```

We can now click on the little green arrow to run this chunk. We should see that our setup chunk will first run, loading the appropriate packages, and then we should see the model object aov_factorial appear in our Environment pane.

Instead of manually running each chunk, we’ll now Knit the document. We’ll seen output of an almost empty html page expect for our code above. We can make this look neater by including include=FALSE to the heading of this code chunk. When we re-Knit the document, we’ll see that we now don’t see anything. However, our document is producing a model object named aov_factorial.

Working with code and text

Now that we have some code in our .Rmd file, we’ll add some text. We’ll just add a level 2 heading for Results.

Copy markdown

## Results

In our results section, we’ll probably want to include a couple of things. First, we might want a table of the ANOVA results. And second, we might want a plot of our ANOVA results.

To include a table, we’ll use the function knitr::kable() from the knitr. R has lots of packages for making tables in RMarkdown, but the kable() function is pretty straightforward to use. kable() will turn anything tabular (like a data frame) into a table. And it’ll turn our aov_factorial object into a table too. However, before we can do that, we first have to make it nice. To do this, we’ll use the afex::nice() function. To make our table, let’s add a new code chunk, and start filling it with code. The first thing we’ll do is to wrap our aov_factorial is the nice() function.

Copy markdown

```{r}
afex::nice(aov_factorial)
```

Next, we’ll just %>% that into knitr::kable(). So our final code should look like the following:

Copy code

afex::nice(aov_factorial) %>% knitr::kable(x = .)

We can know go ahead and knit our document. When we look at our knitted document, we’ll now see an ANOVA table. We’ll also see the code used for creating the table. We can get rid of the code, and keep the table, by adding echo=FALSE to the heading of our code chunk.

The kable() function has a few options that are worth setting. The first is the caption argument that sets the table caption. There’s also an argument called digits which will format the numbers in the table so that they’re, for example, all rounded to 2 dp. For our table, all the number formatting has already been taken care of by the nice() function, so we’ll just set the caption.

Copy code

afex::nice(aov_factorial) %>% 
  knitr::kable(x = ., caption = "ANOVA Table")

Working with code and plots

The next thing we’ll want to do is include a plot. We could generate a plot using ggplot2, but we’ll save ourselves time and make one with afex::afex_plot().

To include a plot, we’ll just create another code chunk and fill it with some plotting code.

Copy code

afex::afex_plot(aov_factorial, x = "group", panel = "gender")

If we were to knit our document again, we’d see that it no contained a plot. But we before we do that, we’ll add a figure caption. To do this, we’ll use the fig.cap argument in the header of the code chunk. In full, the code chunk would look as follows:

Copy markdown

```{r echo=FALSE, fig.cap="Our ANOVA plot"}
afex::afex_plot(aov_factorial, x = "group", panel = "gender")
```

Embedding output in text

The last thing we’ll cover are what’s know as inline code. We saw that we could fence off sections of code into code chunks as follows:

```{r}
 
```

Code inside code chunks runs, and depending of the settings of your code chunk it might even produce an output like a table or a plot. There are however some situations were we’ll actually want to mixed words we’ve written with output from R. The most obvious situation you’d do this, is in situations like reporting statistical tests. For example, you might have some t-test or an ANOVA that you’ve conducted and you might want to report it as follows:

The interaction between group and gender was not significant, F(2, 54) = 0.69, p = .504, \(\\\eta^2_p\) = .03.

That statistical result, is already stored in our ANOVA object aov_factorial. We just need to extract, and format it and insert it into our test. To do this, we’ll use a package called apa. How apa works is that it takes in objects created by our statistical tests we’ve run in R and it formats the output into APA format. To see how this works, we’ll first just fee it the aov_factorial object we’ve created. We’ll feed it to the apa::apa() function. To test it out we just run run the following code in our console:

Copy code

apa::apa(aov_factorial)

# A tibble: 4 x 2
  effect       text                                                 
  <chr>        <chr>                                                
1 (Intercept)  "*F*(1, 54) = 1306.48, *p* < .001, $\\eta^2_p$ = .96"
2 group        "*F*(2, 54) = 134.66, *p* < .001, $\\eta^2_p$ = .83" 
3 gender       "*F*(1, 54) = 0.21, *p* = .648, $\\eta^2_p$ < .01"   
4 group:gender "*F*(2, 54) = 0.69, *p* = .504, $\\eta^2_p$ = .03"   

You’ll see the output is no longer a table, but some APA formatted results. You’ll also see that we have the results for all the effect. Let’s say we just want the interaction. To do this, we’ll just use the effect argument.

Copy code

apa::apa(aov_factorial,
               effect = "group:gender")

[1] "*F*(2, 54) = 0.69, *p* = .504, $\\eta^2_p$ = .03"

But we don’t want that output print to the console. We want to mix that in with our text. An in line code chunk allows us to do it. To create an inline code chunk, we just fence our code off with a `r at the start and a ` at the end. Like so:

`r apa::apa(aov_factorial, effect = "group:gender")`

When you knit the document, this inline code chunk will just be replaced with whatever the code outputs. So, for example, the following text:

Copy markdown

The interaction was not significant, `r apa::apa(aov_factorial, effect = "group:gender")`.

Would appear as follows:

The interaction was not significant, F(2, 54) = 0.69, p = .504, \(\eta^2_p\) = .03.

No more having to copy down numbers at the inevitable errors that occur!

The apa does more than just ANOVAs. It can also handle t-tests and regressions. And infact, you don’t need to rely on the apa, but you can write a function to handle any kind of statistical test you want. As long as the function produces some output text, then that text will appear in your final document.

Referencing and bibliographies

It’s also possible to use RMarkdown (or, more specifically, Pandoc, the program that powers a lot of RMarkdown) to include citations and reference lists in our documents. To do this, we just need to include a reference to our bibliography file in the header of our file. For example:

---
title: "Sample Document"
output: html_document
bibliography: bibliography.json
csl: apa.csl
---

RMarkdown is able to accept bibliography files generated by many popular reference managers including endnote, zotero, or any reference manager that allows you to export your bibliography to a .bib BibTex/BibLaTeX file (which is essentially all of them).

In addition, you can include a reference to a .csl citation style file, which determines the style of the final citations.

Once set up, yo actually include a citation in your document you just use pandoc-sytle citations using the reference identifier in your reference manager (this is called the citation key in, for example, Zotero). For example, if you have a paper in your reference manager by Smith et al, with the citation key Smith1990, then you would simply cite is as @Smith1990, to in text style references, or as [@Smith1990], for parenthetical references¹.

There’s a lot more information about RMarkdown on the RStudio website, including information specifically about bibliographies and references.

---

1. Note that this referencing style, or even writing in markdown, is not specific to R, and it’s part of the wider movement of plain text academic writing which brings the philosophies of open source and open standards to the process of actually writing papers. A core of this movement is the idea that using open tools, and rejecting closed, propriety software like Microsoft Word, not only results in a better writing experience, but also makes science more open, fair, and accessible. You can check out more on plain-text.co for more info.↩︎

CC-BY-NC-SA-4.0 ♥ Lincoln J Colling