Introduction to RMarkdown

class: title-slide, bottom,center
background-image: url(img/title_bkgd.png)
background-position: top center
background-size: 100%

## Introduction to RMarkdown

### Ziwei Ma  
Department of Mathematics

2022-09-12

[<svg aria-hidden="true" role="img" viewBox="0 0 496 512" style="height:1em;width:0.97em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3 .3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5 .3-6.2 2.3zm44.2-1.7c-2.9 .7-4.9 2.6-4.6 4.9 .3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3 .7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3 .3 2.9 2.3 3.9 1.6 1 3.6 .7 4.3-.7 .7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3 .7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3 .7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"></path></svg> @ziwei-utc](https://github.com/ziwei-utc)  
[<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="M459.4 151.7c.325 4.548 .325 9.097 .325 13.65 0 138.7-105.6 298.6-298.6 298.6-59.45 0-114.7-17.22-161.1-47.11 8.447 .974 16.57 1.299 25.34 1.299 49.06 0 94.21-16.57 130.3-44.83-46.13-.975-84.79-31.19-98.11-72.77 6.498 .974 12.99 1.624 19.82 1.624 9.421 0 18.84-1.3 27.61-3.573-48.08-9.747-84.14-51.98-84.14-102.1v-1.299c13.97 7.797 30.21 12.67 47.43 13.32-28.26-18.84-46.78-51.01-46.78-87.39 0-19.49 5.197-37.36 14.29-52.95 51.65 63.67 129.3 105.3 216.4 109.8-1.624-7.797-2.599-15.92-2.599-24.04 0-57.83 46.78-104.9 104.9-104.9 30.21 0 57.5 12.67 76.67 33.14 23.72-4.548 46.46-13.32 66.6-25.34-7.798 24.37-24.37 44.83-46.13 57.83 21.12-2.273 41.58-8.122 60.43-16.24-14.29 20.79-32.16 39.31-52.63 54.25z"></path></svg> @ZiweiMa](http://twitter.com/ZiweiMa)  
[<svg aria-hidden="true" role="img" viewBox="0 0 640 512" style="height:1em;width:1.25em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M172.5 131.1C228.1 75.51 320.5 75.51 376.1 131.1C426.1 181.1 433.5 260.8 392.4 318.3L391.3 319.9C381 334.2 361 337.6 346.7 327.3C332.3 317 328.9 297 339.2 282.7L340.3 281.1C363.2 249 359.6 205.1 331.7 177.2C300.3 145.8 249.2 145.8 217.7 177.2L105.5 289.5C73.99 320.1 73.99 372 105.5 403.5C133.3 431.4 177.3 435 209.3 412.1L210.9 410.1C225.3 400.7 245.3 404 255.5 418.4C265.8 432.8 262.5 452.8 248.1 463.1L246.5 464.2C188.1 505.3 110.2 498.7 60.21 448.8C3.741 392.3 3.741 300.7 60.21 244.3L172.5 131.1zM467.5 380C411 436.5 319.5 436.5 263 380C213 330 206.5 251.2 247.6 193.7L248.7 192.1C258.1 177.8 278.1 174.4 293.3 184.7C307.7 194.1 311.1 214.1 300.8 229.3L299.7 230.9C276.8 262.1 280.4 306.9 308.3 334.8C339.7 366.2 390.8 366.2 422.3 334.8L534.5 222.5C566 191 566 139.1 534.5 108.5C506.7 80.63 462.7 76.99 430.7 99.9L429.1 101C414.7 111.3 394.7 107.1 384.5 93.58C374.2 79.2 377.5 59.21 391.9 48.94L393.5 47.82C451 6.731 529.8 13.25 579.8 63.24C636.3 119.7 636.3 211.3 579.8 267.7L467.5 380z"></path></svg> https://ziwei-utc.github.io/](https://ziwei-utc.github.io/)

.pull-right[

]

---
name: about-me
class: middle, center, inverse

# About me
<img style="border-radius: 50%;" src="img/ziwei.png" width="200px"/>

### Ziwei Ma
#### Assistant Professor of Statistics

---
class: center, middle

# Let's get to know each other

--
## 👍 if you consider yourself an `R` and/or `R Markdown` beginner

--
## ❤️ if you are comfortable or very comfortable with `R` and `R Markdown`

---

class: inverse
# <svg aria-hidden="true" role="img" viewBox="0 0 576 512" style="height:1em;width:1.12em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M96 96h384v288h64V72C544 50 525.1 32 504 32H72C49.1 32 32 50 32 72V384h64V96zM560 416H416v-48c0-8.838-7.164-16-16-16h-160C231.2 352 224 359.2 224 368V416H16C7.164 416 0 423.2 0 432v32C0 472.8 7.164 480 16 480h544c8.836 0 16-7.164 16-16v-32C576 423.2 568.8 416 560 416z"></path></svg>
# Today we will cover:

--
### What is RMarkdown (Rmd)

--
### Why/when is it useful

--
### What can be done in Rmd

--
### How to use it (make your first Rmd file)

---

class: inverse
# What is RMarkdown?

--
- > "R Markdown is an **<span style='color: red;'>authoring syntax</span>** that combines the ease of *<span style='color: lightblue;'>Markdown</span>* with the *<span style='color: lightblue;'>statistical programming language R</span>*."

>Baumer, B., & Udwin, D. (2015). R markdown. Wiley Interdisciplinary Reviews: Computational Statistics, 7(3), 167-177.

--
- **[A brief history of RMarkdown](https://slides.yihui.org/2021-Brazilian-R-Day.html#1)** 
  - [Literate programming](https://en.wikipedia.org/wiki/Literate_programming)

--
- ### RMarkdown workflow

---
class: top, center

---
class: top, center

---
class: top

# What purposes is Rmd for?

(according to Hadley Wickham who is the Chief Scientist at Rstudio and 2019 COPSS Presidents' Award recipients)

--
- ### **Communication** with decision makers

--
- ### **Collaboration** with other data scientists

--
- ### Modern **notepad**
  - reproducibility ([A nice presentation for reproducible scicence](https://oliviergimenez.github.io/reproducible-science-workshop/slides/0_introduction.html#1))
  
  
---
# Advantages: Why using Rmd?

- ### Better comprehensibility

- ### Ease of usage
  -   "on the way"-usage (documentation)
  -   easy to learn

- ### Power of usage
  - multiple occassions
  - multiple output-formats (+ possibility to switch)
  - compatibility with other "languages"
  
  
---
# When is Rmd **not** recommended?
-   ### In general: The less need for communication the less is Rmd recommended

---
# What can be done

**<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="M112.1 454.3c0 6.297 1.816 12.44 5.284 17.69l17.14 25.69c5.25 7.875 17.17 14.28 26.64 14.28h61.67c9.438 0 21.36-6.401 26.61-14.28l17.08-25.68c2.938-4.438 5.348-12.37 5.348-17.7L272 415.1h-160L112.1 454.3zM191.4 .0132C89.44 .3257 16 82.97 16 175.1c0 44.38 16.44 84.84 43.56 115.8c16.53 18.84 42.34 58.23 52.22 91.45c.0313 .25 .0938 .5166 .125 .7823h160.2c.0313-.2656 .0938-.5166 .125-.7823c9.875-33.22 35.69-72.61 52.22-91.45C351.6 260.8 368 220.4 368 175.1C368 78.61 288.9-.2837 191.4 .0132zM192 96.01c-44.13 0-80 35.89-80 79.1C112 184.8 104.8 192 96 192S80 184.8 80 176c0-61.76 50.25-111.1 112-111.1c8.844 0 16 7.159 16 16S200.8 96.01 192 96.01z"></path></svg> Tip: ** It is better to start with a template then customize it. There are many templates available in RStudio and more from internet, like github.

.panelset.sideways[
.panel[.panel-name[Academic papers]

.panel[.panel-name[Presentations]

**NOTE** You may use a single Rmd file to create your presentations in difference format, like beamer, ppt, html and more. A nice talk ["One R Markdown Document, Fourteen Demos "](https://www.youtube.com/watch?v=qLEkUjxk7e8&t=755s)

<img src="img/example-beamer.png" width="90%" height="90%" />
]

.panel[.panel-name[Poster]

<img src="img/example-poster.png" width="90%" height="90%" />
]

.panel[.panel-name[Professional websites]

<img src="img/example_professional_site.png" width="90%" height="90%" />
]

.panel[.panel-name[Visual blogs]

]

.panel[.panel-name[Books]
## **A real example** [R Markdown: The Definitive Guide](https://bookdown.org/yihui/rmarkdown/)
<img src="img/example_book.png" width="90%" height="90%" />
]

.panel[.panel-name[And more]
See some examples of Rmd-applications and possible output formats at the [R-Studio Gallery](https://rmarkdown.rstudio.com/gallery.html)
<img src="img/R-Gallery.png" width="90%" height="90%" />
]

]

---
# Make your first RMarkdown

- ## **Requirement**

--
  
  - ### Option 1
    
     #### Install R and RStudio

--
  - ### Option 2
    
     ####  Sign up a Rstudio Cloud account [https://rstudio.cloud/](https://rstudio.cloud/)

---
# Getting Started in RStudio

>RStudio is what is called an Integrated Development Environment for R. It is dependent on R but separate from it. There are several ways of using R but R Studio is arguably the most popular and convenient. It’s time to open it up and get started! When you first open up RStudio, this is what you should see:

---

## An intutitive introdution about RStudio (*[Image source](https://bookdown.org/animestina/intro_stats_rms/getting-started-in-rstudio.html#r-as-an-interactive-envrionment)*)

---
# Structure of a R Markdown document
.center[![](img/rmd_struc.png)]

---
class: inverse,  middle
# Demo

- ## Open RStudio

- ## Create a new Rmd file

- ## Identify 3 components (frontmatter, content, chunks)

---

.center[![](img/3components.png)]

---

.center[![](img/3componentson.png)]

---
# Structure of a R Markdown document
.center[![](img/rmd_struc.png)]

---
# Structure of a R Markdown document
.center[![](img/rmd_struc_markdown.png)]

---
class: inverse, center, middle
# Format your text with Markdown

---
# What is Markdown?

- A way to write stuff
- Mostly plain words, with some formating

---
# Headers

- Use # to create headers
- Multiple #'s create lower level headers

---
# Text

- Text is rendered as plain text

---
# Lists

- Use asterisks to make bullet points
- Use numbers to make numbered lists
- Use 4 spaces or 1 tab for indentation

---
# Hyperlinks

- To add a hyperlink, put your text between brackets
- Then place the URL between parentheses

---
# Equations

- Write equations with Latex syntax

---
# Equation blocks

---
# Images

- Use a link preceded by an ! to insert an image
- The link text should be
    - a URL if the image is hosted online
    - a file path if the image is saved on your computer

---
# Tables

```md
| header A | header B |
|---------:|:---------|
| data     | data     |

Table:title

```

- A bit of a hassle...

- Use a [generator of Tables for Markdown](https://www.tablesgenerator.com/markdown_tables)

- Wait for next section to learn how to generate tables from `R`

---
# R Markdown Reference Guide

<https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf>

---
# Structure of a R Markdown document
.center[![](img/rmd_struc.png)]

---
# Structure of a R Markdown document
.center[![](img/rmd_struc_chunks.png)]

---
class: inverse, center, middle
## Code, figures and tables

---
# Embed code

- Insert chunk of `R` code
- R Markdown runs code and includes results.

---
# Inline code

- Place code in a sentence with 
- R Markdown replaces code with results

---
# Chunk options
 
- By default, R markdown includes both code and results

---
# echo

- Add options between brackets after `r`.
- `echo = FALSE` hides code.

---
# echo

- Add options between brackets after `r`.
- `echo = FALSE` hides code.

---
# eval

- `eval = FALSE` prevents code from being run  
- No results is displayed, only code

---
# fig.height, fig.width

- Specify dimension of plots (in inches) with fig.width and fig.height
- Separate multiple arguments with commas.

---
# message

- `message = FALSE` prevents messages from appearing
in output

---
# Default chunk options

- Repeating chunk options can be painful

- If you have `echo = FALSE` in every single chunk, how to set the default chunk option to `echo = FALSE` ?

- Use `knitr::opts_chunk$set(echo = FALSE)`

- You may overwrite the default for each chunk

- For chunk options, check out <https://yihui.name/knitr/options/>

---
# Including tables

```r
# cars is a built-in-to-R data set of cars
# and their stopping distances
cars %>% 
  head(5) %>% 
  knitr::kable(format = "html", caption = "A kable table")
```

<table>
<caption>A kable table</caption>
 <thead>
  <tr>
   <th style="text-align:right;"> speed </th>
   <th style="text-align:right;"> dist </th>
  </tr>
 </thead>
<tbody>
  <tr>
   <td style="text-align:right;"> 4 </td>
   <td style="text-align:right;"> 2 </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 4 </td>
   <td style="text-align:right;"> 10 </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 7 </td>
   <td style="text-align:right;"> 4 </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 7 </td>
   <td style="text-align:right;"> 22 </td>
  </tr>
  <tr>
   <td style="text-align:right;"> 8 </td>
   <td style="text-align:right;"> 16 </td>
  </tr>
</tbody>
</table>

- The [`kable`](https://www.rdocumentation.org/packages/knitr/versions/1.21/topics/kable) package is often used with the [`kableExtra`](https://cran.r-project.org/web/packages/kableExtra/vignettes/awesome_table_in_html.html) package
- A number of other packages are available for making pretty tables, see [rmarkdown.rstudio.com](https://rmarkdown.rstudio.com/lesson-7.html)

---
# R Markdown Reference Guide

<https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf>

---
# Structure of a R Markdown document
.center[![](img/rmd_struc.png)]

---
# Structure of a R Markdown document
.center[![](img/rmd_struc_yaml.png)]

---
class: inverse, center, middle
# YAML Yet Another Markup Language

---
# YAML in brief

- Contains the metadata of the document

- Starts and ends by three dashes

- Comes first in the document

---
# Simplest example

.center[![](img/yaml.png)]

---
# Output formats

.center[![](img/output_formats.png)]

---
# Output formats

.center[![](img/knit_rstudio.png)]

---
# Managing bibliography

--
<ol>
<li> Put references in a plain text file with the extension **.bib**, in **BibTex** format (my advice: use [Zotero](https://www.zotero.org))
</ol>
```bibtex
*@article{Shea2014,
  author =        {Shea, Nicholas and Boldt, Annika},
  journal =       {Trends in Cognitive Sciences},
  pages =         {186--193},
  title =         {{Supra-personal cognitive control}},
  volume =        {18},
  year =          {2014},
  doi =           {10.1016/j.tics.2014.01.006},
}
```

--
<ol start = 2>
<li>Reference this file in your YAML header
</ol>
```yaml
---
title: "Citation test"
*bibliography: example.bib
output: html_document
---
```

---
# Citations
<ol start = 3>
<li>In your text, citations go inside brackets and separated by semicolons
</ol>

--
.pull-left[
### This...
Blah blah [@Shea2014; @Lottridge2012].
]

.pull-right[
### turns into this...
  
Blah blah (Shea et al. 2014; Lottridge et al. 2012).
]
---
class: larger-body
# Citations
<ol start = 3>
<li>In your text, citations go inside brackets and separated by semicolons
</ol>

.pull-left[
### This...
Blah blah [@Shea2014; @Lottridge2012].

@Shea2014 says blah.

Blah blah [see @Shea2014, pp. 33-35; also @Wu2016, ch. 1].
]

.pull-right[
### turns into this...
  
Blah blah (Shea et al. 2014; Lottridge et al. 2012).

Shea et al. (2014) says blah.

Blah blah (see Shea et al. 2014, 33–35; also Wu 2016, ch. 1).
]

---
class: larger-body
# Citations
<ol start = 3>
<li>In your text, citations go inside brackets and separated by semicolons
</ol>

.pull-left[
### This...
Blah blah [@Shea2014; @Lottridge2012].
  
@Shea2014 says blah.

Blah blah [see @Shea2014, pp. 33-35; also @Wu2016, ch. 1].
]

.pull-right[
### turns into this...
  
Blah blah (Shea et al. 2014; Lottridge et al. 2012).

Shea et al. (2014) says blah.

Blah blah (see Shea et al. 2014, 33–35; also Wu 2016, ch. 1).
]

- Add e.g `csl: my-style.csl` in the YAML header to change to other formats
- Browse through and download styles at [zotero.org/styles](https://www.zotero.org/styles)

---
# Citations

For an easy way to insert citations, try the [`citr`](https://github.com/crsh/citr) RStudio add-in.

---
# R Markdown Reference Guide

<https://rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf>

.center[![](img/pandoc.png)]

---

.center[![](img/sorcerers.jpg)]