06 R Markdown Basics

class: center, middle, inverse, title-slide

.title[
# 06 R Markdown Basics
]
.subtitle[
## Elements of R e R Markdown
]
.author[
### Claudio Zandonella
]

---

class: size-small
# Document Structure

.pull-left-50[
### Source File
<img src="images/rmarkdown-source.png" width="80%" style="display: block; margin: auto;" />

]

.pull-right-50[

#### YAML header

```yaml
---
title: "Untitled"
author: "ARCA"
date: "6/26/2022"
output: html_document
---
```

#### Markdown text

```
## R Markdown

This is an R Markdown document [...]
When you click the **Knit** button [...]

```

#### R code

````
```{r cars}
summary(cars)
```
````
]

---
class: size-small
# Document Structure

.pull-left-50[
### Source File
<img src="images/rmarkdown-source.png" width="80%" style="display: block; margin: auto;" />

]

.pull-right-50[
### Compiled Output

<img src="images/rmarkdown-compiled.png" width="80%" style="display: block; margin: auto;" />
]

---

# R Markdown Workflow

---
class: size-small
# Markdown Syntax

.pull-left-50[
.pull-left-50[
```
plain text

*italics* and _italics_
**bold** and __bold__
***bold-italic***  
`code`

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

> blockquote

[link](https://...)
image:  
![](path/to/image.png) 
```
]
.pull-right-50[
plain text

*italics* and _italics_  
**bold** and __bold__  
***bold-italic***  
`code`

<div class="example">
<h1>Header 1</h1>
<h2>Header 2</h2>
<h3>Header 3</h3>
<h4>Header 4</h4>
</div>

> blockquote

[link](https://www.dpss.unipd.it/arca/home)

image:

]

.pull-right-50[
.pull-left-50[
```
Unordered list:

- item
- item
  - sub-item

Ordered list:

1. first
1. second
  1. sub-item
  1. sub-item
  
Table:

Col-1 | Col-2
----- | -----
  A   |   B
  C   |   D
```
]

.pull-right-50[
Unordered list:

- item
- item
  - sub-item

Ordered list:

1. first
1. second
  1. sub-item
  1. sub-item

Table:

Col-1 | Col-2
----- | -----
  A   |   B
  C   |   D
]

]

---
class: size-small

.pull-left-50[
# Code
#### Inline Code

The result is `` `r round(3.46, 1)` ``  
The result is 3.5

#### Chunk
````
```{<engine> <chunck-name>, <options, ...>}
<body>
```
````

#### Chuncks setup
````
```{r setup, include=FALSE}
library("<package-name>")

# Chunk default settings
knitr::opts_chunk$set(echo = FALSE,
                      <other-options>,
                      ...)

# Other options
options(width = 80)
```
````
]

.pull-right-50[

### Knitr Chunk Options

https://yihui.org/knitr/options/

.pull-left-50[
#### Code Evalaution
- eval

#### Text Output
- echo
- include
- collapse (only html)
- results
- message
- warning
- error

#### Format
- prompt
- comment
- size
]

.pull-right-50[
#### Figures

- dev
- dev.args
- dpi
- fig.width, fig.height
- fig.asp
- out.width, out.height
- fig.align
- fig.pos (only LaTeX)
- fig.cap
- fig.scap (only LaTeX)
- sanitize (only LaTeX)

#### Other

- cache
- child
]
]

---
class: size-small
# YAML Header

.pull-left-50[

```r
---
title: "My Beatiful Paper"
subtitle: "On something very interesting"
author:
  - First Author^[Institution One]
  - name: Second Author
    affiliation: Institution two
date: "`r format(Sys.time(), '%d %B, %Y')`"
output:
  html_document:
    number_sections: true
    toc: true
  pdf_document:
    latex_engine: pdflatex
    number_sections: true
    toc: true

abstract: |
  This is my abstract.
  
  On multiple lines
---
```

]

.pull-right-50[
.pull-left-50[

#### General Notes

1. YAML is strict about indentation
1. Options repeated for different output formats
1. Path specification is relative to document

#### TOC Options

- toc_depth
- toc_float (only html)
- collapsed (only html)

#### Include Content

<code>
includes:<br>
&emsp;in_header<br>
&emsp;before_body<br>
&emsp;after_body
</code>

]

.pull-right-50[
#### HTML Options

- keep_md 
- css

#### `$\LaTeX$` Options

- keep_tex
- documentclass
- classoption
- geometry
- linestretch
- fontsize
- fontfamily

#### Bibliography

- bibliography
- csl
]
]

---
class: size-small
# Outputs

.pull-left-50[
### Default

#### HTML

- `output:html_document`, web page
- `output:ioslides_presentation`, slides

#### PDF

- `output:pdf_document`, document
- `output:beamer_presentation`, slides

To get pdf outputs we need `$\LaTeX$`<br>Easiest way is to use `tinytex`

```r
tinytex::install_tinytex()
```

#### WORD document... really ?!?
]

.pull-right-50[
### Bookdown

```r
install.packages("bookdown")
```

- better for large (multi-page, chapters) documents.
- easier numbering and cross-referencing figures/tables/equations

#### HTML

```r
output:
  bookdown::html_document2 
```

#### PDF

```r
output:
  bookdown::pdf_document2 
```
]

---
class:size-small

# References

.pull-left-50[

```r
bibliography: <ref-file>.bib 
csl: <custom-style>.csl
```

#### `.bib` file

Reference manager as Zotero (https://www.zotero.org/)

```r
@Manual{rcoreteamR,
    title = {R: A Language and Environment for Statistical Computing},
    author = {{R Core Team}},
    organization = {R Foundation for Statistical Computing},
    address = {Vienna, Austria},
    year = {2021},
    url = {https://www.R-project.org/},
  }
```

#### `.csl` file

Get required style from https://www.zotero.org/styles
]

.pull-right-50[

#### Bibliography

By default, is printed at the end of the document. Use `<div id="refs"></div>` to force the position.

```html
# References
<div id="refs"></div>
# Appendix
```

#### Intext Citations

<table class="table table-striped table-hover" style="margin-left: auto; margin-right: auto;">
 <thead>
  <tr>
   <th style="text-align:left;"> Command </th>
   <th style="text-align:left;"> Result </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:left;width: 6cm; "> [@rcoreteamR] </td>
   <td style="text-align:left;width: 6cm; "> (R Core Team, 2021) </td>
  </tr>
  <tr>
   <td style="text-align:left;width: 6cm; "> @rcoreteamR </td>
   <td style="text-align:left;width: 6cm; "> R Core Team (2021) </td>
  </tr>
  <tr>
   <td style="text-align:left;width: 6cm; "> [-@rcoreteamR] </td>
   <td style="text-align:left;width: 6cm; "> (2021) </td>
  </tr>
  <tr>
   <td style="text-align:left;width: 6cm; "> [@rcoreteamR, text] </td>
   <td style="text-align:left;width: 6cm; "> (R Core Team, 2021, text) </td>
  </tr>
  <tr>
   <td style="text-align:left;width: 6cm; "> [text, @rcoreteamR] </td>
   <td style="text-align:left;width: 6cm; "> (text, R Core Team, 2021) </td>
  </tr>
  <tr>
   <td style="text-align:left;width: 6cm; "> [@rcoreteamR; @yihuiRMarkdown2020] </td>
   <td style="text-align:left;width: 6cm; "> (R Core Team, 2021; Xie et al., 2020) </td>
  </tr>
</tbody>
</table>

]

---
class:size-small
# Figures

.pull-left-50[

#### Images

````
```{r <tag-fig>, fig.cap = "<caption>", ...}
knitr::include_graphics("<path-to-figure>")
```
````

#### Plots
````
```{r <tag-fig>, fig.cap = "<caption>", ...}
ggplot(...)+
  ...
```
````

#### In Text Reference (bookdown)

`\@ref(fig:<tag-fig>)`

- Do not use underscore (`"_"`) in the tag-name
- `fig.cap` is required for referencing.
]

.pull-right-50[
#### Options

- `dev`, device for plotting (`'png'`, `'pdf'`, `'tikz'`)
- `dev.args`, settings for the device
- `dpi`, definition (dots per inch)
- `fig.width`/`fig.height`, plot size in inches
- `fig.asp`, plot aspect ratio height/width
- `out.width`/`out.height` size in the document
- `fig.align`, values `'left'`, `'right'`, `'center'`
- `fig.cap`, figure caption

#### Extra `$\LaTeX$`
- `fig.pos`, values `'h'` (here), `'t'` (top), `'b'` (bottom), `'H'` (HERE need `\usepackage{float}`) 
- `fig.scap`, short caption for list
- `sanitize`, escape special `$\LaTeX$` characters
]

---
class:size-small
# Tables with kableExtra

.pull-left-50[

```r
install.packages("kableExtra")
```

````
```{r <tag-table>, ...}
kable(
  <data>,
  format,
  col.names = NA,
  align,
  caption = "<caption>",
  escape = TRUE,
  ...
)
```
````

#### In Text Reference (bookdown)

`\@ref(tab:<tag-table>)`

- Do not use underscore (`"_"`) in the tag-name
- `caption` is required for referencing.
]

.pull-right-50[
#### Options

- `kable_styling()`, modify style options  (`full_width`, `position`, `font_size`)
  - `bootstrap_options`, specific HTML options (`"striped"`, `"hover"`)
  - `latex_options`, specific LaaTeX options (`"striped"`, `"hold_position"`, `"scale_down"`)
- `add_header_above()`, add a header row on top
- `pack_rows()`, group table rows
- `collapse_rows()`, collapse repeated rows
- `footnote()`, add footnote
- `column_spec()`, customize column look
- `row_spec()`, customize row look

#### Documentation

.pull-left-50[
- [For HTML](https://cran.r-project.org/web/packages/kableExtra/vignettes/awesome_table_in_html.html)
]

.pull-right-50[
- [For PDF](https://cran.r-project.org/web/packages/kableExtra/vignettes/awesome_table_in_pdf.pdf)
]
]
---
class: size-small

.pull-left-50[
## Equations
#### Inline

`$\sqrt{16} = 2^2$` &nbsp;&nbsp; ➡ &nbsp;&nbsp; `$\sqrt{16} = 2^2$`

#### Blocks

```
$$
(\#eq:<tag-equation>)
P(H|D) = \frac{P(H)\ P(D|H)}{P(D)}
$$
```
$$
P(H|D) = \frac{P(H)\ P(D|H)}{P(D)}
$$

- All math symbols ([link]( https://artofproblemsolving.com/wiki/index.php/LaTeX:Symbols))
- `$\LaTeX$` math syntax ([link](https://www.overleaf.com/learn/latex/Mathematical_expressions))
- In text reference (bookdown) `\@ref(eq:<tag-equation>)`
- Do not use underscore (`"_"`) in the tag-name
]

.pull-right-50[
## Sections

<table class="table table-striped table-hover" style="margin-left: auto; margin-right: auto;">
 <thead>
  <tr>
   <th style="text-align:left;"> Command </th>
   <th style="text-align:left;"> Result </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:left;width: 6cm; "> # My Title </td>
   <td style="text-align:left;width: 6cm; "> default tag (my-title) </td>
  </tr>
  <tr>
   <td style="text-align:left;width: 6cm; "> # Title {#tag-section} </td>
   <td style="text-align:left;width: 6cm; "> custom tag (tag-section) </td>
  </tr>
  <tr>
   <td style="text-align:left;width: 6cm; "> # Title {.unnumbered} </td>
   <td style="text-align:left;width: 6cm; "> no number </td>
  </tr>
  <tr>
   <td style="text-align:left;width: 6cm; "> # Title {-} </td>
   <td style="text-align:left;width: 6cm; "> no number </td>
  </tr>
  <tr>
   <td style="text-align:left;width: 6cm; "> # Title {.toc-ignore} </td>
   <td style="text-align:left;width: 6cm; "> no in TOC </td>
  </tr>
</tbody>
</table>

#### In Text Reference (bookdown)

`\@ref(<tag-section>)`

- Do not use underscore (`"_"`) in the tag-name

#### Referece to custom part

- Create tag: `<a name="tag-section"></a>`
- Link to tag: `[Link to ...]$\#tag-section$`
]

---
class: end, middle, center

# Thanks!