Last week, we quickly checked whether R Markdown would work on your computer (e.g., whether you could compile that R Markdown document). This week, you are going to be creating your own R Markdown files, and learning about the Markdown syntax. This tutorial is inspired by much work done by others.

1 Make your own R Markdown file

Begin by creating a new directory for this lab on your Datastore drive (e.g., Documents>ResearchMethods>Lab2). Open RStudio. Let’s now create a Markdown file. Click on the File menu, New File, R Markdown.

Create a new document

Create a new document

Give your new document a Title, and fill in your name for the Author. You can see that there are lots of different options for creating different Markdown documents. You can make a pdf, a Word doc, a presentation, etc. But we’ll just make an HTML file for now. Press Ok to create the new file, and then press the Knit button at the top of your screen; this will prompt you to save your R Markdown document in the appropriate directory, and then your R Markdown document should compile as a web page.

R Markdown vs R Notebooks. When creating your R Markdown file, you may also have seen the option to create an R Notebook file. Markdown documents and Notebook documents are more or less the same thing, and you don’t need to worry about the difference right now (people use the two names more-or-less interchangeably). For those truly interested, Markdown is a type of programming language for formatting text, and Notebooks are an R Studio-specific way of displaying Markdown documents.

2 The components of an R Markdown File

Let’s read through this document, and see what you have created.

2.1 The header

At the top of your document is its header. Information in the header is enclosed between two three-dash lines.

Header for your document

Header for your document

The header is written in a style called YAML, an acronym whose meaning is somewhat disputed. But what’s important is that YAML is a language for recording data in a way that can be read by both humans and machines. YAML is made up of a series of key-value pairs. For instance, the first line of your Header will read something like

title: “My amazing markdown document”

In this case, the key is title and the value is “My amazing markdown document”. You can read this, and so can R Studio, and when it comes time to “Knit” the document (e.g., turn it into a webpage), R Studio will know to entitle the document My amazing markdown document.

You can edit the header in lots of different ways. Some Key:Value pairs can take almost any value. For instance, you can change the title value in any way you like, as long as the value is a string (i.e., is enclosed in quotation marks). Try editing the title in some crazy ways, and then re-Knitting the document.

Other Key:Value pairs, like the Output key, take only a limited range of values. For instance, try changing the Output value from “html_document” to “excel_document” and the Knit the document. You should receive an error message from R Studio, as below

This message occurs because the software that Knits the RMarkdown file does not know how to turn it into an Excel file (and why would you want to create an Excel file anyway!?); there are only a limited number of options for this Key:Value pair and “excel_document” is not one. Erase “excel_document”, replace it with “html_document”, and Knit the file again to make sure that everything is working.

If you want to see a list of some options for the Header, take a look here.

2.2 The free text

Underneath the Header is a little grey box that looks like this:

We’ll ignore that little grey box for now, but we’ll come back to it later! Instead, let’s examine the text outside the box, which looks like this:

Markdown text

Markdown text

