R Markdown

layout: true

<div class="footer-small">https://github.com/mjfrigaard/ph-lacounty-r/</div>

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

# R Markdown
#.fancy[Dynamic documents, presentations, and reports from R]

.large[by Martin Frigaard]

Written: October 03 2022

Updated: December 02 2022

.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)
]]]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# Materials

The slides are in the `slides.pdf` file

The materials for this training are in the `worksheets` folder:

```
worksheets
├── import.Rmd
├── export.Rmd
├── objects.Rmd
├── rmd-basic.Rmd
├── rmd-tables.Rmd
└── rmd-visualizations.Rmd
```

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# Outline

.leftcol[

#### 1. Importing data

#### 2. Common Data Objects

#### 3. .red[R Markdown]

]

.rightcol[

#### 4. R Markdown Data Visualizations

#### 5. R Markdown Tables

#### 6. Exporting Data

]

---
background-image: url(www/pdg-hex.png)
class: center, middle, inverse
background-position: 96% 4%
background-size: 6%

# .large[R Markdown]

.font90[.green[Open `rmd-basics.Rmd` to follow along]]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

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

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# How R Markdown Works

#### R Markdown combines .red[metadata], prose, *and* executable code

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# How R Markdown Works

#### R Markdown combines metadata, .red[prose], *and* executable code

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# How R Markdown Works

#### R Markdown combines metadata, prose, *and* .red[executable code]

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# 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?)

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

.leftcol[

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

]

.rightcol[
.code120[

```yml
---
title: "Untitled"
author: "John Doe"
output: html_document
---
```

]
]

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

.leftcol[

#### Table of contents:

.font90[**`toc:`** binary (**`yes`** or **`no`**)]

.font90[**`toc_float:`** logical (**`true`** or **`false`**)]

.font90[**`toc_depth:`** set numerically **`0`** - **`6`**]

]

.rightcol[

#### _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

]

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

### Create a floating table of contents

.leftcol60[

.font90[Open the **`rmd-basic.Rmd`** file in the `worksheets` folder]

.font90[Change the `output` in the YAML header to the following:]

]

.rightcol40[
.code70[

```yml
---
title: "R Markdown Basics"
author: ""
date: ""
output: 
  html_document: 
    toc: yes
    toc_float: true
---
```

]
]

.font90[***Knit the document again***]

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

### Floating table of contents (rendered)

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

### Text highlighting and theme options

.leftcol[

.font90[Add **`highlight`** and **`theme`** to the YAML header]

]

.rightcol[
.code80[

```yml
---
title: "R Markdown Basics"
author: ""
date: ""
output: 
  html_document: 
    toc: yes
    toc_float: yes
    highlight: zenburn 
    theme: united

---
```

]
]

#### *Knit the document again*

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

### Text highlighting and theme options (rendered)

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

.leftcol40[

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

]

.rightcol60[

]

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

.leftcol[

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

]

.rightcol[

]

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

.leftcol40[

### .font80[Change the **Output Format** to **PDF**]

### .font70[Adjust the level of header in the table of contents to **4**]

### .font70[Set the syntax highlighting to **espresso**]

]

.rightcol60[

<img src="www/pdf-rmd-output-options.png" width="80%" height="80%" style="display: block; margin: auto;" />
]

#### .font80[*Knit the document again*]

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

### .font80[PDF Document Options (rendered)]

.leftcol20[

### .font80[A new window will open with the PDF preview]

]

.rightcol80[

]

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

### .font80[Common output formats]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: YAML

### Output formats

.font80[

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

]

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Markdown

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

---
class: left, top
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Markdown

.leftcol[.large[

#### Italics, Bold, and Code

```markdown
For italics, you can use *this* or _this_.

If you want bold, you can use **this** or __this__.

If you want text formatted as code, you can use `this`.
```

]]

.rightcol[.font90[

For italics, you can use *this* or _this_.

If you want bold, you can use **this** or __this__.

If you want text formatted as code, you can use `this`.

]]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%
class: left, top

# R Markdown: Markdown

.leftcol[.large[

#### Headers

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

]]

.rightcol[.large[.center[

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

]]]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%
class: left, top

# R Markdown: Markdown

.cols3[

#### Bullets & Numeric Lists

]

.cols3[

```markdown
  - Item 1  
  - Item 2
      + Item 2a
      + Item 2b
        - Item 2b.1
        - Item 2b.2
    
 1. Item 1
 2. Item 2  
   a. Item 2a  
   b. Item 2b  
```
  
]

