R Markdown Basics

Young Statisticians Conference 2019

Alison Hill · RStudio

https://ysc-rmarkdown.netlify.com/

Wifi network name

Functions

Wifi password

Stata_16

Go here and log in (free):

http://bit.ly/ysc-rmarkdown

Time
Activity


09:00 - 10:30
Session 1 (R Markdown Basics)

10:30 - 11:00
Break ☕

11:00 - 12:30
Session 2 (Advanced R Markdown)

12:30 - 01:30
Lunch 🍱

01:30 - 03:00
Session 3 (Templates)

03:00 - 03:30
Break 🍵

03:30 - 05:00
Session 4 (Collections)

Time	Activity
09:00 - 10:30	Session 1 (R Markdown Basics)
10:30 - 11:00	Break ☕
11:00 - 12:30	Session 2 (Advanced R Markdown)
12:30 - 01:30	Lunch 🍱
01:30 - 03:00	Session 3 (Templates)
03:00 - 03:30	Break 🍵
03:30 - 05:00	Session 4 (Collections)

Alison Hill

@apreshill
@apreshill

Emi Tanaka

@emitanaka
@statsgen

All content is CC-BY. All art (unless otherwise noted) is by Desirée De Leon, CC-BY-NC-ND.

What is R Markdown?

An authoring framework for data science.
A document format (.Rmd).
An R package named rmarkdown.
A file format for making dynamic documents with R.
A tool for integrating prose, code, and results.
A computational document.
Wizardry.

What is R Markdown?

"An authoring framework for data science." (✔️)
A document format (.Rmd). (✔️)
An R package named rmarkdown. (✔️)
"A file format for making dynamic documents with R." (✔️)
"A tool for integrating text, code, and results." (✔️)
"A computational document." (✔️)
Wizardry. (🧙‍♂️)

Change your mental model

Source ↔ output

Source → output

Change your mental model

Source ↔ output

Source → output

https://www.americangirl.com/shop/c/welliewishers

https://ysc-rmarkdown.netlify.com/
Same doll sourceDifferent occasions

`html_document`

Go here:

https://github.com/ysc2019-workshop/01-basics

Click on "Use this template" (make sure you are logged in)

In your repo

Click on green button, then the clipboard to copy HTTPS

Go to rstudio.cloud:

http://bit.ly/ysc-rmarkdown

Join space > Click on "Projects" (nothing there)
New Project from GitHub Repo
Use your HTTPS link:

Name your project

Last step!

I promise! Still in rstudio.cloud:

library(usethis)
use_git_config(
  scope = "project",
  user.name = "Jane",
  user.email = "jane@example.org"
)

Your turn

Find a partner and look at 01-bakeoff-report.Rmd together. Look at the source, then 🧶 Knit to HTML.

Try to identify these parts in the source and the output:

The metadata
The text
The code
The output

If this was easy, try to find all code that produces a plot.

05:00

Basic anatomy I

We look at the source anatomy for 01-bakeoff-report.Rmd together:

The metadata
The text
The code

Basic anatomy II

We look at the output anatomy for 01-bakeoff-report.Rmd together:

The metadata
The text
The code
The output

Art by Allison Horst

What is inside?

Metadata

metadata: YAML

"YAML Ain't Markup Language"

---
key: value
---

https://ysc-rmarkdown.netlify.com/
Output options

Save output options in your YAML

---
title: The Great British Bake Off
output: html_document
---

---
title: The Great British Bake Off
output:
  html_document:
    toc: true
---

Your turn

Add output options to YAML

Use ?html_document from your R console to:

Add a floating table of contents
Add a theme

🧶 Knit to HTML to see the output.

If this was easy, try to embed the Rmd source code to download.

psst...answers on the next slide...

03:00

Answers

---
title: The Great British Bake Off
output:
  html_document:
    toc: true
    toc_float: true
    theme: flatly
    code_download: true
---

Parameters

---
title: The Great British Bake Off
output:
  html_document:
    toc: true
    toc_float: true
    theme: flatly
    code_download: true
params:
  series: '1'
---

Your turn

Change this:

---
title: The Great British Bake Off
output:
  html_document:
    toc: true
    toc_float: true
    theme: flatly
    code_download: true
