Advanced R Markdown

class: title-slide, center, middle

02

# Advanced R Markdown

## Young Statisticians Conference 2019

### Alison Hill &#183; RStudio

#### [https://ysc-rmarkdown.netlify.com/](https://ysc-rmarkdown.netlify.com/)

---
class: middle, center

#

# Go here and log in (free):

[http://bit.ly/ysc-rmarkdown](http://bit.ly/ysc-rmarkdown)

---
layout: true

<div class="my-footer">https://ysc-rmarkdown.netlify.com/</div>

---

.left-column[

 
 ?
 
]

.right-column[

# How does R Markdown work?

1. 🤷

1. I press knit, a document appears, and I believe that anything happening in between could be actual magic.

1. `knitr` executes the code and converts `.Rmd` to `.md`; **Pandoc** renders the `.md` file to the output format you want.

]

---
class: top

.left-column[

 
 ?

]

.right-column[

# How *does* R Markdown work?

1. 🤷 (✔️)

1. ["I press knit, a document appears, and I believe that anything happening in between could be actual magic."](https://twitter.com/allison_horst/status/1070323369600442368?s=20) (🧙‍♂️)

1. `knitr` executes the code and converts `.Rmd` to `.md`; **Pandoc** renders the `.md` file to the output format you want. (✔️)

]

---
class: middle, center

> "In a nutshell, R Markdown stands on the shoulders of `knitr` and **Pandoc**.

> The former executes the computer code embedded in Markdown, and converts R Markdown to Markdown.

> The latter renders Markdown to the output format you want (such as PDF, HTML, Word, and so on)."

> &mdash; [R Markdown: The Definitive Guide](https://bookdown.org/yihui/rmarkdown/)

---
class: center, middle

# Foreshadowing

---
class: pop-quiz

# Pop quiz

Which of the following is **NOT** a part of R Markdown basic anatomy?

1. Metadata

1. Text

1. CSS

1. Code

1. Output

---
class: your-turn

# Your turn

## Mad libs style &mdash; with a neighbor

```markdown
 ___________ is written at the top between `---` in ________.
    noun                                             syntax
                                                     
  ______ is written in Markdown.
   noun         
  
  ______ is written in R (or other programming language).
   noun   
   
  The ______ package evaluates the code and produces the ______.
       noun                                               noun
```

_psst: answers on next slide..._

---
class: your-turn

# Your turn

## Answers

```markdown
 Metadata is written at the top between `---` in YAML.
   (noun)                                      (syntax)
                                                     
  Text is written in Markdown.
 (noun)         
  
  Code is written in R (or other programming language).
 (noun)   
   
  The knitr package evaluates the code and produces the output.
     (noun)                                             (noun) 
```

---

.left-column[

#

]

.right-column[

# Go here:

[https://github.com/ysc2019-workshop/02-advanced](https://github.com/ysc2019-workshop/02-advanced)

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

]

---

.left-column[

#

]

.right-column[

# In your repo

Click on green button, then the clipboard to copy HTTPS

<img src="images/cloud-from-https.png" width="3840" />
]

---

.left-column[

#

]

.right-column[

# Go to rstudio.cloud:

[http://bit.ly/ysc-rmarkdown](http://bit.ly/ysc-rmarkdown)

1. Join space > Click on "Projects" (nothing there)

1. New Project from GitHub Repo

1. Use **your** HTTPS link:

1. Name your project

]

---

.left-column[

#

]

.right-column[

# Last step!

I promise! Still in rstudio.cloud:

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

]

---
class: your-turn

# Your turn

Find a partner and look at `02-bakeoff-finales.Rmd` together. 
Look at the source, then 🧶 **Knit**.

Answer the following questions:

1. What is the output **format**?

1. Are there any output **options**?

1. Are any `knitr` **global** chunk options set?

1. Anything in the code look foreign to you?

1. Anything in the output (or not in the output) surprise you?

---
class: middle, center, inverse

1

# Output formats

---
class: middle, center

???

Built in formats (in the `rmarkdown` package)

versus

extensions (different packages that extend output formats available to you)

---
class: middle, center

https://rmarkdown.rstudio.com/docs/reference/index.html#section-output-formats

---
class: your-turn

# Your turn

## Use a different built-in format

.pull-left[

Use the drop-down menu for the 🧶 **Knit** button and try:

1. Knit to Word

1. Knit to PDF

]

.pull-right[
<img src="images/knit-dropdown.png" width="60%" style="display: block; margin: auto;" />

]

---

# Temp check 🌡

Do you have new output formats in your YAML?

```yaml
---
output:
  html_document:
    toc: true
    toc_float: true
    theme: flatly
  word_document:
    toc: true
  pdf_document:
    toc: true
---
```

???

This is a great way to "control" your knit button!

Notice that when you knit, it respects those output options in your YAML.

This way you "save" your output options

---

# What is hard about YAML?

.pull-left[
![](https://media.giphy.com/media/Nt2cPxzpKhbCE/giphy.gif)
]

.pull-right[
+ Indentations matter

+ Rarely informative error messages

+ Knowing which output options are relevant for different formats (i.e., Word, PDF, HTML, etc.)

+ Easy to forget the right `key`

+ Easy to forget the possible `values` for a given `key`
]

---
class: your-turn

# Your turn

## Use an extension package

.pull-left[

1. Edit your YAML again! Change the `output:` key to only `bookdown::html_document2`

1. Save the document; click on the dropdown 🧶 **Knit** button- what do you notice?

1. 🧶 **Knit** to html_document2.

]

.pull-right[
```yaml
---
output:
  bookdown::html_document2:
    toc: true
    toc_float: true
    theme: flatly
---
```
]

.footnote[(note: this requires you to install the [`bookdown` package](https://bookdown.org/yihui/bookdown/) on your own computer)]

---
class: live-code

# Adding figure auto-numbering & captions

Together we:

1. Label that chunk

1. Add a cross-reference like see Figure `\@ref(fig:pretty-plot)`

1. Try with `finale-scatterplot` code chunk: see Figure `\@ref(fig:finale-scatterplot)` (watch what happens if try to cross-reference without a caption!)

.footnote[Cross-referencing only works in these output packages: distill, bookdown, blogdown]

---
class: your-turn

# Your turn

## Use another extension package

1. Edit your YAML again! Add the output format `distill::distill_article`

1. Save the document; click on the dropdown 🧶 **Knit** button- what do you notice?

1. 🧶 **Knit** to distill_article.

**If this was easy**, add a table of contents too.

_psst...answers on the next slide..._

.footnote[(note: this requires you to install the [`distill` package](https://rstudio.github.io/distill/) on your own computer)]

???

At this point, I'm going to stick with the distill_article output format for the rest of this session.

---
class: your-turn

# Your turn

## Answer

```yaml
---
output:
  distill::distill_article:
    toc: true
---
```

---
class: middle

# Pop quiz

.pull-left[
How do you add a single output **format** to your YAML?

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

]

.pull-right[
How do you add an output **option** to a format in your YAML?

```yaml
---
output: 
  html_document: 
    toc: true
---
output: 
  html_document(toc=true)
---
```

]

---
class: middle

# Pop quiz

.pull-left[
How do you add another output **format** to your YAML?

```yaml
---
output: 
  html_document: default
  word_document: default
---
output: 
  html_document()
  word_document()
---
```

]

.pull-right[
How do you now add output **options** to your YAML?

```yaml
---
output: 
  html_document: 
    toc: true
  word_document: default
---
output: 
  html_document(toc=true)
  word_document(default)
---
```

]

---
class: middle, center, inverse

2

# Command line

---
class: middle, center

# Rendering

.pull-left[

So far: 🧶

]

.pull-right[

```r
render("02-bakeoff-finales.Rmd")
```

]
---
class: your-turn

# Your turn

Instead of using the "Knit" button, try running this code in your R console:

```r
library(rmarkdown) # needs to be loaded first
render("02-bakeoff-finales.Rmd")
```

Now try changing the parameters:

```r
render("02-bakeoff-finales.Rmd",
       params = list(series = "9"))
```

__If this was easy__, play with the other parameters too. Or see if you can change the output format, and add output options.

_psst...answers on the next slide..._

---
class: your-turn

# Answer

```r
render("02-bakeoff-finales.Rmd",
       params = list(series = "9"), 
       output_format = distill::distill_article(toc = TRUE))
```

---
class: middle, center, inverse

3

# Render loops

---
class: live-code

# We loop together

```r
# the setup
series <- sort(unique(ratings$series))

# the loop
for (this_series in series) {
  render("02-bakeoff-finales.Rmd",
         params = list(series = this_series))
}
```

_psst...the wrong way_

---

---

# We need two things

For the `rmarkdown::render()` function to work they way we want:

1. The list of series -> `params`

1. The name of each report -> `output_file`

We could do this with a loop, but let's start **purrr**ing...

---
class: center, middle, inverse

> "Of course someone has to write **loops**.

> It doesn't have to be _you_.

> &mdash; Jenny Bryan

---

---

---

# Rendering multiple reports

```r
# the setup

paths <- paste0("series-", series)

# series needs to be a list
series <- sort(unique(ratings$series))
params <- map(series, ~ list(series = .x))
str(params)
```

```r
walk2(
  paths, params,
  ~ rmarkdown::render("02-bakeoff-finales.Rmd", output_file = .x, params = .y)
)
```

---
class: your-turn

# Your turn

Try to get this set-up working locally for you.

```r
# the setup

paths <- paste0("series-", series)

# series needs to be a list
series <- sort(unique(ratings$series))
params <- map(series, ~ list(series = .x))
str(params)
```

```r
walk2(
  paths, params,
  ~ rmarkdown::render("02-bakeoff-finales.Rmd", output_file = .x, params = .y)
)
```

---
class: live-code

# Digging deeper

So now the output file name changed, but we can go deeper.

Let's say we'd also like the change the title in our YAML.

Let's do this together.

(make sure the below is in quotes)

```yaml
---
title: The Great British Bake Off, Series `r params$series`
---
```

---
class: your-turn

# Your turn

Use your render script again and check to make sure that the titles now have the series number in them.

It is good practice to save your rendering script in the project, call it `_render.R`.

---
class: middle, center

# 🍱

# Time for lunch!