-
Notifications
You must be signed in to change notification settings - Fork 72
/
cm003.Rmd
214 lines (137 loc) · 9.11 KB
/
cm003.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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
# Authoring
Communication of a data analysis is just as important as the analysis itself. Today, we'll be looking at tools for _writing_ about your analysis.
__Announcements__:
- The add/drop deadline for Stat 545A is on Wednesday Sep. 11
- Hang tight -- the canvas slot for Assignment 1 is coming shortly.
## Learning Objectives
By the end of today's class, students are expected to be able to:
- Write documents in markdown on GitHub and RStudio, and render these documents to html and pdf with RStudio.
- Choose whether html or pdf is an appropriate output
- Style an Rmd document by editing the YAML header
- Demonstrate at least two Rmd code chunk options
- Make presentation slides using one of the R Markdown presentation formats.
## Resources
Cheat sheets for "quick reference":
- [GitHub's markdown cheatsheet](https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf)
- [RStudio's R markdown cheatsheet](http://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf)
Further reading:
- The [Rmd website](https://rmarkdown.rstudio.com/) has a fantastic walk-through [tutorial](https://rmarkdown.rstudio.com/lesson-1.html) that gives a great overview of R Markdown. There's also a nice [overview video](https://rmarkdown.rstudio.com/authoring_quick_tour.html) on the site, too.
- Yihui's [Rmd book](https://bookdown.org/yihui/rmarkdown/) for lots more on R Markdown.
Other explorations of this content:
- Interactive [tutorial](https://commonmark.org/help/tutorial/) for learning markdown.
- The [stat545: Rmd test drive](http://stat545.com/block007_first-use-rmarkdown.html).
## Topic 1: Output Formats (5 min)
There are generally two prominent non-proprietary file types to display manuscripts of various types:
1. __pdf__: This is useful if you intend to print your work onto a physical sheet of paper, or for presentation slides. If this is not the primary purpose, then avoid at all costs, because formatting things so that it fits to the page is way more effort than its worth (unless your making presentation slides).
- Example: The [concession template](https://stat545.stat.ubc.ca/concession_template.pdf).
2. __html__: This is what you see when you visit a webpage. Content does not need to be partitioned to pages.
- Example: My [website main page](https://vincenzocoia.com), and its corresponding [html file](https://github.com/vincenzocoia/website/blob/hugo/public/index.html).
- Example: html [slides using ioslides](https://rpubs.com/cheyu/ioslideDemo).
We won't be using proprietary file types, like MS Word. Amongst [many reasons](http://www.antipope.org/charlie/blog-static/2013/10/why-microsoft-word-must-die.html), it just doesn't make sense for integrating reproducible code into the document and for a dynamic analysis.
Others that we won't be covering:
- Jupyter notebooks (actually a JSON file)
- LaTeX
We'll be treating pdf and html files as _output_ that should not be edited. In fact, pdf documents are not even easy to edit, and even if you do pay for the Adobe add-on to edit the files, this is not a reproducible workflow.
What's the source, then? (R) __Markdown__! We'll be discussing this
## Topic 2: Markdown
(3 min)
Markdown is plain text with an easy, readable way of marking up your text. Let's see [GitHub's cheat sheet](https://guides.github.com/pdfs/markdown-cheatsheet-online.pdf). Various software convert markdown to either pdf or html.
File extension: `.md`
### Activity: Modify `navigating_github.md` (5 min)
Together:
1. Open your `navigating_github.md` file that we made in the first class.
2. Mark up the text with some markdown features.
3. Commit your changes.
Notice that GitHub automatically displays markdown files nicely, but not HTML files.
### Activity: Render `navigating_github.md` (5 min)
N.B.: this exercise employs an effective _local_ workflow, which we will address next class.
Together:
1. Download the contents of your GitHub participation repository as a zip file.
2. In RStudio, open the file `navigating_github.md`.
- Yes! RStudio also acts as a plain text editor!
3. Convert the `.md` file to both pdf and html by clicking the appropriate button under the "Preview" tab.
4. Push the two new files to GitHub (by dragging and dropping the files onto your participation repo).
## Topic 3: R Markdown
(2 min)
R Markdown (Rmd) is a "beefed up" version of markdown -- it has many more features built in to it, two important ones being:
- We can specify more features in a _YAML header_.
- This contains metadata about the document to guide how the Rmd document is rendered.
- We can integrate code into a document.
Here's [RStudio's cheat sheet](http://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf) on Rmd. You can see that it certainly has more features than "regular" markdown!
### Activity: getting set up with R packages (5 min)
(Includes what we missed from last class)
To get started with using R Markdown, you'll need to install the `rmarkdown` R package. The activity we have also depends on the `gapminder`, `tibble`, and `DT` packages.
Together:
1. To install these packages, in any R console, run the following:
```
install.packages('rmarkdown')
install.packages('gapminder')
install.packages('tibble')
install.packages('DT')
```
"Official" R packages are stored an retrieved from [CRAN](https://cran.r-project.org/).
2. Check out vignettes for the tibble package by running `browseVignettes(package = "rmarkdown")`.
### Activity: exploring code chunks (15 min)
Last class, we explored data frames. This time, we'll explore tibbles, but within code chunks in an R Markdown document.
Together:
1. Open RStudio's Rmd boilerplate by going to "File" -> "New File" -> "R Markdown" in RStudio. Explore!
2. Scrap everything below the YAML header.
3. Add a code chunk below the YAML header via "Insert" -> "R". Or, by:
- Mac: `Cmd + Option + I`
- Windows: `Ctrl + Alt + I`
4. Load the `gapminder` and `tibble` packages using the `library()` function, by adding the following code to your code chunk:
```
library(gapminder)
library(tibble)
library(DT)
```
5. Print out the `gapminder` data frame to explore the output. Then, in a new code chunk, convert the `mtcars` data frame to a tibble using the `tibble::as_tibble()` function. Try out the `DT::datatable()` function on a data frame!
6. Add some markdown commentary to this comparative analysis.
7. Add an in-line code chunk specifying the number of rows of the `mtcars` dataset.
8. "Knit" to html and pdf.
Note: `knitr` integrates the code into the document. The actual conversion here is Rmd -> md -> pdf/html.
### Activity: exploring the YAML header (10 min)
(Note: If you've "fallen off the bus" from the last exercise, here's a "bus stop" for you to get back on -- just start a new Rmd file and use the boilerplate content while we work through this exercise.)
Now, we'll modify the metadata via the YAML header. Check out a bunch of YAML options [from the R Markdown book](https://bookdown.org/yihui/rmarkdown/html-document.html).
Together, in an Rmd file (ideally the one from the previous exercise):
1. Change the output to `html_document`. We'll be specifying settings for the html document, so this needs to go on a new line after the `output:` field:
```
output:
html_document:
SETTINGS
GO
HERE
```
2. Add the following settings:
- Keep the `md` intermediate file with `keep_md: true`
- Add a theme. My favourite is cerulean: `theme: cerulean`
- Add a table of contents with `toc: true`
- Make the toc float: `toc_float: true`.
3. Knit the results (you may have to delete the pdf, because it is no longer up to date!)
### Activity: exploring chunk options (5 min)
(Bus stop! Couldn't get previous exercises to work? No problem, just start a fresh R Markdown document with File -> New File -> R Markdown)
Just like YAML is metadata for the Rmd document, _code chunk options_ are metadata for the code chunk. Specify them within the `{r}` at the top of a code chunk, separated by commas.
Together, in an Rmd file (ideally the same one we've been working on):
1. Hide the code from the output with `echo = FALSE`.
2. Prevent warnings from the chunk that loads packages with `warning = FALSE`.
3. Knit the results.
## Topic 4: Rmd Presentations
(3 min)
You can also make presentation slides using Rmd. A great resource is Yihui's [Rmd book, "Presentations" section](https://bookdown.org/yihui/rmarkdown/presentations.html).
Some types of formats:
- ioslides
- [xaringan](https://slides.yihui.name/xaringan/#1)
- [slidy](https://www.w3.org/Talks/Tools/Slidy2/#(1))
- [reveal.js](https://revealjs.com/#/)
- ...
### Activity: exploring ioslides (10 min)
Let's turn the file we've been working on into slides.
Together:
1. In RStudio, go to "File" -> "New File" -> "R Markdown" -> "Presentation" -> "ioslides". Explore!
2. Clear everything below the YAML header.
3. Copy and paste the tibble exploration we've been working on (without the YAML header), and turn them into slides.
## Wrap-up (3 min)
Push the following files to your GitHub repo:
1. `navigating_github.md` and its output formats.
2. The Rmd exploration and its output formats.
3. The Rmd presentation slides exploration and its output formats.