/
R_markdown.Rmd
170 lines (144 loc) · 11.5 KB
/
R_markdown.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
---
title: "R Markdown"
author: Luke
output:
github_document:
toc: true
toc_depth: 2
fig_width: 5
fig_height: 5
---
# R Markdown
## What is R Markdown?
R Markdown is a file format that uses R to make interactive documents. A R Markdown document (.Rmd file) is written in markdown, a minimalist plain text format with the organizational power of word processors, and it contains embedded blocks of R code.
R Markdown files are designed to be used with the `rmarkdown` package. This package comes with the default RStudio installation, but it can be installed with the command
```
> install.packages("rmarkdown")
```
## The R Markdown File
A R Markdown file contains dynamic elements that are embedded in the plain text, structured by markdown formatting. The following text file is an example of a R Markdown document.
With R Studio's highlighting, from first glance it is apparent that there are three different frameworks in the R Markdown document:
1. The header separated by the triple dashes `---`, known as the YAML header for rendering parameters
2. The embedded code in the gray blocks, separated by the triple backticks and curly brackets with a 'r' inside `` ```{r} ``
3. The remaining formatted markdown plain text
* Within the plain text, there are small in-line code blocks surrounded by single backticks `` `code block` ``
R Studio can _render_ the raw R Markdown document and transform it into a suitable document for sharing data and results, such as a Word document, PDF, or a HTML5 webpage. R Studio enlists the help of the `knitr` package to run each embedded code block and add it to the document, while the `pandoc` package outputs the document and code into the designated file format according to the YAML header. As a result, the example R Markdown document becomes a formatted and ready-to-share document.
## Getting Started
R markdown files can be created by opening a plain text and saving the file with the _.Rmd_ file extension. The _.Rmd_ extension is necessary for R Studio to recognize the document as a R Markdown file. In RStudio Cloud, this can be done by going to the toolbar and clicking on _File_ > _New File_ > _Text File_. This will open an empty text file in the text editor window.
As noted earlier, R Markdown relies on three frameworks to produce professional documents: markdown for formatted text, embedded code, and the YAML header.
## Markdown Basics
Markdown is necessary to format and organize information without the help of a word processor such as Microsoft Office Word program. This allows the user to indicate lists, bold and italic text, hyperlinks, and much more without having to copy and paste special characters.
In addition, markdown conventions are clear and easy to read:
1. Italic text is indicated by surrounding text with the asterisk (`*`) or underscore (`_`) characters, like `*italic words*` or `_more italic words_`. Bold text is indicated by surrounding text with two consecutive asterisks (`**`) or two underscores (`__`), like `**bold words**` or `__more bold words__`.
2. Headers begin with the pound (`#`) sign. A single `#` creates a first level header, or the largest header. Two pound signs, `## Second Level Header`, creates a second level header, and so on, where the first level is the largest and each successive level gets progressively smaller.
3. Lists can be ordered or unordered. In an ordered list, each line starts with the numeric placement, and sub-lists are indented by four spaces and a plus (`+`) sign. In unordered lists, each item begins with an asterisk, and each item in a sub-list is indented by four spaces and a plus (`+`) sign.
Ordered lists:
```
1. Item 1
2. Item 2
3. Item 3
+ sub-item 1
+ sub-item 2
```
Unordered lists:
```
* Item 1
* Item 2
+ sub-item 1
+ sub-item 2
```
4. Code blocks, as mentioned earlier, are indicated by the triple backticks and the curly brackets surrounding a 'r' (`` ```{r} ``), and in-line code blocks are indicated by a single backtick followed by a "r" (`` `r ``). Code will be run and executed during rendering.
Code blocks:
````
```{r}
summary(cars)
dim(cars)
```
````
In-line code:
````
This is in-line code: `r code goes here`.
````
5. Plain code blocks are not evaluated by R Studio, but they are rendered at a fixed-width font. Unlike the previous example of code blocks, plain code blocks require only the triple ticks without the `{r}`.
````
```
Plain code blocks will not be evaluated by R Studio when rendering. However, text inside the code block will still be placed within its own code block after rendering.
```
````
6. External links can be a simple URL (e.g. https://github.com), or a phrase can be hyperlinked to another url. For example, `[Github hyperlink](https://github.com)` generates a [Github hyperlink](https://github.com).
7. Images are similar to linked phrases for URLs, except embedded images require an exclamation mark at the beginning. The text inside the square brackets provides the image caption that appears when the mouse hovers over the image. For example, `` embeds an image without a caption, while `` adds a caption.
Additional markdown formatting can be found in [R Markdown Basics](http://rmarkdown.rstudio.com/authoring_basics.html).
## Embedded R Code
R Markdown supports code blocks that contain R code. The value of code blocks allows the user to easily edit and update the code without having to copy and paste new figures and results. As noted in the Markdown Basics section, markdown supports the simpler plain code blocks, but R Markdown takes code blocks one step further by running the code within the code blocks and appending the results to the document. The `knitr` package looks for the `{r}` indicator before evaluating the code block. However, the curly brackets allow for additional arguments, such as displaying the code block verbatim instead of running the code, or removing the original code and display only the results.
The default usage of `{r}` keeps the original code block and publishes both the code block and its output. In the example R Markdown document, this is illustrated by the
````
```{r}
summary(cars)
```
````
code block. Its rendered output is
.
If the arguments inside the curly brackets included `eval=FALSE`, then R Studio and `knitr` would know to skip the evaluation step and only publish the code block.
````
```{r eval=FALSE}
summary(cars)
```
````
The addition of the `eval=FALSE` to the previous example would generate
If `eval=FALSE` was instead replaced by `echo=FALSE`, then `knitr` will omit the original code and only publish the code results to the final document. In this case, the code block
````
```{r echo=FALSE}
summary(cars)
```
````
would render
Similarly, in-line code is surrounded by a single backtick and the letter "r". For example, the line
```
The sum of 2 plus 2 is `r 2 + 2`.
```
would produce the output
```
The sum of 2 plus 2 is 4.
```
In-line code behaves like a code block with the `echo=FALSE` argument.
## YAML Render Parameters
The final framework of the R Markdown document is the YAML rendering parameters. The YAML header is surrounded by triple dashes (`---`) and consists of `key: value` pairs. The `key` is one of many pre-defined variables that the `pandoc` package looks for when it converts the raw plain text file to its desired output. The `value` is information given by the user and tells the program what to do, like below
```
---
title: "Untitled"
author: "Name"
date: "January 1, 2000"
output: html_document
---
```
The `output:` pair determines the file type of the rendered output. In this example, the output would be a HTML web document. In general, there are three main outputs:
* `html_document` creates a HTML document (default)
* `pdf_document` creates a PDF document
* `word_document` creates a Word document
R Markdown documents can also be rendered as a slideshow document, By default, `rmarkdown` will create a new slide at each header, but the document can be further split up by adding horizontal rules (`***`). `rmarkdown` supports four different slideshow formats:
* [`beamer_presentation`](http://rmarkdown.rstudio.com/beamer_presentation_format.html) - PDF slideshow document
* [`ioslides_presentation`](http://rmarkdown.rstudio.com/ioslides_presentation_format.html) - HTML slideshow document
* [`slide_presentation`](http://rmarkdown.rstudio.com/slidy_presentation_format.html) - alternative HTML slideshow document
* [`revealjs::revealjs_presentation`](http://rmarkdown.rstudio.com/revealjs_presentation_format.html) - another type of HTML slideshow document
## Rendering
Once the R Markdown document has been saved, the document can be transformed into a HTML, PDF, or Word document. To do so, open the dropdown menu with the knit options and select the appropriate output. Doing so will overide the output option in the YAML header.
`rmarkdown` will create a copy of the file in the new format, and the new file will be saved to the cloud. Files will be available through the file manager on the bottom right of RStudio Cloud. Clicking on the file name will open the file in a new tab on the browser.
Another way to render the document without the knit dropdown menu is to type the `rmarkdown::render()` command into the console beneath the text editor. Inside the parentheses, it is important to specify the name of the R Markdown document to render in quotes, like `rmarkdown::render("rmarkdown.Rmd")`. Otherwise, `rmarkdown` will not know what file to render. The `rmarkdown::render()` command will follow the rules set by the YAML header.
## Summary
R Markdown provides an easy-to-use and easy-to-read report in R. The document is written in markdown with embedded R code blocks. The `knitr` package allows the user to easily update the code by simply re-knitting the document. Also, the document can be converted into one of several familiar file formats.
## Additional Resources
* [R Markdown Basics](http://rmarkdown.rstudio.com/authoring_basics.html)
* [R Markdown Cheatsheet](https://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf)
* [R Markdown Reference Guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf)
## Review Questions
1. What are the three frameworks that compose R Markdown documents?
2. How is a header created, and what is the difference between each level of headers?
3. What are the two kinds of lists that can be created, and how are they created?
4. What types of files can R Studio render?