Reproducible reports with RMarkdown

class: title-slide, inverse, bottom
background-image: url(img/gradient-background.png)
background-size: cover

# Reproducible reports with RMarkdown
### CFE R Training - Module 4

<br/>

María Paula Caldas and Jolien Noels

---
class: middle

# Useful links

[Slides](https://oecd-cfe-eds.github.io/cfe-r-training/04_rmarkdown.html), if you want to navigate on your own

[RStudio Project](https://rstudio.cloud/project/2989711), to try out the exercises

[Teams Space](https://teams.microsoft.com/l/team/19%3aewi8FvNssJHrCsxFDSJbA7IL4q4kGH0E8IRMfMp8zPA1%40thread.tacv2/conversations?groupId=c957fd70-0f85-4bcc-b3a4-e453919316de&tenantId=ac41c7d4-1f61-460d-b0f4-fc925a2b471c), for discussions

[Github repository](https://github.com/mpaulacaldas/cfe-r-training), for later reference

---
class: middle

# Housekeeping matters

🙋‍♀️&nbsp; During the session, ask questions in the chat 
or raise your hand

📷&nbsp; Sessions are recorded. Remember to turn off your camera if 
its your preference

💬&nbsp; After the session, post follow-up questions, 
comments or reactions in the [Teams space](https://teams.microsoft.com/l/team/19%3aewi8FvNssJHrCsxFDSJbA7IL4q4kGH0E8IRMfMp8zPA1%40thread.tacv2/conversations?groupId=c957fd70-0f85-4bcc-b3a4-e453919316de&tenantId=ac41c7d4-1f61-460d-b0f4-fc925a2b471c)

📝&nbsp; If you are going through these slides on your own, type `p` 
to see the presenter notes

???

The presenter notes are where you might also find OECD or CFE specific 
information.

---
class: middle

# Learning objectives for today

1. Understand what RMarkdown is and its many implementations.

1. Understand how Markdown, YAML and R code are used together to make a report.

1. Learn how to leverage the `params` arguments to parametrise reports.

---
class:inverse, bottom, left

# Introduction
## What is RMarkdown?

---
background-image: url(https://github.com/rstudio/rmarkdown/blob/main/man/figures/logo.png?raw=true)
background-position: 1050px 20px
background-size: 100px

# What is RMarkdown?

It is an **authoring framework** for data science, that combines:

- Prose
- Code
- Results

The term _RMarkdown_ can also make reference to:

- 📄&nbsp;  A file format (`.Rmd`)
- 📦&nbsp; The [`rmarkdown`](https://pkgs.rstudio.com/rmarkdown/) package.

---
# How does the process work?

.pull-left[
### As programmers, we...

1. Create an `.Rmd` file.
1. Write prose and R code
1. Specify rendering parameters
1. *Knit* the document, by clicking on a button

]

.pull-right[

### Behind the scenes...

**rmarkdown** processes the `.Rmd` file using [knitr](https://github.com/yihui/knitr/) and [pandoc](https://pandoc.org/)

.center[![](https://es.r4ds.hadley.nz/images/RMarkdownFlow.png)]
]

---
# Why RMarkdown?
## Reproducibility

---
# Why RMarkdown?
## Multiple output formats

.panelset.sideways[

.panel[.panel-name[Traditional]

- PDF
- HTML
- Word
- PowerPoint

]

.panel[.panel-name[Slides]

[xaringan](https://github.com/yihui/xaringan), an RMarkdown extension based on [remark.js](https://remarkjs.com)

<div class="shareagain" style="min-width:300px;margin:1em auto;max-width:560px;">
<iframe src="https://oecd-cfe-eds.github.io/cfe-r-training/01_intro.html" width="1600" height="900" style="border:2px solid currentColor;" loading="lazy" allowfullscreen></iframe>
<script>fitvids('.shareagain', {players: 'iframe'});</script>
</div>

]

.panel[.panel-name[Books]

[bookdown](https://bookdown.org/), to write HTML, PDF, ePub and Kindle books with RMarkdown.

Some examples:

- [R for Data Science](https://r4ds.had.co.nz/)
- [Geocomputation with R](https://geocompr.robinlovelace.net/)

]

.panel[.panel-name[Websites]

[blogdown](https://pkgs.rstudio.com/blogdown/), an extension based on Hugo.

[distill](https://pkgs.rstudio.com/distill/), a format optimised for scientific and technical communication.

[postcards](https://github.com/seankross/postcards), for personal landing pages.

]

---
# Why RMarkdown?
## Multiple output formats

.pull-left[
<iframe width="560" height="315" src="https://www.youtube.com/embed/_D-ux3MqGug" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
]
.pull-right[
<iframe width="560" height="315" src="https://www.youtube.com/embed/qLEkUjxk7e8" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
]

---
class: exercise

# 📝&nbsp; Create and knit an `.Rmd`

Let's try these out at the same time in the [RStudio Cloud Project](https://rstudio.cloud/project/2989711).

1. Create an`.Rmd` from the RStudio IDE.

1. *Knit* the document.

1. Make some changes, knit again.

---
class:inverse, bottom, left

# Markdown, R and YAML
## (Text, code and metadata)

---

# YAML parameters

.pull-left[
- They are defined at the beginning of `.Rmd` files

- They control the output file format (e.g. PDF, Word, HTML)

- And the different options for each file format
]

.pull-right[

```markdown
*---
*title: "Country note: Korea"
*author: "CFE/EDS"
*date: "2021-10-07"
*output: 
*  html_document:
*    theme: yeti
*    toc: true
*    toc_float: true
*  word_document: default
*---

## Labour productivity in Korea

Labour productivity is measured as GDP 
per hour worked. In Korea, the most 
productive region...
```

]

---
class: exercise

# 📝&nbsp; YAML parameters

## Instructors demonstrate...

- How to find the different output options for `html_document`
- Knitting an `.Rmd` to different type of outputs

## You do...

In the [RStudio Cloud Project](https://rstudio.cloud/project/2989711):

- Create a new `.Rmd` file from RStudio
- Choose `html_document` as output option
- Add a floating table of contents
- Change the output option to `word_document`
- Add a table of contents, and number the sections

---
# Markdown syntax

.panelset[

.panel[.panel-name[Headers]

.pull-left[

```md
# First level
## Second level
### Third level
#### Fourth level
```

].pull-right[

# First level
## Second level
### Third level
#### Fourth level
  
]

]

.panel[.panel-name[Text]

.pull-left[

```md
Another option to ~~crochet~~
_knit_ an `.Rmd` document is 
using the `render()` function
from the __rmarkdown__ package.

But most of the time, the 
easiest way to go about it is 
using the _Knit_ button in 
RStudio, or the keyboard 
shortcut `Ctrl + Shift + K`
```

].pull-right[

Another option to ~~crochet~~
_knit_ an `.Rmd` document is 
using the `render()` function
from the __rmarkdown__ package.
But most of the time, the 
easiest way to go about it is 
using the _Knit_ button in 
RStudio, or the keyboard 
shortcut `Ctrl + Shift + K`
]

]

.panel[.panel-name[Lists]

.pull-left[

```md
- One item
- Another item
  - A sub-item
  - Another sub-item

1. Item 1
1. Item 2
1. Item 3
```

].pull-right[

- One item
- Another item
  - A sub-item
  - Another sub-item

1. Item 1
1. Item 2
1. Item 3

]

<br/>

> 💡&nbsp; You are not required to keep the count in numbered lists.
]

.panel[.panel-name[Images]

.pull-left[

```md
![Alt text](https://github.com/rstudio/rmarkdown/raw/master/man/figures/logo.png)
```

].pull-right[
.center[
![A judge’s desk labeled “Reproducibility” with a witness stand right next to it. On the witness stand is a smiling and confident R Markdown document pointing at some lines of code on itself. A fuzzy monster lawyer in a polka-dot tie stands proudly saying “Nothing further!” The judge (also a cute fuzzy monster) is smiling with their hands raised in celebration of reproducible work.](https://github.com/allisonhorst/stats-illustrations/blob/master/rstats-artwork/reproducibility_court.png?raw=true)
]
]

> 🙋&nbsp; What is the use of the text inside the square brackets?
]

.panel[.panel-name[Links]

.pull-left[

```md
[RStudio's RMarkdown lessons](https://rmarkdown.rstudio.com/lesson-1.html)
```
<br/>

```md
<https://rmarkdown.rstudio.com/lesson-1.html>
```

].pull-right[

[RStudio's RMarkdown lessons](https://rmarkdown.rstudio.com/lesson-1.html)

<br/>

<https://rmarkdown.rstudio.com/lesson-1.html>

]

???

In the RStudio IDE, you can always go to: Help -> Markdown quick reference for a list of these rules.

---
class: exercise

# 📝&nbsp; Markdown syntax

In the [RStudio Cloud Project](https://rstudio.cloud/project/2989711):

1. Create a new `.Rmd` using the RStudio IDE, or use a previous one.

1. In the top of the RStudio IDE, go to _Help_ -> _Markdown Quick Reference_.

1. Using the reference, add the following elements to your document:
  - A footnote.
  - A block quote.
  - A table.

---
# Inline R code

.pull-left[

```markdown
### Connectivity report

_Date of last update: `r Sys.Date()`_

With fixed average download speeds at 
145 Mbps, people living in Xyz 
experience actual fixed Internet 
speeds `r scales::percent((145/119) - 1)`
above the OECD average.
```
]

.pull-right[

### Connectivity report

_Date of last update: 2021-10-07_

With fixed average download speeds at 
145 Mbps, people living in Xyz 
experience actual fixed Internet 
speeds 22%
above the OECD average.

]

---

# R code chunks

.panelset[

.panel[.panel-name[Objects]

.pull-left[

````markdown
### Connectivity report

_Date of last update: `r Sys.Date()`_

```{r, echo = FALSE}
xyz  <- 145
oecd <- 119
rate <- (xyz/oecd - 1)
```

With fixed average download speeds at 
`r xyz` Mbps, people living in Xyz 
experience actual fixed Internet 
speeds `r scales::percent(rate)`
above the OECD average.
````

]

.pull-right[

### Connectivity report

_Date of last update: 2021-10-07_

With fixed average download speeds at 
145 Mbps, people living in Xyz 
experience actual fixed Internet 
speeds 22%
above the OECD average.

]

.panel[.panel-name[Figures]

.pull-left[

````markdown
```{r}
library(ggplot2)
df <- data.frame(
  region = c("Xyz", "OECD"),
  speed  = c(145, 119))
ggplot(df, aes(region, speed)) + 
  geom_col()
```
````
]

.pull-right[

```r
library(ggplot2)
df <- data.frame(
  region = c("Xyz", "OECD"),
  speed  = c(145, 119))
ggplot(df, aes(region, speed)) + 
  geom_col()
```

]

.panel[.panel-name[Tables]

.pull-left[

````markdown
```{r}
df # printed
```

```{r}
knitr::kable(df) # rendered
```
````
]

.pull-right[

```r
df # printed
#>   region speed
#> 1    Xyz   145
#> 2   OECD   119
```

```r
knitr::kable(df) # rendered
```

|region | speed|
|:------|-----:|
|Xyz    |   145|
|OECD   |   119|

]

---

# Chunk options

Chunk options control the output of chunks. They can be used to determine if the code is executed, printed, or if its results are displayed in the final document.

.pull-left[
````
*```{r, eval = FALSE}
ggplot(df, aes(region, speed)) + 
  geom_col()
```
````
]

.pull-right[

- You set them at the top of the chunk <br>`{r option = value}`

- Options are separated by commas<br>`{r opt1 = value1, opt2 = value2}`

]

.footnote[
.small[
📖&nbsp; [Chapter 27, R4DS](https://r4ds.had.co.nz/r-markdown.html#chunk-options)
]
]

---

# Most common options

.panelset[

.panel[.panel-name[eval]

`eval = FALSE` shows the code, but doesn't evaluate it.

.pull-left[

````
*```{r, eval = FALSE}
nrow(df)
```
````
]

.pull-right[

```r
nrow(df)
```

]

.panel[.panel-name[echo]

`echo = FALSE` hides the code chunk from the output, but it executes the code and prints its results.

.pull-left[

````
*```{r, echo = FALSE}
df # printed
knitr::kable(df) # rendered
```
````

]

.pull-right[

```
#>   region speed
#> 1    Xyz   145
#> 2   OECD   119
```

|region | speed|
|:------|-----:|
|Xyz    |   145|
|OECD   |   119|
]

]

.panel[.panel-name[include]

`include = FALSE` executes teh code in the chunk, but doesn't print the code or its results.

The objects created in the block remain available to be used later in the document.

.pull-left[

````markdown
*```{r, include = FALSE}
df <- data.frame(
  region = c("Xyz", "OECD"),
  speed  = c(145, 119))

df
nrow(df)
```

We have data for `r nrow(df) - 1` country.
````
]

.pull-right[

We have data for 1 country.

]

---
class: exercise

# 📝&nbsp; Putting it all together

Head to the [RStudio Cloud Project](https://rstudio.cloud/project/2989711)

Modify `starting-point.Rmd` so you get an output file that looks exactly like `goal.html`

---
class: inverse, bottom, left
background-image: url(https://images.unsplash.com/photo-1421986872218-300a0fea5895?ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&ixlib=rb-1.2.1&auto=format&fit=crop&w=634&q=80)
background-size: cover

# Break

---
class:inverse, bottom, left

# Parametrised reports

---
# Parametrised reports

You can __parametrise__ RMarkdown documents further by setting the `params` parameter in the YAML header.

This can be useful to:

- Highlight important metadata of the document
    - This is what we do, for example, to control the RStudio Cloud links in the present slides.

- To create a template that can be used to produce similar documents that change depending on parameters.

---
# The `params` parameter

.pull-left[

````markdown
---
title: "Status report"
output: html_document
params:
  country: "Xyz"
  tl: "TL2"
---

```{r, include = FALSE}
library(cfe)
indicators <- read_status(params$country, params$tl)
```

In `r indicators$year`, `r params$country` 
reported download speeds between 
`r min(indicators$speed)` Mbps and 
`r max(indicators$speed)` Mbps 
across its `r params$tl` regions.

````

]

.pull-right[

### Status report

In 2021, Xyz reported average download speeds 
between 60Mpbs and 180Mbps across its TL2 
regions.

]

---
class: exercise

# 👩‍💻&nbsp; Demo: Parametrised country notes

The code used in this demonstration is in the [RStudio Cloud project](https://rstudio.cloud/project/2989711).

---
class: inverse, bottom, left
background-image: url(img/gradient-background.png)
background-size: cover

# Annex

---
# More exercises

The __OECD lunch::houR()__ had two sessions dedicated to RMarkdown. The materials from the sessions are available in the [Algobank](https://algobank.oecd.org:4430/Philip.CHAN/lunch-hour-materials/-/tree/master/).

The __Tidyverse Certification Exam__ has an exercise where you are asked to [fix an `.Rmd` that is not working](https://education.rstudio.com/blog/2020/02/instructor-certification-exams/#question-2-1). It uses many of the tidyverse concepts we have covered so far, and introduces the `params` parameter.

---

# Books

.pull-left[

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

]
.pull-right[

[R Markdown Cookbook](https://bookdown.org/yihui/rmarkdown-cookbook/)

]

---
# On the opportunities and challenges

__Ana Moreno__ is looking for examples of OECD documents produced in R Markdown. If you want to know of or want to contribute, answer in [this thread](https://community.oecd.org/thread/29197).

__Romain Lesur__, the Head of Innovation at INSEE spoke on the _"Benefits and challenges of using RMarkdown in organisations"_ at the OECD R/Python/Algobank CoP. You can find his [slides](https://community.oecd.org/events/5062) in the CoP website and a [recording](https://oecd.sharepoint.com/teams/2020-Z8LFL7/Shared%20Documents/General/Recordings/R_Py_Ab%20CoP%20--%20R%20Markdown_%20benefits%20and%20challenges,%20Romain%20Lesur,%20INSEE-20210609_103033-Meeting%20Recording.mp4) in the [CoP Teams Space](https://teams.microsoft.com/l/team/19%3ae428d079b787461faf343cbbdbe9e9e0%40thread.tacv2/conversations?groupId=5b15779a-6a99-4cc0-bd60-778ed62d453d&tenantId=ac41c7d4-1f61-460d-b0f4-fc925a2b471c).