Session 7: Introduction to R Markdown

.title[
# Session 7: Introduction to R Markdown
]
.subtitle[
## R for Stata Users
]
.author[
### DIME Analytics
]
.date[
### The World Bank – DIME | <a href="https://github.com/worldbank">WB Github</a> <br> March 2024
]

---

.remark-slide-content {
    font-size: 30px;
}
</style>

# Preamble

- Make sure you have the packages `tinytex`, `stargazer`, and `huxtable` installed

```r
# Package we used for other sessions, install only if needed
install.packages("huxtable")

# New packages
install.packages("tinytex")
install.packages("stargazer")

# No need to load the packages for now
```

---

# Preamble <font size="5">(<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M464 256A208 208 0 1 1 48 256a208 208 0 1 1 416 0zM0 256a256 256 0 1 0 512 0A256 256 0 1 0 0 256zM232 120V256c0 8 4 15.5 10.7 20l96 64c11 7.4 25.9 4.4 33.3-6.7s4.4-25.9-6.7-33.3L280 243.2V120c0-13.3-10.7-24-24-24s-24 10.7-24 24z"/></svg> 5 min)</font>

- Use `tinytex` to install LaTeX with: `tinytex::install_tinytex()`
- This will take a while. Leave it running:

- LaTeX can be unpredictable in WB computers. It's possible that this didn't work
- Don't worry for now, just follow the approppriate instructions we'll specify in the exercises

---

# Introduction

- This is an **introduction** to R Markdown
- We'll show:
  1. How to write and knit (output) R Markdown documents
  2. How to format text and R code in R Markdown documents
  3. How to include regression tables in R Markdown documents

---

# Table of contents

