R Markdown

We can install the R Markdown package using either the console

install.packages("rmarkdown")
# and then load the library
library(rmarkdown)

or selecting an R Markdown/R Notebook document from the + menu.

The installation may require some additional “Yes” here and there, don’t be shy :)

So…

What is R Markdown? from RStudio, Inc. on Vimeo.

But… let’s go one step back! What is Markdown?

Markdown

According to the creators:

Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).

Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML.

The Daring Fireball Company LLC.

So, let’s have a look at the basic syntax of Markdown.

Syntax (basics)

In Markdown, to specify a header (the title of a section or a subsection and so on), we use the hashtag # symbol. For the first and second level headers, there is an alternative syntax.

# Level 1 header
## Level 2 header
### Level 3 header

Level 1 header
==============
Level 2 header
--------------

We can include links in the text using the < link > syntax, or add the link to a word with the syntax [word](link).

We can get italic font using the syntax *italic font* or _italic font_ and the bold font using **bold font** or __bold font__

By using the following syntax

* item 1
* item 2 
* item 3

OR 

+ item 1
+ item 2 
+ item 3

OR

- item 1
- item 2 
- item 3

we get

item 1
item 2
item 3

Whereas, the code

1. item
2. item
3. item

returns a numbered list.

We can include parts of code inline using the ` our code ` (back apostrophe) syntax. If we want to include a block of code we use

```

line of code1

line of code2

```

We can include pictures using the syntax ![alt text](/path/to/img.jpg "Title") and we can write tables as follows

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

Tables	Are	Cool
col 3 is	right-aligned	$1600
col 2 is	centered	$12
zebra stripes	are neat	$1

For those that are used to the Latex syntax, in R Markdown, you can directly include mathematical expressions inline using the '$e^{1/3}$ notation, or include equation blocks using the

$$

your math

$$

You can find these and the other syntax examples at the page.

Back to R Markdown

Exercise 1

Create an empty R Notebook. Discuss what you notice and practice with the syntax.

We can write text in R Markdown using the Markdown syntax that we learned before. Moreover, we can execute R commands and include the results directly in a document. This feature is fundamental to enhance the reproducibility of scientific results.

In fact, an R Markdown document allows anyone to check the correctness of the code, as well as the results, all in the same document.

We can easily include R commands in the document either through the keys combination Cmd + Option + I in Mac or Ctrl + Alt + I in Windows, or using the insert button. In addition, we can type the code block as in markdown, as well as the inline code. At the page, you can find a detailed description of the options and the commands.

As in any R script, we should set a working directory and include the packages we need. Then, we include the chunks of code that we want to run.

As already mentioned, unless some specific options are included, the code and the output of any command will be included in the document. This is particularly useful for tables that are the output of some commands (such as table or summary) or for plots. In this way, there is no need to save a plot, it will be displayed as it is produced.

Another convenient feature is that the document, at least in the html format, supports interactive tables and plots. The following chunks of code include some examples of the potential of this feature.

#Uncomment to install the packages
#install.packages("DT") 

library(DT)
datatable(mtcars,
          filter = 'top', options = list(
            pageLength = 12, autoWidth = TRUE
          ), caption = "An interactive table.")

#From https://plot.ly/ggplot2/getting-started/#plotly-for-r

#Uncomment to install the packages
#install.packages("ggplot2") 
#install.packages("plotly", dependencies=TRUE)

library(ggplot2)
library(plotly)
set.seed(100)
d <- diamonds[sample(nrow(diamonds), 1000), ]

p <- ggplot(data = d, aes(x = carat, y = price)) +
  geom_point(aes(text = paste("Clarity:", clarity)), size = 4) +
  geom_smooth(aes(colour = cut, fill = cut)) + facet_wrap(~ cut)

p <- ggplotly(p)

The output of these chunks is available here (Rmd)

For an extensive tutorial on the use of R Markdown, please visit this page.

Time to practice

Exercise 2

Create an R Markdown document where you import the dataset from the url (description). Analyze the data and explore a possible relationship between the two variable. Comment on your results.

Exercise 3

Modify one of your assignments and import it in R Markdown. Export the file in HTML, Word, and PDF (if it is possible).

Useful links

Notes on R (in Italian) link.
R commands cheatsheet (in Italian) link.
Here, you can find the R Markdown of a good course on data visualization, previously hosted at http://vissoc.co/