params:
  series: '1'
---

To this:

---
title: The Great British Bake Off
output:
  html_document:
    toc: true
    toc_float: true
    theme: flatly
    code_download: true
params:
  series: '2'
---

Now click on knit button and pick "Knit with Parameters." How is this different from what you did above?

03:00

Text

https://ysc-rmarkdown.netlify.com/
Headers

https://ysc-rmarkdown.netlify.com/
Headers# HEADER 1
## HEADER 2
### HEADER 3
#### HEADER 4
##### HEADER 5
###### HEADER 6

https://ysc-rmarkdown.netlify.com/
Headers# HEADER 1
## HEADER 2
### HEADER 3
#### HEADER 4
##### HEADER 5
###### HEADER 6

HEADER 1
HEADER 2
HEADER 3
HEADER 4
HEADER 5
HEADER 6

https://ysc-rmarkdown.netlify.com/
Text

https://ysc-rmarkdown.netlify.com/
Text **The Great British Bake Off** 
(often abbreviated to _Bake Off_ or _GBBO_) 
is a British television baking competition.

Text

 **The Great British Bake Off** 
(often abbreviated to _Bake Off_ or _GBBO_) 
is a British television baking competition.

The Great British Bake Off (often abbreviated to Bake Off or GBBO) is a British television baking competition.

https://ysc-rmarkdown.netlify.com/
Lists

https://ysc-rmarkdown.netlify.com/
ListsThe original cast included:
- Sue Perkins (_host_)
- Mel Giedroyc (_host_)
- Mary Berry (_judge_) and
- Paul Hollywood (_judge_).
In each episode, the amateur bakers are 
given **three challenges** based on that 
week's theme.
1. a signature bake,
1. a technical challenge,
1. a show-stopper.

Lists

The original cast included:
- Sue Perkins (_host_)
- Mel Giedroyc (_host_)
- Mary Berry (_judge_) and
- Paul Hollywood (_judge_).
In each episode, the amateur bakers are 
given **three challenges** based on that 
week's theme.
1. a signature bake,
1. a technical challenge,
1. a show-stopper.

The original cast included:

Sue Perkins (host)
Mel Giedroyc (host)
Mary Berry (judge) and
Paul Hollywood (judge).

In each episode, the amateur bakers are given three challenges based on that week's theme.

a signature bake,
a technical challenge,
a show-stopper.

https://ysc-rmarkdown.netlify.com/
Images

