R Markdown Anatomy

class: title-slide, center, middle

01

# R Markdown Anatomy

## R Markdown for Medicine

### Alison Hill &#183; RStudio

#### [rmd4medicine.netlify.com/](https://rmd4medicine.netlify.com/)

---
class: middle, center

.pull-left[
#

Wifi network name

`Omni Meeting`
]

.pull-left[
#

Wifi password

`rmedicine`
]

---
class: middle, center

#

# Go here and log in (free):

https://rstd.io/rmd4medicine-cloud

---
class: middle, center

| Time          | Activity                                |
|:--------------|:----------------------------------------|
| 01:00 - 01:50 | Session 1 (R Markdown Anatomy)          |
| 01:50 - 02:00 | *Break* ☕           |
| 02:00 - 02:45 | Session 2 (Outputs & Tables)            |
| 02:45 - 03:00 | *Break* 🍵              |
| 03:00 - 03:50 | Session 3 (Graphics for Communication)  |
| 03:50 - 04:00 | *Break* 🚰    |
| 04:00 - 04:45 | Session 4 (Data & Workflows)            |
| 04:45 - 05:00 | Wrap-up / Overtime                      |

---
layout: true

<div class="my-footer">https://rstd.io/rmd4medicine-cloud</div>

---
background-image: url(images/hello.jpg)
background-position: top center
background-size: 100%
class: bottom, center

