-
-
Notifications
You must be signed in to change notification settings - Fork 537
/
15-knitr-markdown.Rmd
465 lines (365 loc) · 14.1 KB
/
15-knitr-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
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
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
---
title: Producing Reports With knitr
teaching: 60
exercises: 15
questions:
- "How can I integrate software and reports?"
objectives:
- Understand the value of writing reproducible reports
- Learn how to recognise and compile the basic components of an R Markdown file
- Become familiar with R code chunks, and understand their purpose, structure and options
- Demonstrate the use of inline chunks for weaving R outputs into text blocks, for example when discussing the results of some calculations
- Be aware of alternative output formats to which an R Markdown file can be exported
keypoints:
- "Mix reporting written in R Markdown with software written in R."
- "Specify chunk options to control formatting."
- "Use `knitr` to convert these documents into PDF and other formats."
source: Rmd
---
```{r chunk_options, include=FALSE}
source("../bin/chunk-options.R")
knitr_fig_path("15-")
```
## Data analysis reports
Data analysts tend to write a lot of reports, describing their
analyses and results, for their collaborators or to document their
work for future reference.
Many new users begin by first writing a single R script containing all of the
work. Then simply share the analysis by emailing the script and various graphs
as attachments. But this can be cumbersome, requiring a lengthy discussion to
explain which attachment was which result.
Writing formal reports with Word or [LaTeX](http://www.latex-project.org/)
can simplify this by incorporating both the analysis report and output graphs
into a single document. But tweaking formatting to make figures look correct
and fix obnoxious page breaks can be tedious and lead to a lengthly "whack
a mole" game of fixing new mistakes resulting from a single formatting change.
Creating a web page (as an html file) by using R Markdown makes things easier.
The report can be one long stream, so tall figures that wouldn't ordinary fit on
one page can be kept full size and easier to read, since the reader can simply
keep scrolling. Formatting is simple and easy to modify, allowing you to spend
more time on your analyses instead of writing reports.
## Literate programming
Ideally, such analysis reports are _reproducible_ documents: If an
error is discovered, or if some additional subjects are added to the
data, you can just re-compile the report and get the new or corrected
results (versus having to reconstruct figures, paste them into
a Word document, and further hand-edit various detailed results).
The key R package is [`knitr`](http://yihui.name/knitr/). It allows you
to create a document that is a mixture of text and chunks of
code. When the document is processed by `knitr`, chunks of code will
be executed, and graphs or other results inserted into the final document.
This sort of idea has been called "literate programming".
`knitr` allows you to mix basically any sort of text with code from different programming languages, but we recommend that you use `R Markdown`, which mixes Markdown
with R. [Markdown](https://www.markdownguide.org/) is a light-weight mark-up language for creating web
pages.
## Creating an R Markdown file
Within RStudio, click File → New File → R Markdown and
you'll get a dialog box like this:
![](../fig/New_R_Markdown.png)
You can stick with the default (HTML output), but give it a title.
## Basic components of R Markdown
The initial chunk of text (header) contains instructions for R to specify what kind of document will be created, and the options chosen. You can use the header to give your document a title, author, date, and tell it that you're going to want
to produce html output (in other words, a web page).
```
---
title: "Initial R Markdown document"
author: "Karl Broman"
date: "April 23, 2015"
output: html_document
---
```
You can delete any of those fields if you don't want them
included. The double-quotes aren't strictly _necessary_ in this case.
They're mostly needed if you want to include a colon in the title.
RStudio creates the document with some example text to get you
started. Note below that there are chunks like
<pre>
```{r}
summary(cars)
```
</pre>
These are chunks of R code that will be executed by `knitr` and replaced
by their results. More on this later.
Also note the web address that's put between angle brackets (`< >`) as
well as the double-asterisks in `**Knit**`. This is
[Markdown](http://daringfireball.net/projects/markdown/syntax).
## Markdown
Markdown is a system for writing web pages by marking up the text much
as you would in an email rather than writing html code. The marked-up
text gets _converted_ to html, replacing the marks with the proper
html code.
For now, let's delete all of the stuff that's there and write a bit of
markdown.
You make things **bold** using two asterisks, like this: `**bold**`,
and you make things _italics_ by using underscores, like this:
`_italics_`.
You can make a bulleted list by writing a list with hyphens or
asterisks, like this:
```
* bold with double-asterisks
* italics with underscores
* code-type font with backticks
```
or like this:
```
- bold with double-asterisks
- italics with underscores
- code-type font with backticks
```
Each will appear as:
- bold with double-asterisks
- italics with underscores
- code-type font with backticks
You can use whatever method you prefer, but *be consistent*. This maintains the
readability of your code.
You can make a numbered list by just using numbers. You can even use the
same number over and over if you want:
```
1. bold with double-asterisks
1. italics with underscores
1. code-type font with backticks
```
This will appear as:
1. bold with double-asterisks
1. italics with underscores
1. code-type font with backticks
You can make section headers of different sizes by initiating a line
with some number of `#` symbols:
```
# Title
## Main section
### Sub-section
#### Sub-sub section
```
You _compile_ the R Markdown document to an html webpage by clicking
the "Knit" button in the upper-left.
> ## Challenge 1
>
> Create a new R Markdown document. Delete all of the R code chunks
> and write a bit of Markdown (some sections, some italicized
> text, and an itemized list).
>
> Convert the document to a webpage.
> > ## Solution to Challenge 1
> >
> > In RStudio, select File > New file > R Markdown...
> >
> > Delete the placeholder text and add the following:
> >
> > ```
> > # Introduction
> >
> > ## Background on Data
> >
> > This report uses the *gapminder* dataset, which has columns that include:
> >
> > * country
> > * continent
> > * year
> > * lifeExp
> > * pop
> > * gdpPercap
> >
> > ## Background on Methods
> >
> > ```
> >
> > Then click the 'Knit' button on the toolbar to generate an html document (webpage).
> {: .solution}
{: .challenge}
## A bit more Markdown
You can make a hyperlink like this:
`[text to show](http://the-web-page.com)`.
You can include an image file like this: `![caption](http://url/for/file)`
You can do subscripts (e.g., F~2~) with `F~2~` and superscripts (e.g.,
F^2^) with `F^2^`.
If you know how to write equations in
[LaTeX](http://www.latex-project.org/), you can use `$ $` and `$$ $$` to insert math equations, like
`$E = mc^2$` and
```
$$y = \mu + \sum_{i=1}^p \beta_i x_i + \epsilon$$
```
You can review Markdown syntax by navigating to the
"Markdown Quick Reference" under the "Help" field in the
toolbar at the top of RStudio.
## R code chunks
The real power of Markdown comes from
mixing markdown with chunks of code. This is R Markdown. When
processed, the R code will be executed; if they produce figures, the
figures will be inserted in the final document.
The main code chunks look like this:
<pre>
```{r load_data}
gapminder <- read.csv("gapminder.csv")
```
</pre>
That is, you place a chunk of R code between <code>```{r chunk_name}</code>
and <code>```</code>. You should give each chunk
a unique name, as they will help you to fix errors and, if any graphs are
produced, the file names are based on the name of the code chunk that
produced them.
> ## Challenge 2
>
> Add code chunks to:
>
> * Load the ggplot2 package
> * Read the gapminder data
> * Create a plot
>
> > ## Solution to Challenge 2
> >
> > <pre>
> > ```{r load-ggplot2}
> > library("ggplot2")
> > ```
> > </pre>
> >
> > <pre>
> > ```{r read-gapminder-data}
> > gapminder <- read.csv("gapminder.csv")
> > ```
> > </pre>
> >
> > <pre>
> > ```{r make-plot}
> > plot(lifeExp ~ year, data = gapminder)
> > ```
> > </pre>
> >
> {: .solution}
{: .challenge}
## How things get compiled
When you press the "Knit" button, the R Markdown document is
processed by `[knitr](http://yihui.name/knitr)` and a plain Markdown
document is produced (as well as, potentially, a set of figure files): the R code is executed
and replaced by both the input and the output; if figures are
produced, links to those figures are included.
The Markdown and figure documents are then processed by the tool
[`pandoc`](http://pandoc.org/), which converts the Markdown file into an
html file, with the figures embedded.
```{r rmd_to_html_fig, fig.width=8, fig.height=3, fig.align="left", echo=FALSE}
par(mar=rep(0, 4), bty="n", cex=1.5)
plot(0, 0, type="n", xlab="", ylab="", xaxt="n", yaxt="n",
xlim=c(0, 100), ylim=c(0, 100))
xw <- 10
yh <- 35
xm <- 12
ym <- 50
rect(xm-xw/2, ym-yh/2, xm+xw/2, ym+yh/2, lwd=2)
text(xm, ym, ".Rmd")
xm <- 50
ym <- 80
rect(xm-xw/2, ym-yh/2, xm+xw/2, ym+yh/2, lwd=2)
text(xm, ym, ".md")
xm <- 50; ym <- 25
for(i in c(2, 0, -2))
rect(xm-xw/2+i, ym-yh/2+i, xm+xw/2+i, ym+yh/2+i, lwd=2,
border="black", col="white")
text(xm-2, ym-2, "figs/")
xm <- 100-12
ym <- 50
rect(xm-xw/2, ym-yh/2, xm+xw/2, ym+yh/2, lwd=2)
text(xm, ym, ".html")
arrows(22, 50, 38, 50, lwd=2, col="slateblue", len=0.1)
text((22+38)/2, 60, "knitr", col="darkslateblue", cex=1.3)
arrows(62, 50, 78, 50, lwd=2, col="slateblue", len=0.1)
text((62+78)/2, 60, "pandoc", col="darkslateblue", cex=1.3)
```
## Chunk options
There are a variety of options to affect how the code chunks are
treated. Here are some examples:
- Use `echo=FALSE` to avoid having the code itself shown.
- Use `results="hide"` to avoid having any results printed.
- Use `eval=FALSE` to have the code shown but not evaluated.
- Use `warning=FALSE` and `message=FALSE` to hide any warnings or
messages produced.
- Use `fig.height` and `fig.width` to control the size of the figures
produced (in inches).
So you might write:
<pre>
```{r load_libraries, echo=FALSE, message=FALSE}
library("dplyr")
library("ggplot2")
```
</pre>
Often there will be particular options that you'll want to use
repeatedly; for this, you can set _global_ chunk options, like so:
<pre>
```{r global_options, echo=FALSE}
knitr::opts_chunk$set(fig.path="Figs/", message=FALSE, warning=FALSE,
echo=FALSE, results="hide", fig.width=11)
```
</pre>
The `fig.path` option defines where the figures will be saved. The `/`
here is really important; without it, the figures would be saved in
the standard place but just with names that begin with `Figs`.
If you have multiple R Markdown files in a common directory, you might
want to use `fig.path` to define separate prefixes for the figure file
names, like `fig.path="Figs/cleaning-"` and `fig.path="Figs/analysis-"`.
> ## Challenge 3
>
> Use chunk options to control the size of a figure and to hide the
> code.
>
> > ## Solution to Challenge 3
> >
> > <pre>
> > ```{r echo = FALSE, fig.width = 3}
> > plot(faithful)
> > ```
> > </pre>
> >
> {: .solution}
{: .challenge}
You can review all of the `R` chunk options by navigating to
the "R Markdown Cheat Sheet" under the "Cheatsheets" section
of the "Help" field in the toolbar at the top of RStudio.
## Inline R code
You can make _every_ number in your report reproducible. Use
<code>`r</code> and <code>`</code> for an in-line code chunk,
like so: <code>`r round(some_value, 2)`</code>. The code will be
executed and replaced with the _value_ of the result.
Don't let these in-line chunks get split across lines.
Perhaps precede the paragraph with a larger code chunk that does
calculations and defines variables, with `include=FALSE` for that larger
chunk (which is the same as `echo=FALSE` and `results="hide"`).
Rounding can produce differences in output in such situations. You may want
`2.0`, but `round(2.03, 1)` will give just `2`.
The
[`myround`](https://github.com/kbroman/broman/blob/master/R/myround.R)
function in the [R/broman](https://github.com/kbroman/broman) package handles
this.
> ## Challenge 4
>
> Try out a bit of in-line R code.
>
> > ## Solution to Challenge 4
> >
> > Here's some inline code to determine that 2 + 2 = `` `r
> > 2+2` ``.
> >
> {: .solution}
{: .challenge}
## Other output options
You can also convert R Markdown to a PDF or a Word document. Click the
little triangle next to the "Knit" button to get a drop-down
menu. Or you could put `pdf_document` or `word_document` in the initial header
of the file.
> ## Tip: Creating PDF documents
>
> Creating .pdf documents may require installation of some extra software. If
> required this is detailed in an error message.
>
> - [TeX installers for Windows](https://miktex.org/2.9/setup).
> - [TeX installers for macOS](https://tug.org/mactex).
{: .callout}
## Resources
* [Knitr in a knutshell tutorial](http://kbroman.org/knitr_knutshell)
* [Dynamic Documents with R and knitr](http://www.amazon.com/exec/obidos/ASIN/1482203537/7210-20) (book)
* [R Markdown documentation](http://rmarkdown.rstudio.com)
* [R Markdown cheat sheet](https://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf)
* [Getting started with R Markdown](https://www.rstudio.com/resources/webinars/getting-started-with-r-markdown/)
* [R Markdown: The Definitive Guide](https://bookdown.org/yihui/rmarkdown/) (book by Rstudio team)
* [Reproducible Reporting](https://www.rstudio.com/resources/webinars/reproducible-reporting/)
* [The Ecosystem of R Markdown](https://www.rstudio.com/resources/webinars/the-ecosystem-of-r-markdown/)
* [Introducing Bookdown](https://www.rstudio.com/resources/webinars/introducing-bookdown/)