1. [Dynamic documents](#dynamic-documents)
2. [Knitting](#knitting)
3. [Markdown](#markdown)
4. [R code](#r-code)
5. [R plots](#r-plots)
6. [Inline code](#r-inline-code)
7. [Regression outputs](#regression-outputs)
8. [Annex](#annex)

---

# Dynamic documents

---

# Dynamic documents and R Markdown

- Dynamic documents are documents that include both text and code outputs
- They are generated by a script and are updated automatically every time the script runs
- R Markdown is a type of dynamic document

---

# Dynamic documents

- Code outputs and text are fully integrated

---

# Dynamic documents

- You can format the text and code outputs as much as you need

---

# Dynamic documents

- Each document element and formatting is defined by R and Markdown code
- You can define the document type you need

---

# Why use dynamic documents?

- Increased research transparency. Documents are fully reproducible
- No more copying and pasting outputs from R to a document editor
- Nice option for simple documents that don't require a lot of formatting, but you can also customize your documents as needed
- Can include code snippets

---

# Knitting R Markdown documents

---

# Knitting R Markdown documents

- R markdown combines text, R code, and rendered outputs
- The text follows Markdown's syntax
- The code and outputs follow R's syntax
- Knitting an R Markdown document is rendering the text and code portions into a single output
- The output can be a PDF, Word, HTML document, or others

---

# Knitting R Markdown documents

.exercise[
## Exercise 1: Knit an R Markdown document <font size="5">(<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M464 256A208 208 0 1 1 48 256a208 208 0 1 1 416 0zM0 256a256 256 0 1 0 512 0A256 256 0 1 0 0 256zM232 120V256c0 8 4 15.5 10.7 20l96 64c11 7.4 25.9 4.4 33.3-6.7s4.4-25.9-6.7-33.3L280 243.2V120c0-13.3-10.7-24-24-24s-24 10.7-24 24z"/></svg> 2 min, leave it running)</font>

1. Download the file `r-markdown-template.Rmd` from : https://osf.io/7g6t9/
1. Open this file in RStudio
  + If the installation of tinytex didn't work, change line 2 to: `output: html_document`
1. Click on `Knit`. If RStudio asks you to update some packages, select `Yes`
]

---

# Knitting R Markdown documents

Note that this might take a while

We'll continue with markdown syntax while it finishes

---

# Markdown

---

# Markdown

---

# Markdown

- The text part of R Markdown follows the syntax of Markdown
- Markdown is a "light" markup language. It's similar to Latex or HTML, but simpler
- Markdown was designed to be easily readable while allowing to format text and document sections

---

# Markdown - Headers

- Headers in markdown are preceded by pound (`#`) symbols
- Additional pound symbols denote a lower level in the headers hierarchy

---

# Markdown - Paragraphs

- Text not preceded by special symbols are regular paragraphs.

---

# Markdown - Text emphasis

- Emphasized text is enclosed by special symbols.

---

# Markdown - Lists

- Markdown allows us to use both ordered and unordered lists.

---

# Markdown - Lists

- Markdown allows us to use both ordered and unordered lists.

---

# Markdown - Links

- We can also include links as text in Markdown.

---

# Markdown - Tables

- Lastly, we can include tables in Markdown text.

---

# Markdown - Tables

- Lastly, we can include tables in Markdown text.

---

# Exercise 1 results

- If exercise 1 worked, you'll now see this PDF file (or HTML) in the folder where you saved `r-markdown-template.Rmd`

- If it's still running, let it run until it finishes
- If it failed, try again after changing `output: html_document` in line 2

---

# R Code

---

# Including R code

- R code in R Markdown goes inside **fenced code blocks**, as the one below

````
```{r}
# Your R code goes here
```
````

---

# Including R code

- To add new block, you can type the fences directly, or go to `Insert` > `R` in the script panel of RStudio, or type `CTRL` + `ALT` + `i`

---

# Including R code

.exercise[
## Exercise 2: Include the summary of a variable <font size="5">(<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M464 256A208 208 0 1 1 48 256a208 208 0 1 1 416 0zM0 256a256 256 0 1 0 512 0A256 256 0 1 0 0 256zM232 120V256c0 8 4 15.5 10.7 20l96 64c11 7.4 25.9 4.4 33.3-6.7s4.4-25.9-6.7-33.3L280 243.2V120c0-13.3-10.7-24-24-24s-24 10.7-24 24z"/></svg> 2 min)</font>

1. Create a header named `R Code` at the bottom of `r-markdown-template.Rmd`
2. Create a new fenced code block where you load the dataset `mtcars`
  + `mtcars` is a built-in dataset. Load it with: `data(mtcars)`
3. Inside the same block, get the summary of the variable `mpg` with `summary(mtcars$mpg)`
4. Knit. You'll have to **close the PDF document if you have it opened**
]

---

# Including R code

````
## R Code

```{r}
data(mtcars)
summary(mtcars$mpg)
```
````

---

# Including R code

---

# Including R code

- What about running only the code block and not knitting the document?
- You can do that with the <svg aria-hidden="true" role="img" viewBox="0 0 384 512" style="height:1em;width:0.75em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M73 39c-14.8-9.1-33.4-9.4-48.5-.9S0 62.6 0 80V432c0 17.4 9.4 33.4 24.5 41.9s33.7 8.1 48.5-.9L361 297c14.3-8.7 23-24.2 23-41s-8.7-32.2-23-41L73 39z"/></svg> icon at the upper right corner of the block
- The other icon (<svg aria-hidden="true" role="img" viewBox="0 0 384 512" style="height:1em;width:0.75em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M73 39c-14.8-9.1-33.4-9.4-48.5-.9S0 62.6 0 80V432c0 17.4 9.4 33.4 24.5 41.9s33.7 8.1 48.5-.9L361 297c14.3-8.7 23-24.2 23-41s-8.7-32.2-23-41L73 39z"/></svg><svg aria-hidden="true" role="img" viewBox="0 0 320 512" style="height:1em;width:0.62em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M48 64C21.5 64 0 85.5 0 112V400c0 26.5 21.5 48 48 48H80c26.5 0 48-21.5 48-48V112c0-26.5-21.5-48-48-48H48zm192 0c-26.5 0-48 21.5-48 48V400c0 26.5 21.5 48 48 48h32c26.5 0 48-21.5 48-48V112c0-26.5-21.5-48-48-48H240z"/></svg>) will run all previous code blocks until this block

---

# Including R code

- Note that the output echoes both the code and the output
- What if we wanted to include the output but not the code?
- We use the argument `echo = FALSE` in the fenced code block for that
- Code block arguments are separated by commas inside the curly brackets, as in: `{r, echo = FALSE}`

---

# Including R code

.exercise[
## Exercise 3: Omit the code when knitting R code <font size="5">(<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M464 256A208 208 0 1 1 48 256a208 208 0 1 1 416 0zM0 256a256 256 0 1 0 512 0A256 256 0 1 0 0 256zM232 120V256c0 8 4 15.5 10.7 20l96 64c11 7.4 25.9 4.4 33.3-6.7s4.4-25.9-6.7-33.3L280 243.2V120c0-13.3-10.7-24-24-24s-24 10.7-24 24z"/></svg> 1 min)</font>

1. Add the option `echo = FALSE` to the fenced code block created in exercise 2
2. Knit the document and see how it's different now
]

---

# Including R code

````
```{r, echo = FALSE}
data(mtcars)
summary(mtcars$mpg)
```
````

---

# Including R code

---

# Including R code

- To include only R code but not the output, we use the option `eval = FALSE`

````
```{r, eval = FALSE}
data(mtcars)
summary(mtcars$mpg)
```
````

---

# Including R code

---

# R Plots

---

# Including R plots

- Adding R plots is similar to adding R code
- Include the code producing the plot in a fenced block
- The block option `echo = FALSE` is useful when we only want to include the plot but not the code producing it

---

# Including R plots

.exercise[
## Exercise 4: Include an R plot in your document <font size="5">(<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M464 256A208 208 0 1 1 48 256a208 208 0 1 1 416 0zM0 256a256 256 0 1 0 512 0A256 256 0 1 0 0 256zM232 120V256c0 8 4 15.5 10.7 20l96 64c11 7.4 25.9 4.4 33.3-6.7s4.4-25.9-6.7-33.3L280 243.2V120c0-13.3-10.7-24-24-24s-24 10.7-24 24z"/></svg> 2 min)</font>

1. Create a header named `R Plots`
2. Create a new fenced code block with the option `echo = FALSE`
3. Add the following code inside the new block:

```r
plot(mtcars$wt,
     mtcars$mpg,
     main = "Plot example",
     xlab = "Car weight",
     ylab = "Miles per gallon")
```
]

---

# Including R plots

````
# R plots

```{r, echo = FALSE}
plot(mtcars$wt,
     mtcars$mpg,
     main = "Plot example",
     xlab = "Car weight",
     ylab = "Miles per gallon")
```
````

---

# Including R plots

---

# Inline code

---

# Including code inline

- Inline code  is enclosed by backtick followed by an r (``r`) and a single backtick
- For example:

~~~
The mean of mpg is `r mean(mtcars$mpg)`.
~~~

- Will be rendered as:

````
The mean of mpg is 20.090625.
````

- Note that inline code doesn't go enclosed in code blocks, it's just regular Markdown text

---

# Including code inline

.exercise[
## Exercise 5 <font size="5">(<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M464 256A208 208 0 1 1 48 256a208 208 0 1 1 416 0zM0 256a256 256 0 1 0 512 0A256 256 0 1 0 0 256zM232 120V256c0 8 4 15.5 10.7 20l96 64c11 7.4 25.9 4.4 33.3-6.7s4.4-25.9-6.7-33.3L280 243.2V120c0-13.3-10.7-24-24-24s-24 10.7-24 24z"/></svg> 2 min)</font>

1. Create a new header named `Inline code` in `markdown-template.Rmd`
2. Add an unordered list with the following text and include inline R code to render the corresponding numbers in each case
  + The number of elements in mtcars is: (use function `nrow(mtcars)`)
  + The mean of weight is: (use function `mean(mtcars$wt)`)
  + The standard deviation is: (use function `sd(mtcars$wt)`)
]

---

# Including code inline

~~~
# Inline code

- The number of elements in mtcars is `r nrow(mtcars)`
- The mean of weight is `r mean(mtcars$wt)`
- The standard deviation is `r sd(mtcars$wt)`
~~~

---

# Including code inline

---

# Including code inline

You can use the function `round()` to control the number of decimals displayed.

~~~
# Inline code

- The number of elements in mtcars is `r nrow(mtcars)`
- The mean of weight is `r round(mean(mtcars$wt), 1)`
- The standard deviation is `r round(sd(mtcars$wt), 2)`
~~~

---

# Including code inline

You can use the function `round()` to control the number of decimals displayed.

---

# Including code inline

You can also combine R inline code with the markdown syntax for tables to produce statistics tables.

~~~
# Inline code in tables

|Column: weight| Value                       |
|--------------|-----------------------------|
|N             |`r nrow(mtcars)`             |
|Mean          |`r round(mean(mtcars$wt), 1)`|
|SD            |`r round(sd(mtcars$wt), 2)`  |
~~~

---

# Including code inline

You can also combine R inline code with the markdown syntax for tables to produce statistics tables.

---

# Including regression outputs

---

# Including regression outputs

- In a previous session, we saw that we can produce regression tables in LaTeX
- We can use code producing LaTeX outputs along with the code block option `results = "asis"` to display them in the knitted document

---

# Including regression outputs - Stargazer

- First, we'll start with the function `stargazer()` from the package `stargazer`
- The first argument of `stargazer()` is a regression result
- We also include the arguments `echo = FALSE` and `message = FALSE` in the code block to omit printing the code and messages that appear when loading stargazer
- In `stargazer()` we include `header = FALSE` to omit printing stargazer metadata

**Important:** When using external packages in RMarkdown, you need to have them loaded in a code block regardless of if they're already loaded in your current session. Libraries have to load again for each knit.

---

# Including regression outputs - Stargazer

````
```{r, echo = FALSE, message = FALSE, results = "asis"}
# Loading stargazer
library(stargazer)

# Creating a simple regression
model <- lm(mpg ~ cyl + hp, data = mtcars)

# Printing it with stargazer
stargazer(model, header = FALSE) # add: type = "html" if knitting to HTML
```
````

---

# Including regression outputs - Stargazer

---

# Including regression outputs - Stargazer

.exercise[
## Exercise 6 <font size="5">(<svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M464 256A208 208 0 1 1 48 256a208 208 0 1 1 416 0zM0 256a256 256 0 1 0 512 0A256 256 0 1 0 0 256zM232 120V256c0 8 4 15.5 10.7 20l96 64c11 7.4 25.9 4.4 33.3-6.7s4.4-25.9-6.7-33.3L280 243.2V120c0-13.3-10.7-24-24-24s-24 10.7-24 24z"/></svg> 3 min)</font>

1. Create a new header named `Regressions - Stargazer` in `r-markdown-template.Rmd`
1. Add a new code block with the arguments `echo = FALSE` and `results = "asis"`
1. Load stargazer in the code block
1. Add a regression of the variable `mpg` on `wt` and `hp`
1. Use stargazer's arguments `header = FALSE`, `title = "your_title"` and `omit = c("Constant")` to customize your table
  + If your output is HTML instead of PDF, include the argument `type = "html"` in `stargazer()`
]

---

# Including regression outputs - Stargazer

````
# Regressions - Stargazer

```{r, echo = FALSE, message = FALSE, results = "asis"}
library(stargazer)
model <- lm(mpg ~ wt + hp, data = mtcars)
stargazer(model,
          header = FALSE,
          title = "Best table ever",
          omit = c("Constant"))
```
````

---

# Including regression outputs - Stargazer

---