.cols3[

* Item 1  
* Item 2
    + Item 2a
    + Item 2b
      - Item 2b.1
      - Item 2b.2

1. Item 1
 2. Item 2  
   a. Item 2a  
   b. Item 2b  
 
]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%
class: left, top

# R Markdown: Markdown

.leftcol55[

#### Hyperlinks

```md
[linked phrase](https://posit.co/)
```

]

.rightcol45[

#### *becomes...*

.center[.large[

[linked phrase](https://posit.co/)

]]]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%
class: left, top

# R Markdown: Markdown

.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(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%
class: left, top

# R Markdown: Markdown

.leftcol[

#### Math Equations

```md
$equation$

$$ equation $$
```

]

.rightcol[.large[

`$equation$`

$$ equation $$

]]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%
class: left, top

# R Markdown: Markdown

.leftcol45[

#### Strike-through

```md
~~strikethrough~~
```

]

.rightcol55[.center[.large[

~~strikethrough~~

]]]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%
class: left, top

# R Markdown: Markdown

.font90[In `rmd-basic.Rmd`, add the following paragraph in the **R Markdown** section, after the first sentence.]

> R Markdown is a plain-text file format that combines narrative text (with markdown, a lightweight markup syntax) and executable code chunks (R, Python, or SQL) to produce multiple output formats (.html, .pdf, .docx, .pptx, etc.)

.leftcol[
.font80[
- make 'plain-text' *italic*

- insert the wikipedia page link for [markdown](https://en.wikipedia.org/wiki/Markdown): 
`https://en.wikipedia.org/wiki/Markdown`
]
]

.rightcol[
.font80[
- make the code languages **bold**

- format the file extensions as `code`
]
]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

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

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

### `setup` code chunk

.font90[The first bit of R code in our RMarkdown file is the `setup` chunk]

.font90[Chunks named '`setup`' are special because they can set global options, and they are run first]

.font90['`include=FALSE`' means this code is run, but not displayed]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

### `setup` code chunk contents

.leftcol30[

.font90[Load packages]

.code70[

```r
library(tidyverse)
```
]

]

.rightcol70[

.font90[Set the URLs for the repositories used by `update.packages`]

.code70[

```r
options(repos = "https://cloud.r-project.org")
```
]

]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

### `setup` code chunk options

.leftcol60[

.font90[R Markdown code document options come from the `knitr` package]

]

.rightcol40[

.font90[We can set the chunk and knit options the with syntax below:]

```r
knitr::opts_chunk$set()
knitr::opts_knit$set()
```

]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

### Inserting code chunks

.leftcol[

.font120[Use keyboard shortcuts **CMD/CTRL + I** or **ALT/OPTION + I**]

]

.rightcol[

]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

### Code chunks

.border[

]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

### Code chunk fences

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

### Code chunk names and options

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

### Code chunk options

.leftcol[

.font80[Common options for code chunks are:]

.font70[

]

.rightcol[

.font80[More advanced options can control language engines (`engine`), caching (`cache`, `dependson`), and plot animations (`fig.show`)]

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

]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

.leftcol[

.font90[In the `rmd-basic.Rmd` file, delete the **`pressure`** code chunk]

.font90[Insert a new code chunk and name it **`diamonds`**]

.font90[Add the code below]

.code70[

```r
ggplot(data = diamonds, 
          aes(x = carat, y = price)) + 
  geom_point(aes(color = cut))
```

.font90[Set **`echo`** to **`FALSE`**]

]

.rightcol[

.font90[Create another code chunk and name it **`diamonds-show`**]

.font90[Set the options to display this code, but not execute it]

.font90[**Knit the document**]

]

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

### Edit code chunk options

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

---
background-image: url(www/pdg-hex.png)
background-position: 96% 4%
background-size: 6%

# R Markdown: Code

### 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"      "php"      
  [13] "psql"      "Rscript"   "ruby"      "sas"       "scala"     "sed"      
  [19] "sh"        "stata"     "zsh"       "asis"      "asy"       "block"    
  [25] "block2"    "bslib"     "c"         "cat"       "cc"        "comment"  
  [31] "css"       "ditaa"     "dot"       "embed"     "eviews"    "exec"     
  [37] "fortran"   "fortran95" "go"        "highlight" "js"        "julia"    
  [43] "python"    "R"         "Rcpp"      "sass"      "scss"      "sql"      
  [49] "stan"      "targets"   "tikz"      "verbatim"  "glue"      "glue_sql" 
  [55] "gluesql"
```