Introduction to R Markdown

layout: true

<div class="footer-small">https://github.com/mjfrigaard/csuc-data-journalism</div>

---
name: title-slide
class: title-slide, center, middle, inverse

# Introduction to R Markdown
#.fancy[Combine text, code, and output in one document]

.large[by Martin Frigaard]

Written: October 03 2021

Updated: November 30 2021

.footer-large[.right[.fira[
 [Created using the "λέξις" theme](https://jhelvy.github.io/lexis/index.html#what-does-%CE%BB%CE%AD%CE%BE%CE%B9%CF%82-mean)
]]]

---

.footer-large[.right[Artwork by @allison_horst]]

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Materials

### Link to slides:

https://mjfrigaard.github.io/csuc-data-journalism/slides.html

### Link to exercises:

https://mjfrigaard.github.io/csuc-data-journalism/lessons-exercises.html

---
class: inverse, center
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# *What is RMarkdown?*

## Three technologies:

### 1) Markdown is a plain text markup language for capturing .blue[human-readable prose]

### 2) Data manipulation/graphing/statistical language engines for computing .blue[machine-readable code]

### 3) Multiple .blue[output options] for creating PDFs, Word docs, PowerPoints, HTML, etc.

---
class: center, top

# How R Markdown works

## `rmarkdown` works directly with `knitr`

.leftcol[

`rmarkdown` combines YAML, markdown, and R code into a markdown document and passes it to `knitr`

]

.rightcol[

`knitr` uses `pandoc` (a universal document conversion tool) to generate the specified document format

]

---
background-image: url(img/rmarkdown.png)
background-position: 95% 8%
background-size: 7%
class: inverse, middle, center

# Exercises

### We will create an example HTML report using the R Markdown template provided by RStudio

---
background-image: url(img/rmarkdown.png)
background-position: 95% 12%
background-size: 7%
class: left, top

# Exercise 1: create a new RMarkdown file

.leftcol[

### Click on .red[File] >

### then .red[New File] >

### then .red[R Markdown]

]

.rightcol[

***Or use the drop-down menu***

]

---
background-image: url(img/rmarkdown.png)
background-position: 93% 7%
background-size: 7%
class: left, top

# Install required packages

.leftcol[

If you're in a fresh RStudio.Cloud session, you *might* be asked to install the required packages for R Markdown, Click **Yes**

.border[

]]

.rightcol[

You will see RStudio installing the packages in the **Jobs** pane

.border[

]]

---
background-image: url(img/rmarkdown.png)
background-position: 93% 7%
background-size: 7%
class: middle

# New R Markdown File

### Enter ***'Title'*** and ***'Author'*** of your report and click ***OK***

.border[

]

---
background-image: url(img/rmarkdown.png)
background-position: 93% 7%
background-size: 7%
class: left, top

# Save your `.Rmd` file

### Click on the small floppy disk, enter a name (with .Rmd extension), and save your `.Rmd` file

---
background-image: url(img/rmarkdown.png)
background-position: 93% 7%
background-size: 7%
class: left, top

# Knit your .Rmd file

### Click on the small gear, select .blue[Preview in Viewer Pane]

### Click on the knit icon (ball of yarn)

---
background-image: url(img/rmarkdown.png)
background-position: 93% 7%
background-size: 7%
class: left, center

## Our First R Markdown Report!

.border[

]

---
background-image: url(img/rmarkdown.png)
background-position: 95% 8%
background-size: 7%
class: inverse, middle, center

# How R Markdown Works

## (under the hood)

---
background-image: url(img/how-rmd-works.png)
background-position: 50% 73%
background-size: 63%
class: top, center

# R Markdown is made up of three elements

---
class: left, top

# Rmarkdown combines metadata, markdown, *and* R code

.leftcol[

]

.rightcol[

`.yaml` = Metadata  
`.md` = Prose   
`.R` = Code

]

> The result is a file framework for creating reproducible reports using YAML, Markdown, and computer code

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# R Markdown: YAML

## `.yaml` = Metadata
### ~~`.md` = Prose~~  
### ~~`.R` = Code~~

### YAML is a human friendly data serialization standard for all programming languages.

### YAML stands for *'YAML Ain't Markup Language'* (funny, huh?)

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# R Markdown: YAML

### YAML contains the information about the document we're going to create

```yaml
---
title: "Monthly Report"
author: "Martin Frigaard"
date: "10/27/2020"
output: html_document
---
```

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# R Markdown: YAML format

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# R Markdown: YAML format

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# R Markdown: YAML

### There are many YAML arguments and options

### _Indentation matters in YAML!!_

> Check out the [YAML Fieldguide](https://cran.r-project.org/web/packages/ymlthis/vignettes/yaml-fieldguide.html) for a comprehensive list

---
background-image: url(img/rmarkdown.png)
background-position: 93% 7%
background-size: 7%

# Example YAML output options

## Table of contents:

### `toc:` logical (`true` or `false`)

### `toc_float:` logical (`true` or `false`)

### `toc_depth:` set numerically `0` - `6`

---
background-image: url(img/rmarkdown.png)
background-position: 7% 93%
background-size: 7%

# Exercise 2: create a floating table of contents

### Change the `output` in the YAML header to the following:

.leftcol40[

```yaml
output: 
  html_document: 
    toc: yes
    toc_float: true
```

]

.rightcol60[.center[

#### *Knit the document again*

]]

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# YAML output options: table of contents

### Floating table of contents (rendered)

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# Exercise 3: text highlighting and themes

### Add the following two options to your YAML header

.leftcol40[

```yaml
output: 
  html_document: 
    toc: yes
    toc_float: yes
    highlight: zenburn
    theme: united

```

]

.rightcol60[.center[

#### *Knit the document again*

]]

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# YAML: text highlighting and theme options

### Text highlighting and theme options (rendered)

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# More YAML options

### You can change the YAML contents using the settings (small gear)

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# Edit R Markdown Document Options

.leftcol[

#### This window gives us the ability to manually change some of the YAML settings (but not all of them!)

]

.rightcol[

]

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# YAML Parameters

### YAML parameters can be referred to throughout the document

.leftcol[

***Create `params` in YAML header***

```yaml
params: 
  param1: x
  param2: y
  data: df
```
]

.rightcol[

***Refer to `params` in .Rmd document***

```r
params$param1
params$param2
params$data
```
]

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# Exercise 4: Using YAML parameters

.leftcol40[

#### *Add the following `params` option in the YAML header*

.small[

```yaml
params: 
  small_pressure: !r head(pressure)
```

]]

.rightcol60[

#### *Add this code to the end of the document*

.border[

#### *Knit the document again!*

]]

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

## See our new plot with the `params`

We can see the new plot with the reduced sample size

.border[

]

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# YAML output formats

Function       | Outputs
-------------- | --------------------------
`html_document()`   | HTML document
`pdf_document()`  | PDF document
`word_document()` | Word document
`odt_document()`   | ODT document
`rtf_document()`   | RTF document
`md_document()`   | Markdown document
`slidy_presentation()`   | Slidy Slides (HTML)
`beamer_presentation()`   | Beamer Slides (PDF)
`ioslides_presentation()`   | ioslides (HTML)
`powerpoint_presentation()`   | PowerPoint (pptx)

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 15%

# R Markdown

### ~~`.yaml` = Metadata~~
## `.md` = Prose
### ~~`.R` = Code~~

---
background-image: url(img/markdown.png)
background-position: 93% 10%
background-size: 7%
class: left, top

# Basic Markdown Syntax

.leftcol30[.large[

#### Italics & Bold

```md
 *italic*   **bold**
 _italic_   __bold__
```

]]

.rightcol70[.center[.large[

*italic*   **bold**  
 _italic_   __bold__

]]]

---
background-image: url(img/markdown.png)
background-position: 93% 10%
background-size: 7%
class: left, top

# Basic Markdown Syntax

.leftcol[.large[

#### Headers

```md
# Header 1
## Header 2
### Header 3
```

]]

.rightcol[.large[.center[

# Header 1  
## Header 2  
### Header 3

]]]

---
background-image: url(img/markdown.png)
background-position: 93% 10%
background-size: 7%
class: left, top

# Basic Markdown Syntax

.leftcol40[

#### Bullets & Numeric Lists

```md
 * Item 1
 * Item 2
    + Item 2a
    + Item 2b
    
 1. Item 1
 2. Item 2
```

]

.rightcol60[.medium[

* Item 1  
* Item 2
    + Item 2a
    + Item 2b

1. Item 1
 2. Item 2
 
]]

---
background-image: url(img/markdown.png)
background-position: 93% 10%
background-size: 7%
class: left, top

# Basic Markdown Syntax

.leftcol55[

#### Hyperlinks

```md
https://www.biomarin.com/

[linked phrase](https://www.biomarin.com/)
```

]

.rightcol45[

#### *becomes...*

.center[.large[

[linked phrase](https://www.biomarin.com/)

]]]

---
background-image: url(img/markdown.png)
background-position: 93% 10%
background-size: 15%
class: left, top

# Basic Markdown Syntax

.leftcol55[

#### Images

.small[

```md
![](https://www.r-project.org/logo/Rlogo.png)

![optional caption](https://www.r-project.org/logo/Rlogo.png)
```

]]

.rightcol45[

#### *becomes...*

]

---
background-image: url(img/markdown.png)
background-position: 93% 10%
background-size: 7%
class: left, top

# Basic Markdown Syntax

.leftcol[

#### Math Equations

```md
$equation$

$$ equation $$
```

]

.rightcol[.large[

`$equation$`

$$ equation $$

]]

---
background-image: url(img/markdown.png)
background-position: 93% 10%
background-size: 7%
class: left, top

# Basic Markdown Syntax

.leftcol45[

#### Super scripts & Strike-through

```md
superscript^2^
~~strikethrough~~
```

]

.rightcol55[.center[

superscript^2^

~~strikethrough~~

]]

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# Exercise 5: Markdown Formatting

Delete the top portion of the markdown in `01-monthly-report.Rmd`.

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# Exercise 5: Markdown Formatting

.leftcol[

### Add the text below to your report

> *This is a monthly report generated with RMarkdown, a literate programming tool for combining text and code.*

]

.rightcol[

### Include the following formatting:

1. make `monthly report` italic  
2. include this hyperlink for `Rmarkdown`: https://rmarkdown.rstudio.com/
3. format `code` as code.

]

#### *Knit the document when you're finished*

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# Exercise 5: Markdown Formatting (rendered)

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Exercise 6: Tabsets

Remove the `toc` and `toc_float` options from your YAML header

```yaml
output: 
  html_document: 
    highlight: zenburn
    theme: united
params: 
  small_pressure: !r head(pressure)
```

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Exercise 6: Tabsets

Make the following changes to the `R Markdown` header sections

### Knit the document again

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Exercise 6: Tabsets (rendered)

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Exercise 6: Tabsets (rendered)

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 12%

# R Markdown

### ~~`.yaml` = Metadata~~
### ~~`.md` = Prose~~
## `.R` = Code

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Code chunks (`setup`)

### The first bit of R code in our RMarkdown file is the `setup` chunk

### Chunks named '`setup`' are special because they can set global options

### '`include=FALSE`' means this code is run, but not displayed

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Code chunks (`setup`)

### R Markdown document options come from the `knitr` package

### We can access both the with sytnax below:

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Code chunks (`setup`)

### The `echo=TRUE` option controls whether we want to display the code in the code chunk

### Other common options regarding code are `eval`, `tidy`, `error`, `message`, and `warning`

### Advanced options can control language engines (`engine`), caching (`cache`, `dependson`), and plot animations (`fig.show`)

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Code chunks (`setup`)

### Many options for code chunks

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Code chunks

.border[

]

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Code chunk fences

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Code chunk names and arguments

> See the [knitr web page](https://yihui.name/knitr/options/) for complete list of options

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Inserting code chunks

### Use keyboard shortcuts **CMD/CTRL + I** or **ALT/OPTION + I**

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Edit code chunk options

### You can edit code chunk options using the icon (small gear)

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Code Chunk Engines

## More and more code engines all the time

```r
names(knitr::knit_engines$get())
```

```
   [1] "awk"       "bash"      "coffee"    "gawk"      "groovy"    "haskell"  
   [7] "lein"      "mysql"     "node"      "octave"    "perl"      "psql"     
  [13] "Rscript"   "ruby"      "sas"       "scala"     "sed"       "sh"       
  [19] "stata"     "zsh"       "highlight" "Rcpp"      "tikz"      "dot"      
  [25] "c"         "cc"        "fortran"   "fortran95" "asy"       "cat"      
  [31] "asis"      "stan"      "block"     "block2"    "js"        "css"      
  [37] "sql"       "go"        "python"    "julia"     "sass"      "scss"     
  [43] "R"         "bslib"     "targets"
```

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# Exercise 7: code chunks (kable)

.leftcol45[

#### Create a new `Tables` level three header under the `Summary` heading,

.small[

```md
### Tables
```

]]

.rightcol55[

#### Insert the following code chunk under `Tables`

]

> *insert the code block manually with the keyboard short-cut, or use the "Insert" button*

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Exercise 7: code chunks (kable rendered)

We can see the `small_pressure` parameter from the YAML has been rendered in the new `Tables` tab. `kable` tables are great for presenting small, summary tables.

Read more about `kable` table options [here](https://bookdown.org/yihui/rmarkdown-cookbook/kable.html)

---
background-image: url(img/rmarkdown.png)
background-position: 93% 7%
background-size: 6%

# Exercise 8: code chunks (paged)

#### We are going to repeat the process above, but with a larger table (`mtcars`)

Insert the following code chunk above the `knitr::kable()` output:

.border[

]

#### Knit the document

---
background-image: url(img/rmarkdown.png)
background-position: 7% 96%
background-size: 7%

# Exercise 8: code chunk (paged rendered)

### Paged tables are great for larger datasets

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Exercise 8: paged tables

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Inline R Code

### R Markdown also supports inline R code

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Inline R Code

### Inline R code allows us to include summaries of our analysis in the report

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Exercise 9: Add Inline Code

### We're going to add a Pearson correlation between speed and stopping distance

.leftcol[

#### Include the following code under the `Summary` level three header

]

.rightcol[

> The correlation between speed and 
> stopping distance is 
> 0.8068949

]

.center[

#### Knit the document again

]

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%

# Exercise 9: Add Inline Code (rendered)

---
background-image: url(img/rmarkdown.png)
background-position: 93% 50%
background-size: 20%

# Make cool stuff in R Markdown!

## `bookdown`
## `blogdown`
## these slides!

---
background-image: url(img/rmarkdown.png)
background-position: 93% 10%
background-size: 7%
class: left, top

# Resources

- **YAML**: check out the [`ymlthis` package](https://r-lib.github.io/ymlthis/) for tools and documentation for working with YAML

- **Markdown**: [Commonmark](https://commonmark.org/help/tutorial) has a quick ten-twenty minute tutorial on markdown.

- [R Markdown](https://bookdown.org/yihui/rmarkdown/): A comprehensive but friendly introduction to R Markdown and friends. Free online!

- [R for Data Science](http://r4ds.had.co.nz/): A comprehensive but friendly introduction to the tidyverse. Free online.

- [R Markdown for Scientists](https://rmd4sci.njtierney.com/): R Markdown for Scientists workshop material