You have probably noticed that, when you Knitted the document, it was this text that was displayed. The line of text with the hash marks (#) in front of it become a Heading, while the text below was displayed as the body of the document. This aspect of the Markdown document is equivalent to the writing that you might do in a Microsoft Word document. What you write down here will be displayed on the Webpage that you Knit.

Importantly, you can format the appearance of this text in the resulting document, just as you might do with a Word document. However, to do that, you don’t highlight the text and press a button, rather, you use special characters to inform R Studio as to how the text should be formatted. For instance, the hash marks (#) indicate that some text should be treated as a heading (with 1 mark indicating a very large heading, and 4 indicating a small heading), while the stars (*) around a piece of text indicate that it should be displayed in italics.

Other options include:

  • One * around a word or phrase will make it italic, two ** will make it bold, three *** will make it both, and four **** will not do anything.
  • You can make a list of bullet points by putting a * at the beginning of each line, and you can also indent your list using + as below (you have to leave some spaces in front of the +).
* Item 1
* Item 2
    + Item 2a
    + Item 2b
  • You can also make a numbered list by replacing the * or + with a number plus a period 1.
    • Note that when you Knit a document with lists, you might encounter errors if there are not blank lines before and after the list (this also applies to headings).
  • You can add superscripts as so: ^superscript^.
  • You can add a hyperlink to an external webpage, using the format [link text](http://www.linkaddress.com).
  • You can add images using very similar code ![image_caption](image_filename). Note that there’s a ! before the opening square bracket.

2.2.1 Exercises

  1. Get creative with your Markdown document. Add some text that uses the different formatting options described above, including links to some interesting CogSci relevant web pages, and some images (you’ll need to download them to your project folder).
  2. Headings (#) are very useful for organizing your Markdown document. By creating a set of headings organize your markdown document as though it were an APA style paper. (Remember to use Headings, not bullet points and lists). Note that, using a PC keyboard, you should be able to write down a Hash mark by pressing together the alt key on the right of your keyboard and the number 3 key on the number line.
* Introduction
* Experiment 1
  + Methods
    - Participants
    - Materials
    - Procedure
  + Results
    - Analysis 1
    - Analysis 2
  + Discussion
* Experiment 2
  + Methods
    - Participants
    - Materials
    - Procedure
  + Results
  + Discussion
* General Discussion
* References
  1. Let’s make a Table of Contents. To do this, you’ll need to modify the Header of your document as so:
output: 
  html_document:
    toc: true
    number_sections: true
  1. You can also make your ToC float to the side, by adding the following code toc_float: true (I’ll let you figure out where it goes; shout if you need help).

2.3  R Code Chunks

Let’s go back to that grey box.

R Code

R Code

This aspect of your document is what gives R Markdown its amazing powers, because it allows you to run R code within the document itself! Wow! Let’s go through what these three lines of code do.

2.3.1 Line 1

``` {r setup, include=FALSE}

Each component of this section, from the three inverted commas to the curly brackets, plays a different role.

  • The three inverted commas ``` tell RStudio that what comes next is going to be a section of computer code, rather than text.
  • The curly braces {} enclose information that acts as a Header for the forthcoming computer code. In this case, it contains the following information:
    • The r indicates that the subsequent computer code will be written using the R statistical programming language (you can also use other languages, like Python, but we won’t do that).
    • Next, the word setup acts as a label for this particular section of computer code (you can change that label however you want, but each section can only have one label, and each label in an RMarkdown document must be unique). It is useful to label your sections so that when you return to your document weeks later, you know what each section does.
    • After the label, there is a comma , and then a set of parameters for the section. These are similar to the key-value pairs that we saw before. In this case, include=FALSE indicates that the code in the section, along with its results, should not be displayed in the document. Try deleting that parameter, reKnit the document, and see how it has changed.

2.3.2 Line 2

knitr::opts_chunk$set(echo = TRUE)

This is a line of R code, just as you have used in your statistics labs. In this case, the R code is being used to set a default option for the entire document. In particular it says that, for code chunks like this, the code itself should be displayed in the document unless the user specifies otherwise.

Optional Fun. To see the implications of this, edit the line of code in your document that reads ```{r cars}, to include the parameter echo=FALSE (don’t forget to include a comma in front), and see how the resulting document changes.

2.3.3 Line 3

```

The final set of three inverted commas close off the code chunk. Anything on the lines after this will be evaluated as text, until another code chunk begins.

2.3.4  Exercises

  • Create a new code chunk and call it generate_data. In this chunk, we will generate some data to plot! We’ll make some nice sinusoids and then plot them. Create a variable called x that is a sequence from -10 to 10 in steps of 0.1 (i.e., -10,-9.9,-9.8…9.9,10). You can do this using the R function seq; if you know how, go ahead, or you can look at the code chunk below.
  • Create a new variable called sine_x, which is simply the sine transformation of all the values in x.
  • Create a new variable called cos_x, which is the cosine transform of all the values in x.
  • Create a plot that has x on its X axis, and sine_x on its Y axis.

The resulting code should look something like this:

x <- seq(-10,10,0.1)
sine_x <- sin(x)
cos_x <- cos(x)
plot(x,sine_x)

First, let’s evaluate this code without Knitting the document (this is a very cool feature of R Markdown/Notbooks). Highlight the code that you want to run, and then click the button in the Top Right, called Run > Run Selected Lines

Running code

Running code

Fingers crossed, this should do two things. First, the code should evaluate in the Terminal, and second, you should see your plot below the code chunk (cool!).

Now, let’s mess around with this graph. Change the code (either as below, or however you like) and re-evaluate it to see how your graph changes.

  • Add the cos_x points using the function points (type ?points) if you need help.
  • Add a line connecting all the points (using the function line)
  • Mess around with the graph in any other way you like (e.g., change the color of the points, change the type of line, etc!

If you have used R before, then you may have come across the package ggplot2, which makes very pretty graphs. You can also use ggplot2 in RMarkdown. If you know how to use the package already, try to do it on your own. If you don’t, create a second code chunk underneath the chunk generate_data, ```{r, ggplot_sine} and then include the code below.

library(ggplot2)

sine_data_frame <- data.frame(x = rep(x,2), 
                              output = c(sine_x,cos_x),
                              function_call = rep(c("sine","cos"), each = length(x))
                          )
                          
sine_wave <- ggplot(data = sine_data_frame, aes(x=x, y = output,col = function_call))+
                geom_line()+
                geom_point()

sine_wave

As always, if you get an error, just yell (politely)!

  • In your R Markdown document, try to write down an explanation of what is happening in this code.
  • One neat thing, which you may have noticed, is that output and variables from one code chunk can be accessed in subsequent code chunks (here, we access the variables x, sine_x and cos_x).

2.4  R Code in text

You can also include R code in your running text. This can be useful when you want to do simple calculations, or to report the results of your statistical tests. For example, imagine that you have 600 participants in your experiment, and they were evenly divided between 15 conditions. You could write some simple R code in your text to calculate the number of participants per condition.

R code is inserted like so: ` r 2+2`. You begin with an inverted comma followed by the letter r, followed by a line of code that is evaluated. Note that there should not be a space between the inverted comma and the r (I had to insert the space here to ensure the code was displayed to you, rather than evaluated). It should look like this:

Running code

Running code

When written like this, you can only include a single line of R code. However, there is a trick for including multiple lines of code: Enclose the code (the stuff after the letter r) in curly brackets {} and separate each line with a semi-colon, like so {PeanutButterPrice = 3.2; PeanutButterUnitsBought = 4; PeanutButterCost = PeanutButterPrice * PeanutButterUnitsBought; PeanutButterCost}, which evaluates to £12.8

2.4.1 Exercise

  • Use inline r code and the functions mean(), sd(), and round() to write a line of text that says the means and standard deviations of the variables x, sine_x, and cos_x, with all numbers rounded to 2 decimal places.

2.5 Tables

There are two ways to create tables in R Markdown.

2.5.1 Hand-coded Tables

One is to hand code the Table using the Markdown language. For instance, the code below creates the subsequent table.

| Condition | Age | Verbal Score | Non-Verbal Score |
|:------|-----:|---------:|------:|
| Autism Spectrum | 12;3 | 81 | 120 |
| Age Control | 12;4 | 123 | 130 |
| Language Matched Control | 10;2 | 81 | 100 |
Condition Age Verbal Score Non-Verbal Score
Autism Spectrum 12;3 81 120
Age Control 12;4 123 130
Language Matched Control 10;2 81 100

2.5.1.1 Exercise

Create a Table in your own Markdown document by copying the code above. Let’s see what the different parts of the Table do by deleting them!

  • Delete the row that contains all the hyphens - and Knit. What happens? Undo your change. Hyphens are a critical part of the Table as they say where the Header row is (There must be at least 3 hyphens under each column of the Header row).
  • Delete the pipe | between Condition and Age, and then Knit. What happens? Undo your change. Pipes are critical for defining columns.
  • Play with the colons at the start and end of the header rows. What is their purpose?

2.5.2 R tables

You can also create tables by using R functions that format data in elegant, pre-specified formats. I recommend that you use the function kable, which is part of the package knitr.

kable allows you to turn ugly numbers, like this

##                    mpg cyl disp  hp drat    wt  qsec vs am gear carb
## Mazda RX4         21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
## Mazda RX4 Wag     21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
## Datsun 710        22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
## Hornet 4 Drive    21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
## Hornet Sportabout 18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
## Valiant           18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

into pretty numbers, like this

mpg cyl disp hp drat wt qsec vs am gear carb
Mazda RX4 21.0 6 160 110 3.90 2.62 16.46 0 1 4 4
Mazda RX4 Wag 21.0 6 160 110 3.90 2.88 17.02 0 1 4 4
Datsun 710 22.8 4 108 93 3.85 2.32 18.61 1 1 4 1
Hornet 4 Drive 21.4 6 258 110 3.08 3.21 19.44 1 0 3 1
Hornet Sportabout 18.7 8 360 175 3.15 3.44 17.02 0 0 3 2
Valiant 18.1 6 225 105 2.76 3.46 20.22 1 0 3 1

2.5.2.1 Exercise

Create an r code chunk called tables.

  • Print an ugly dataframe, e.g., by using the functions head() or summary() on the dataframe cars.
  • Print a prettier dataframe, by using the function kable(). Make sure that the output of the previously used function is now the input to kable.
  • You can also use kable to print pretty statistical tables. Try running a regression: regression_results <- summary(lm(sine_x ~ x)). Print an ugly version of the output using regression_results$coef, and then a pretty version using kable(regression_results$coef)

2.6 Commenting your document

It is often helpful to leave comments in your document – both in the Markdown itself, and in your R code – so that you can explain what you have done, or leave a note about what to do in the future.

In an R code chunk, you can turn a line of text into a comment by leading with a #, like so

# This is a comment about some code
a <- 1+2

# The commented code below doesn't work; I should fix this next time
# c <- 1 + "2"

You can also comment out sections of Markdown code. For instance, if you are writing a document but don’t want a particular paragraph or table to be displayed, you can put it in a comments tag. This is a little bit different from commenting R code. For code, you begin each line of a comment with a #. For RMarkdown, you enclose the commented text in a tag like this:

<!-- This text won't display in the document -->

One easy way to comment out some text in RMarkdown is using the Comment option on the Code menu at the top of the screen. Highlight the text you want to comment out, and press that option. Try it on your own document.

2.7  Publishing your R Markdown file

A final and very helpful feature of R Markdown is that you can publish your documents and share them on the Internet!. Knit your document, and then press Publish in the top right corner. This will take you to the RPubs website, where you can create a free account and publish your document.

3 Your assignment for this week

Write an R Markdown file that provides a full precis of the paper you intend to replicate. Within this, provide a concise but appropriately detailed description of the particular experimental task that you plan to replicate. This assignment should be submitted on Learn (under Assessment details > Week 2 assignment) and is due one week from today’s lab.