This document is created with RMarkdown.

What is it?

RMarkdown is a special documentation format that works with Markdown (a markup language) and R. It is a very useful tool for reporting analyses. Its input is an .Rmd file and its output can be PDF, Word, HTML, Powerpoint file, and several other types (you will learn to get html and pdf outputs in this document). This document will walk you through the steps to create your first RMarkdown report.

Preparation

Before we can begin download and install the following programs. Make sure you install the right programs according to your OS (i.e. Windows, Mac or Linux).

install.packages("rmarkdown",repos="http://cran.rstudio.com/")

You should be all set.

Basic Elements of RMarkdown

In this section you will learn how to construct an .Rmd file. First step is to open a text editor (e.g. RStudio, Notepad++ or Atom). Create a new text file and save as headstart.Rmd (with the extension, make sure your extension is not .txt or any other extension).

YAML Header

Your Rmd file should start with a header section starting and ending with three dashes (---). It is also called a YAML header. A minimal example would be as follows. It is the YAML part of this document.

---
title: "Quick Introduction to RMarkdown"
author: Berk Orbay
date: Feb 15, 2017
---

You will be able to expand it with other options but it is the story for another tutorial. At the end of this tutorial you are going to find links to intermediate and advanced uses of RMarkdown.

Markdown Syntax

Since you are essentially writing on a plain text file, there are special characters for Markdown which will translate into styles. For instance for big section headers use hash symbol (#), hence the hashtag of Twitter. For a smaller one add one more to ##. For a smaller one ### and so on. Examples are given below. Just compare them to the actual implementations.

You can try Markdown syntax with some online editors. For example try stackedit.io.

# Basic Elements of RMarkdown
## Markdown Syntax
  • Bold is written with ** before and after the phrase (in this case **Bold**).

  • Italic is written with _ before and after the phrase (in this case _Italic_).

  • To take a line break use an empty line or two spaces after the sentence.

  • Itemization is done with + symbol at the beginnning of a line. See example below.

+ **Bold** is written with `**` before and after the phrase (in this case `**Bold**`).

+ _Italic_ is written with `_` before and after the phrase (in this case `_Italic_`).

+ To take a line break use an empty line.
  • For enumeration (ie. 1., 2., 3.) just write 1. instead of +. It will do enumeration automatically (you can also do proper enumeration such as 1., 2. and 3., same output).

    1. Item 1
    2. Item 2
    3. Item 3
  • You can also use HTML syntax such as <br>, <p></p>, <b></b>, <i></i>. Sometimes they are more convenient, sometimes they are not. But you will be fine with Markdown syntax.

Running R Code

The amazing part of RMarkdown is you can run R code from .Rmd files. You just need to write the code between ```{r} and ```. The special character is called a backtick (`) and you should use three of them. For instance look at the code below. It is automatically highlighted and results are calculated.

#In R, comments start with (#). They are used to explain the code.
#This code is a simple sampling of coin tosses
set.seed(50) #Set the seed for reproducibility.
sample(c("H","T"),size=10,replace=TRUE)
##  [1] "T" "H" "H" "T" "T" "H" "T" "T" "H" "H"

You should just include the R code and RMarkdown in your .Rmd file just like below. (Don’t copy paste these lines below for technical reasons, write your own.)

`​``{r eval=TRUE}
#In R, comments start with (#). They are used to explain the code.
#This code is a simple sampling of coin tosses
set.seed(50) #Set the seed for reproducibility.
sample(c("H","T"),size=10,replace=TRUE)
`​``

Bonus: Also you can embed in-line R codes with `​r 2*2` (don’t copy paste these). For instance here I’m running an inline R function here: 4.

Final Step: Rendering

Save your headstart.Rmd file to a folder. Open R and write the following command.

rmarkdown::render(input=file.choose(),output_format="html_document")

It will open a select file menu. Select your headstart.Rmd file. After some processes (and if you have a proper .Rmd file) you will get the following warning in your R console: Output created: headstart.html. If you change the output format to pdf_document you will get a PDF file (if you installed LaTeX).

Instead of file.choose() you can write the full path of your file. For instance, for Windows it can be "C:/somefolder/somesubfolder/headstart.Rmd" or for Mac/Linux it can be "~/somefolder/somesubfolder/headstart.Rmd" or "/Users/berkorbay". Remember to put the path in quotes (') or double quotes (") as it is a string.

Warning for Windows users: You should use slash (/) or double backslash (\\), not single backslash (\) to define a path.

LaTeX with RMarkdown

If you also installed LaTeX, you will be able to include better writing in your mathematical experssions.

You should use double dollars $$ to include LaTeX notation in your Rmd files. For instance let’s run $$\sum_{i=1}^{N} 2^i$$.

\[\sum_{i=1}^{N} 2^i\]

For in-line LaTeX commands use single dollar $ symbol. For example $\sum_{i=1}^{N} 2^i$ can be converted to \(\sum_{i=1}^{N} 2^i\).

Bonus: Faster Progress with RStudio

Download RStudio. RStudio is an integrated development environment (IDE - a fancy name for code editor + compiler and more).

Open RStudio. Open a new R Markdown file via File > New File > R Markdown. Set default output as HTML. You get your default .Rmd file with prepopulated text. If you click Knit (positioned just above your first line of text), you will get the output. You can change the content as you wish and get yourself a new setting.

Other Resources

See the official page of RMarkdown from here for further information.