https://ysc-rmarkdown.netlify.com/
ImagesCompetitive baking, such as making Victoria 
sponge (_pictured_), is part of the classic 
English village fête,
which inspired the series.
![](http://bit.ly/blue-ribbon-sponge)

Images

Competitive baking, such as making Victoria 
sponge (_pictured_), is part of the classic 
English village fête,
which inspired the series.
![](http://bit.ly/blue-ribbon-sponge)

Competitive baking, such as making Victoria sponge (pictured), is part of the classic English village fête, which inspired the series.

https://ysc-rmarkdown.netlify.com/
Links

https://ysc-rmarkdown.netlify.com/
LinksCompetitive baking, such as making Victoria 
sponge (_pictured_), is part of the classic 
English village fête,
which inspired the series.
[Photo](https://en.wikipedia.org/)
![](http://bit.ly/blue-ribbon-sponge)

Links

Competitive baking, such as making Victoria 
sponge (_pictured_), is part of the classic 
English village fête,
which inspired the series.
[Photo](https://en.wikipedia.org/)
![](http://bit.ly/blue-ribbon-sponge)

Competitive baking, such as making Victoria sponge (pictured), is part of the classic English village fête, which inspired the series.

Photo

https://ysc-rmarkdown.netlify.com/
Pop quiz

Pop quiz

How do you add headers in Markdown?

! Header

- Header

# Header

1. Header

Pop quiz

How do you add headers in Markdown?

! Header

- Header

# Header

1. Header

What about lists? Bulleted? Numbered?

! Item 1

- Item 1

# Item 1

1. Item 1

code

Code chunks

```{r}
ratings %>% 
  filter(series == 1) %>% 
  top_n(1, viewers_7day)
```

What is the fate of this chunk?

Code chunks

```{r}
ratings %>% 
  filter(series == 1) %>% 
  top_n(1, viewers_7day)
```

What is the fate of this chunk?

ratings %>% 
  filter(series == 1) %>% 
  top_n(1, viewers_7day)
#> # A tibble: 1 x 8
#>   series episode uk_airdate viewers_7day viewers_28day network_rank
#>    <int>   <int> <date>            <dbl>         <dbl>        <int>
#> 1      1       5 2010-09-14         3.03             1           NA
#> # … with 2 more variables: channels_rank <int>, bbc_iplayer_requests <dbl>

Code chunks

```{r}
top_viewers <- ratings %>% 
  filter(series == 1) %>% 
  top_n(1, viewers_7day)
```

What fate do you predict here?

Code chunks

```{r}
top_viewers <- ratings %>% 
  filter(series == 1) %>% 
  top_n(1, viewers_7day)
```

What fate do you predict here?

top_viewers <- ratings %>% 
  filter(series == 1) %>% 
  top_n(1, viewers_7day)

https://ysc-rmarkdown.netlify.com/
Code chunks```{r}
top_viewers <- ratings %>% 
  filter(series == 1) %>% 
  top_n(1, viewers_7day)
top_viewers
```

https://ysc-rmarkdown.netlify.com/
Code chunks```{r}
top_viewers <- ratings %>% 
  filter(series == 1) %>% 
  top_n(1, viewers_7day)
top_viewers
```
top_viewers <- ratings %>% 
  filter(series == 1) %>% 
  top_n(1, viewers_7day)
top_viewers
#> # A tibble: 1 x 8
#>   series episode uk_airdate viewers_7day viewers_28day network_rank
#>    <int>   <int> <date>            <dbl>         <dbl>        <int>
#> 1      1       5 2010-09-14         3.03             1           NA
#> # … with 2 more variables: channels_rank <int>, bbc_iplayer_requests <dbl>

Code chunks

```{r}
ggplot(viewers, aes(episode, viewers, 
                    colour = days, 
                    group = days)) + 
  geom_point() + 
  geom_line() + 
  labs(x = "Episode", 
       y = "Viewers (millions)") +
  expand_limits(y = 0) 
```

What about this one?

Code chunks

```{r}
ggplot(viewers, aes(episode, viewers, 
                    colour = days, 
                    group = days)) + 
  geom_point() + 
  geom_line() + 
  labs(x = "Episode", 
       y = "Viewers (millions)") +
  expand_limits(y = 0) 
```

What about this one?

ggplot(viewers, aes(episode, viewers, 
                    colour = days, 
                    group = days)) + 
  geom_point() + 
  geom_line() + 
  labs(x = "Episode", 
       y = "Viewers (millions)") +
  expand_limits(y = 0)

Adding/running chunks

Together we:

Add chunks with button or:

Command (or Cmd) ⌘ + Option (or Alt) ⌥ + i (Mac)

Ctrl + Alt + i (Windows/Linux)
Run chunks by:

Run current chunk button (interactive)

Knit button / run all chunks

Inline code

The top viewed episode in series 1 was episode `r top_viewers %>% pull(episode)`

Inline code

The top viewed episode in series 1 was episode `r top_viewers %>% pull(episode)`

The top viewed episode in series 1 was episode 5

Output

https://ysc-rmarkdown.netlify.com/
Chunk options```{r}
glimpse(ratings)
```
glimpse(ratings)
#> Observations: 84
#> Variables: 8
#> $ series               <int> 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 3…
#> $ episode              <int> 1, 2, 3, 4, 5, 6, 1, 2, 3, 4, 5, 6, 7, 8, 1…
#> $ uk_airdate           <date> 2010-08-17, 2010-08-24, 2010-08-31, 2010-0…
#> $ viewers_7day         <dbl> 2.24, 3.00, 3.00, 2.60, 3.03, 2.75, 3.10, 3…
#> $ viewers_28day        <dbl> 7, 3, 2, 4, 1, 1, 2, 2, 1, 1, 1, 1, 1, 1, 1…
#> $ network_rank         <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ channels_rank        <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ bbc_iplayer_requests <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…

https://ysc-rmarkdown.netlify.com/
echo```{r echo=FALSE}
glimpse(ratings)
```
#> Observations: 84
#> Variables: 8
#> $ series               <int> 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2, 2, 2, 3…
#> $ episode              <int> 1, 2, 3, 4, 5, 6, 1, 2, 3, 4, 5, 6, 7, 8, 1…
#> $ uk_airdate           <date> 2010-08-17, 2010-08-24, 2010-08-31, 2010-0…
#> $ viewers_7day         <dbl> 2.24, 3.00, 3.00, 2.60, 3.03, 2.75, 3.10, 3…
#> $ viewers_28day        <dbl> 7, 3, 2, 4, 1, 1, 2, 2, 1, 1, 1, 1, 1, 1, 1…
#> $ network_rank         <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ channels_rank        <int> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…
#> $ bbc_iplayer_requests <dbl> NA, NA, NA, NA, NA, NA, NA, NA, NA, NA, NA,…

https://ysc-rmarkdown.netlify.com/
eval```{r eval=FALSE}
glimpse(ratings)
```
glimpse(ratings)

https://ysc-rmarkdown.netlify.com/
include```{r include=FALSE}
glimpse(ratings)
```

https://ysc-rmarkdown.netlify.com/
results```{r echo=TRUE, results='hide'}
glimpse(ratings)
```
glimpse(ratings)

message / warning

https://ysc-rmarkdown.netlify.com/
message / warning```{r message=FALSE, warning=FALSE}
library(tidyverse)
```
library(tidyverse)

https://ysc-rmarkdown.netlify.com/
Default options
str(knitr::opts_chunk$get())
#> List of 53
#>  $ eval         : logi TRUE
#>  $ echo         : logi TRUE
#>  $ results      : chr "markup"
#>  $ tidy         : logi FALSE
#>  $ tidy.opts    : NULL
#>  $ collapse     : logi TRUE
#>  $ prompt       : logi FALSE
#>  $ comment      : chr "#>"
#>  $ highlight    : logi TRUE
#>  $ strip.white  : logi TRUE
#>  $ size         : chr "normalsize"
#>  $ background   : chr "#F7F7F7"
#>  $ cache        : logi FALSE
#>  $ cache.path   : chr "01-basics_cache/html/"
#>  $ cache.vars   : NULL
#>  $ cache.lazy   : logi TRUE
#>  $ dependson    : NULL
#>  $ autodep      : logi FALSE
#>  $ cache.rebuild: logi FALSE
#>  $ fig.keep     : chr "high"
#>  $ fig.show     : chr "asis"
#>  $ fig.align    : chr "default"
#>  $ fig.path     : chr "01-basics_files/figure-html/"
#>  $ dev          : chr "png"
#>  $ dev.args     : NULL
#>  $ dpi          : num 72
#>  $ fig.ext      : NULL
#>  $ fig.width    : num 7
#>  $ fig.height   : num 7
#>  $ fig.env      : chr "figure"
#>  $ fig.cap      : NULL
#>  $ fig.scap     : NULL
#>  $ fig.lp       : chr "fig:"
#>  $ fig.subcap   : NULL
#>  $ fig.pos      : chr ""
#>  $ out.width    : NULL
#>  $ out.height   : NULL
#>  $ out.extra    : NULL
#>  $ fig.retina   : num 1
#>  $ external     : logi TRUE
#>  $ sanitize     : logi FALSE
#>  $ interval     : num 1
#>  $ aniopts      : chr "controls,loop"
#>  $ warning      : logi TRUE
#>  $ error        : logi FALSE
#>  $ message      : logi TRUE
#>  $ render       : NULL
#>  $ ref.label    : NULL
#>  $ child        : NULL
#>  $ engine       : chr "R"
#>  $ split        : logi FALSE
#>  $ include      : logi TRUE
#>  $ purl         : logi TRUE

Chunk option take-aways

Place between curly braces
{r option=value}
Multiple options separated by commas
{r option1=value, option2=value}
Careful! The r part is the code engine (other engines possible)

Chunk labels

```{r peek, echo=FALSE, results='hide'}
glimpse(ratings)
```

Place between curly braces
{r label}
Separated options with commas
{r label, option1=value}

Careful! No duplicate chunk labels

```{r peek}
head(ratings)
```

Error in parse_block(g[-1], g[1], params.src) : 
  duplicate label 'peek'
Calls: <Anonymous> ... process_file -> split_file -> lapply -> FUN -> parse_block
Execution halted

how can we make it easier on ourselves to explore the code in here?

show how to add chunk labels and view in IDE interactively

Pet or livestock?

https://masalmon.eu/2017/08/08/chunkpets/; https://www.express.co.uk/news/nature/770211/pet-sheep-lamb-rasied-dog-farm-nature

A good chunk label

Good

my-plot

myplot

myplot1

myplot-1

MY-PLOT

Bad

my_plot

my plot

everything else!

The setup chunk

```{r setup, include=FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,   
  comment = "#>", 
  out.width = "100%" 
)
```

A special chunk label: setup
Typically #1
All following chunks will use these options (i.e., sets global chunk options)
Tip: set include=FALSE
You can (and should) use individual chunk options too

Adding a setup chunk

We do this together:

Add fig.path = "figs/" as a knitr code chunk option for a single plot (watch what happens if we don't include the backslash!)
Knit and behold
We add it to a global setup chunk.

Your turn

Customize this report.

Label the code chunk with your plot in it.
Add your setup chunk.
Use the RStudio outline pane; rejoice!
Build a graphical user interface for parameters.

If this was easy, try adding a parameter for color palette and add in a package like wesanderson — use the parameter in our ggplot2 code.

psst...01-bakeoff-report-alison.Rmd is there...

psst-psst...answers on the next slide...

05:00

Answers

params:
  series:
    label: "Series:"
    value: 1
    input: numeric
    min: 1
    max: 9
    step: 1
  palette: 
    label: "Wes Anderson palette:"
    value: GrandBudapest1
    input: select
    choices: [GrandBudapest1, Darjeeling1, Darjeeling2, FantasticFox1, Royal2]

📮

https://app.netlify.com/drop

Clean your url up

We live demo changing the main "landing page" name to index.Rmd, knit, then deploy again: https://app.netlify.com/drop

https://ysc-rmarkdown.netlify.com/
Take-aways

Take-aways

✔️ Document your document: use YAML to set up meaningful metadata

Take-aways

✔️ Document your document: use YAML to set up meaningful metadata

✔️ Style your document: use YAML to add options to your chosen output format

Take-aways

✔️ Document your document: use YAML to set up meaningful metadata

✔️ Style your document: use YAML to add options to your chosen output format

✔️ Organize your text: use markdown headers with #

Take-aways

✔️ Document your document: use YAML to set up meaningful metadata

✔️ Style your document: use YAML to add options to your chosen output format

✔️ Organize your text: use markdown headers with #

✔️ Organize your code: use knitr chunk labels

Take-aways

✔️ Document your document: use YAML to set up meaningful metadata

✔️ Style your document: use YAML to add options to your chosen output format

✔️ Organize your text: use markdown headers with #

✔️ Organize your code: use knitr chunk labels

✔️ Style your text: use markdown bold, italics, bullets, and lists

Take-aways

✔️ Document your document: use YAML to set up meaningful metadata

✔️ Style your document: use YAML to add options to your chosen output format

✔️ Organize your text: use markdown headers with #

✔️ Organize your code: use knitr chunk labels

✔️ Style your text: use markdown bold, italics, bullets, and lists

✔️ Style your output: use knitr chunk options

Take-aways

✔️ Document your document: use YAML to set up meaningful metadata

✔️ Style your document: use YAML to add options to your chosen output format

✔️ Organize your text: use markdown headers with #

✔️ Organize your code: use knitr chunk labels

✔️ Style your text: use markdown bold, italics, bullets, and lists

✔️ Style your output: use knitr chunk options

🧶 early, 🧶 often

https://ysc-rmarkdown.netlify.com/
⏱Time for a break!
30:00

↑, ←, Pg Up, k	Go to previous slide
↓, →, Pg Dn, Space, j	Go to next slide
Home	Go to first slide
End	Go to last slide
Number + Return	Go to specific slide
b / m / f	Toggle blackout / mirrored / fullscreen mode
c	Clone slideshow
p	Toggle presenter mode
t	Restart the presentation timer
?, h	Toggle this help