.pull-left[
### Alison Hill 
[ @apreshill](https://github.com/apreshill) 
[ @apreshill](https://twitter.com/apreshill)

### Peter Higgins 
[ @higgi13425](https://github.com/higgi13425) 
[ @ibddoctor](https://twitter.com/ibddoctor)
]

.pull-right[
### Daniel Chen 
[ @chendaniely](https://github.com/chendaniely) 
[ @chendaniely](https://twitter.com/chendaniely)

]

.footnote[All content is CC-BY. All art (unless otherwise noted) is by [Desirée De Leon](https://desiree.rbind.io/), CC-BY-NC-ND.]

---
background-image: url(images/deardata.jpg)
background-size: 50%

.footnote[https://www.dear-data.com/]

---

.left-column[

 
 ?
 
]

.right-column[

# What is R Markdown?

1. An authoring framework for data science.

1. A document format (`.Rmd`).

1. An R package named `rmarkdown`.

1. A file format for making dynamic documents with R.

1. A tool for integrating prose, code, and results.

1. A computational document.

1. Wizardry.

]

---

.left-column[

 
 ?
 
]

.right-column[

# What is R Markdown?

1. ["An authoring framework for data science."](https://rmarkdown.rstudio.com/lesson-1.html) (✔️)

1. [A document format (`.Rmd`).](https://bookdown.org/yihui/rmarkdown/) (✔️)

1. [An R package named `rmarkdown`.](https://rmarkdown.rstudio.com/docs/) (✔️)

1. ["A file format for making dynamic documents with R."](https://rmarkdown.rstudio.com/articles_intro.html) (✔️)

1. ["A tool for integrating text, code, and results."](https://r4ds.had.co.nz/communicate-intro.html) (✔️)

1. ["A computational document."](http://radar.oreilly.com/2011/07/wolframs-computational-documen.html) (✔️)

1. Wizardry. (🧙‍♂️)

]

---
class: center
background-image: url(https://media.giphy.com/media/11fDMHAzihB8D6/source.gif)

# Reproducibility crisis?

???

We are not here today to solve science or medicine's reproducibility crisis.

What I do think R Markdown can help you with today when you leave here is to tackle two other crises: one I think of as the confidence crisis...

---
class: center
background-image: url(https://media.giphy.com/media/OPZZ6KWJOZ3AA/source.gif)

# Confidence crisis

---
class: center
background-image: url(https://dickbrouwer.com/img/meeting_cheese.png)
background-size: contain

# 🧀 Cheese crisis 🧀

.footnote[https://dickbrouwer.com/blog/a-guide-to-better-meetings/]

---
class: middle, center

# Change your mental model

.pull-left[

### Source &harr; output

]

.pull-right[

### Source &rarr; output

]

---
class: middle, center

# Change your mental model

.pull-left[

### Source &harr; output

]

.pull-right[

### Source &rarr; output

]

---
background-image: url(images/welliewishers/Slide1.png)
background-size: cover
class: top, center

.footnote[https://www.americangirl.com/shop/c/welliewishers]

---
background-image: url(images/welliewishers/Slide2.png)
background-size: cover
class: top, center

.footnote[https://www.americangirl.com/shop/c/welliewishers]

---
class: middle, inverse, center

# Same ~~doll~~ source

# Different occasions

---
class: middle, center

# `html_document`

---
class: your-turn

# Your turn

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

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

1. The **metadata**

1. The **text**

1. The **code**

1. The **output**

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

_psst...`01-explore-alison-params.Rmd` is also there..._

---
class: live-code

# Basic anatomy I

We look at the source anatomy for `01-explore.Rmd` together:

1. The **metadata**

1. The **text**

1. The **code**
    
---
class: center, middle

---
class: center, middle

---
class: live-code

# Basic anatomy II

We look at the output anatomy for `01-explore.Rmd` together:

1. The **metadata**

1. The **text**

1. The **code**

1. The **output**

---
background-image: url(images/rmarkdown_wizards.png)
background-size: contain

.footnote[Art by [Allison Horst](https://twitter.com/allison_horst?lang=en)]

---
class: middle, center

# What is inside?

![](images/doc-make.jpg)

---
class: middle, center, inverse

1

# Metadata

---

# metadata: YAML

.pull-left[

_"YAML Ain't Markup Language"_

```yaml
---
key: value
---
```

]

.pull-right[

]

---
class: middle, center

# Output options

---

# Save output options in your YAML

.pull-left[

```yaml
---
output: html_document
---
```

```yaml
---
output:
  html_document:
    toc: true
---
```

]

.pull-right[

]

---
class: your-turn

# Your turn

## Edit your YAML

Use `?html_document` from your R console to:

1. Add a floating table of contents

1. Add a theme

1. Use the "kable" method to print data frames (more on this later!)

🧶 **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..._

---
class: your-turn

# Answers

```yaml
---
output:
  html_document:
    toc: true
    toc_float: true
    theme: flatly
    df_print: kable
    code_download: true
---
```

---
class: inverse, center, middle

2

# Text

---

# <center>Headers</center>

.pull-left[
```markdown
# HEADER 1

## HEADER 2

### HEADER 3

#### HEADER 4

##### HEADER 5

###### HEADER 6
```
]

.pull-right[
# HEADER 1

## HEADER 2

### HEADER 3

#### HEADER 4

##### HEADER 5

###### HEADER 6
]

---

![](images/rmd-nav.png)

---

# <center>Text</center>

.pull-left[
```markdown
Childhood **vaccines**  
are one of the  
_great triumphs_  
of modern medicine. 
```
]

.pull-right[

Childhood **vaccines**  
are one of the  
_great triumphs_  
of modern medicine.

]

---
class: top

# <center>Lists</center>

.pull-left[

```markdown
Indeed, parents whose children are  
vaccinated no longer have to worry about  
their child's death or disability from:

- whooping cough, 
- polio, 
- diphtheria, 
- hepatitis, or 
- a host of other infections.

Vaccines are the most cost-effective health  
care interventions there are. We have   
three new, extremely effective vaccines to  
roll out in developing countries:

1. pneumonia
1. rotavirus
1. meningitis A
```

]

.pull-right[

Indeed, parents whose children are  
vaccinated no longer have to worry about  
their child's death or disability from:

- whooping cough, 
- polio, 
- diphtheria, 
- hepatitis, or 
- a host of other infections.

Vaccines are the most cost-effective health  
care interventions there are. We have  
three new, extremely effective vaccines to  
roll out in developing countries:

1. pneumonia
1. rotavirus
1. meningitis A

]

---

# <center>Images</center>

.pull-left[
```markdown
Receiving rubella vaccination, Brazil, 2008.
![](http://bit.ly/VaccineBySandraRugio)
```
]

.pull-right[
Receiving rubella vaccination, Brazil, 2008.
![](http://bit.ly/VaccineBySandraRugio)
]

---

# <center>Links</center>

.pull-left[
```markdown
[Photo](https://en.wikipedia.org/wiki/Vaccine)

Receiving rubella vaccination, Brazil, 2008.
![](http://bit.ly/VaccineBySandraRugio)
```
]

.pull-right[
[Photo](https://en.wikipedia.org/wiki/Vaccine)

Receiving rubella vaccination, Brazil, 2008.
![](http://bit.ly/VaccineBySandraRugio)
]

---
name: 03-formative
class: middle

# Pop quiz

.pull-left[

How do you add headers in Markdown?

`! Header`

`- Header`

`# Header`

`1. Header`

]

.pull-right[

What about lists? Bulleted? Numbered?

`! Item 1`

`- Item 1`

`# Item 1`

`1. Item 1`

]

---
class: inverse, center, middle

3

# code

---

# Code chunks

.pull-left[

````
```{r}
mockdata %>% 
  distinct(arm)
```
````

What is the fate of this chunk?

]

.pull-right[

```r
mockdata %>% 
 distinct(arm)
#> # A tibble: 3 x 1
#> arm 
#> <chr> 
#> 1 A: IFL 
#> 2 F: FOLFOX
#> 3 G: IROX
```

]

---

# Code chunks

.pull-left[

````
```{r}
n_sites <- n_distinct(mockdata$site)
```
````

What fate do you predict here?

]

.pull-right[

```r
n_sites <- n_distinct(mockdata$site)
```

]

---

# Code chunks

.pull-left[

````
```{r}
n_sites <- n_distinct(mockdata$site)
n_sites
```
````

]

.pull-right[

```r
n_sites <- n_distinct(mockdata$site)
n_sites
#> [1] 1
```

]

---

# Code chunks

.pull-left[

````
```{r}
ggplot(mockdata, aes(x = arm, 
                     y = n, 
                     fill = arm)) +
  geom_col()
```
````

What about this one?

]

.pull-right[

```r
ggplot(mockdata, aes(x = arm, 
                     y = n, 
                     fill = arm)) +
  geom_col()
```

]

---

# Add chunks

button or

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

Ctrl + Alt + `i` (Windows/Linux)

---

# Run chunks

.pull-left[
interactively (show button)
]

.pull-right[
whole doc (knit button or run all chunks or )
]

---
class: inverse, center, middle

4

# Output

---

# Chunk options

.pull-left[

````
```{r}
glimpse(mockdata)
```
````

]

.pull-right[

```r
glimpse(mockdata)
#> Observations: 3
#> Variables: 5
#> $ arm <chr> "A: IFL", "F: FOLFOX", "G: IROX"
#> $ site <chr> "Boston", "Boston", "Boston"
#> $ country <chr> "USA", "USA", "USA"
#> $ n_target <dbl> 34, 34, 34
#> $ n <dbl> 20, 13, 17
```

]

---

# echo

.pull-left[

````
```{r echo=FALSE}
glimpse(mockdata)
```
````

]

.pull-right[

```
#> Observations: 3
#> Variables: 5
#> $ arm <chr> "A: IFL", "F: FOLFOX", "G: IROX"
#> $ site <chr> "Boston", "Boston", "Boston"
#> $ country <chr> "USA", "USA", "USA"
#> $ n_target <dbl> 34, 34, 34
#> $ n <dbl> 20, 13, 17
```

]

---

# eval

.pull-left[

````
```{r eval=FALSE}
glimpse(mockdata)
```
````

]

.pull-right[

```r
glimpse(mockdata)
```

]

---

# include

.pull-left[

````
```{r include=FALSE}
glimpse(mockdata)
```
````

]

.pull-right[

]

---

# Chunk options

.pull-left[

````
```{r echo=TRUE, results='hide'}
glimpse(mockdata)
```
````

]

.pull-right[

```r
glimpse(mockdata)
```

]

+ 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)

---

.left-column[
# Default options
]

.right-column[

```r
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-rmd-anatomy_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-rmd-anatomy_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 labels

.pull-left[

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

]

.pull-right[

+ Place between curly braces `{r label}`

+ Separated options with commas `{r label, option1=value}`

+ Careful! No duplicate chunk labels

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

```
 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

---
class: middle, center

# Pet or livestock?

.footnote[https://masalmon.eu/2017/08/08/chunkpets/]

---
class: middle, center

# A good chunk label

.pull-left[

### Good

`myplot`

`my-plot`

`myPlot`

`myplot1`

]

.pull-right[

### Bad

`my_plot`

`my plot`

everything else!

]

---

# The setup chunk

.pull-left[

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

]

.pull-right[

+ A special chunk label: `setup`

+ Typically the first chunk

+ 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

]

---
class: your-turn

# Your turn

## New data dump! 📰

Data from more sites just came in &mdash; we now have data for Boston, Seattle, and Denver.

1. Replace `mockboston` in the file `mockbsd`.

1. 🧶 **Knit** to HTML. Do you see data for all 3 sites?

1. Clean up the chunks (split, combine, label, use options as you see fit)

1. Use the RStudio outline pane; rejoice!

**If this was easy**, try to use a parameter for the data file.

_psst...`01-explore-alison-params.Rmd` is still there..._

---
class: middle, center

# 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

---
class: middle, center

# ⏱

# Time for a break!