R Markdown Workshop

name: Rmarkdown Intro
class: left, middle
background-image: url(img/yoal-desurmont-jqgsM3B9Fpo-unsplash.jpg)
background-size: cover

<h1> .fat[.fancy[R Markdown Workshop]]
 
 
 
 
.left2[
<img src="img/rmarkdown.png" alt="Sharingan" width="170">
]

<h2> .fancy[Creation, organisation, storage, and collaboration]

<h3> Anne-Kathrin Kleine | University of Groningen

.hljs-github .hljs {
    background: #D3D3D3;
}

.inline-c, remark-inline-code {
   background: #228B22;
   border-radius: 3px;
   padding: 4px;
   font-family: 'Source Code Pro', 'Lucida Console', Monaco, monospace;
}

.blue-h{
   background: #1261A0;
}

.out-t, remark-inline-code {
   background: #1261A0;
   border-radius: 3px;
   padding: 4px;
   
}

.pull-left-c {
    float: left;
    width: 58%;
    
}

.pull-right-c {
    float: right;
    width: 38%;
    
}

.left2 {
  margin: 0;
  position: absolute;
  top: 50%;
  left: 20%;
  -ms-transform: translate(-50%, -50%);
  transform: translate(-50%, -50%);
    
}

.right2 {
  margin: 0;
  position: absolute;
  top: 50%;
  left: 80%;
  -ms-transform: translate(-50%, -50%);
  transform: translate(-50%, -50%);
    
}

.center2 {
  margin: 0;
  position: absolute;
  top: 50%;
  left: 50%;
  -ms-transform: translate(-50%, -50%);
  transform: translate(-50%, -50%);
}

.medium {
    font-size: 75%
}

.small {
    font-size: 50%
    }

.action {
    background-color: #f2eecb;
  
}

</style>

---

## .fat[...taking the pain away]
### 💅 efficient management of **code** and **results** 
### 📕 easy conversion to pdf, html, word
### 🧘 guaranteed reproducibility, less mistakes

---
class: middle, inverse

## .fat[.fancy[Workshop overview]]

???

record sessions - alright?

---
class: middle, inverse

## .fancy[Day 1:]

.pull-left[
#### 1. R Markdown basics
#### 2. Writing text 
#### 3. Reference management 
#### 4. Writing code 
#### 5. Figures, tables, and plots
#### 6. R project organization 
]
--
.pull-right[

#### .fancy[GOAL 1] 💪 Write your analysis scripts in R Markdown
#### .fancy[GOAL 2] 💪 Convert the output into a format of your choice (word, html, pdf) 
#### .fancy[GOAL 3] 💪 Add text, figures/tables, and references  
#### .fancy[GOAL 4] 💪 Learn proper project structuring and using templates
]

---

## .fancy[Day 2:]

.pull-left[
#### 1. Git & GitHub basics
#### 2. Collaborating using Git & GitHub 
#### 3. Osf integration 
#### 4. Blogdown - build your project website 
#### 5. Xaringan, bookdown & Co.
]
--
.pull-right[

#### .fancy[GOAL 1] 💪 Learn how to use Git & GitHub for version control 
#### .fancy[GOAL 2] 💪 Learn how to collaborate using Git & GitHub 
#### .fancy[GOAL 3] 💪 Share your code and data through osf 
#### .fancy[GOAL 4] 💪 Build your own data analysis project website   
#### .fancy[GOAL 5] 💪 Learn how to use R & Markdown to produce a multitude of outputs (books, presentations, interactive applications)
]

---

# .fancy[General organization:]

#### Presentation, then practice
#### You will work in breakout rooms, groups of 3 to 4

### ❓❔Questions❓❔
#### 1. Ask you group 🙆
#### 2. Google (together) 👨‍💻👩‍💻👩‍💻
#### 3. Ask me 👷‍

---
class: middle, inverse

# Find me at...

[LinkedIn](https://linkedin.com/in/anne-kathrin-kleine)  
[GitHub](https://github.com/AnneOkk)  
[AnneKathrinKleine.com](https://AnneKathrinKleine.com)  
[a.k.kleine@rug.nl](mailto:alison@rstudio.com)

---

# Or find me ...

]

---

## .fat[.fancy[How familiar are you with using R for data analysis?]]

### Go to [https://www.menti.com/yzy8sx3mb6](menti.com) 🤸 (and enter the code **6959 8626**)

### [See results](https://www.mentimeter.com/app/presentation/22b3d8f42894408a6a6c001e1eae6a88/2be87e2a1316)

---

## .fat[.fancy[Major resources:]]

### [Advanced R Markdown Workshop R Conf 2019](https://arm.rbind.io/)
### [R Markdown: The Definitive Guide](https://bookdown.org/yihui/rmarkdown/)
### R Markdown Workshop by [Resul Umit](https://resulumit.com/teaching/rmd_workshop.html#112)

---

# Detailed Outline

-  Did you do the  setup?
-  Creating an R project🐣
-  The YAML header
-  Writing text 📝
-  Reference management
-  Writing code
-  Figures
-  Plots - ggplot2
-  Structure your project
-  🎉 Yey, you're all set! 🎉 
-  Your turn! 🤹

---

# Did you do the .fat[.fancy[setup?]]

.large[[Link to setup](https://anneokk.netlify.app/docs/r_markdown_workshop/preparation/preparation/)]

---

# .fat[.fancy[Creating an R project]]🐣

---

### .fat[.fancy[Creating an R project]]

### Create a new R Project from within R Studio

![](img/openRProj.png)
---
class: middle, inverse

### Save in new directory

---
class: middle, inverse

### Choose the folder where you want to store your R Markdown file

---

### In that new folder, create an R Markdown file

---
class: middle, inverse

### When you knit, the following happens:

![](https://d33wubrfki0l68.cloudfront.net/61d189fd9cdf955058415d3e1b28dd60e1bd7c9b/9791d/images/rmarkdownflow.png)

### knit executes the code if there is any, converts the resulting document from .Rmd (R Markdown) into .md (Markdown)
### pandoc transforms the .md document into your preferred output format(s) (e.g., word, pdf, html)
 
---
class: middle, inverse

# .fat[.fancy[The YAML header]]

---
class: middle, inverse

## .fancy[YAML  &mdash; General]

YAML includes the metadata variables
- e.g., title, output format    
- written between a pair of three hyphens .blue-h[-]

```r
*---
title: 
output:
*---
```

---
class: middle, inverse

## .fancy[YAML &mdash; Variables]

- see [Pandoc User's Guide](https://pandoc.org/MANUAL.html) and [R Markdown Cheat Sheet](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf) for documentation and help

- Typical YAML variables for an research paper are as follows:

```r
---
title: 
author: 
date: 
bibliography: 
csl: 
output: 
---
```

---
class: middle, inverse

## .fancy[YAML &mdash; Variables]

Variables can be provided as .blue-h[strings]

```r
---
*title: "My very funny and descriptive article title"
output:
---
```

---
class: middle, inverse

## .fancy[YAML &mdash; Variables]

Variables can be provided as strings, .blue-h[options]

```r
---
title: "My very funny and descriptive article title"
*output: pdf_document
---
```

---
class: middle, inverse

## .fancy[YAML &mdash; Variables]

Variables can be provided as strings, options, and .blue-h[sub-options]

```r
---
title: "My very funny and descriptive article title"
output: 
    pdf_document:
*       keep_tex: true
---
```

---
class: middle, inverse
## .fancy[YAML &mdash; Variables]

Variables can be provided as strings, options, sub-options, and .blue-h[code]

```r
---
title: "My very funny and descriptive article title"
output: 
    pdf_document:
        keep_tex: true
*date: "\`r format(Sys.Date(), '%d %B %Y')`"
---
```
---
class: middle, inverse

## .fancy[YAML &mdash; Variables &mdash; Output Formats]

Documents as output formats include

- .blue-h[HTML]

```r
---
title: "Theming with bslib and thematic"
*output:
* html_document:
    ...
---
```
]

]

---
class: middle, inverse

## .fancy[YAML &mdash; Variables &mdash; Output Formats]

Documents as output formats include

- HTML
- .blue-h[LaTeX]

```r
---
title: "Theming with bslib and thematic"
*output: latex_document
---
```
]

]

---
class: middle, inverse

##.fancy[ YAML &mdash; Variables &mdash; Output Formats]

Documents as output formats include

- HTML
- LaTeX
- .blue-h[PDF]

```r
---
title: "Theming with bslib and thematic"
*output: pdf_document
---
```
]

]

---
class: middle, inverse

## .fancy[YAML &mdash; Variables &mdash; Output Formats]

Documents as output formats include

- HTML
- LaTeX
- PDF
- .blue-h[Word]

```r
---
title: "Theming with bslib and thematic"
*output: word_document
---
```
]

]

---
class: middle, inverse

## .fancy[YAML &mdash; External Files]

```r
---
title: "Journal title"
author: "Jane Doe^[Department of Science, University of Random. Email: jane.doe@random.edu. Website: http://www.janedoe.com.]"                                    
date: 4 March 2022 
*bibliography: references.bib
*csl: apa.csl
output: pdf_document                                    
---
```

---
class: middle, inverse

##  .fancy[YAML &mdash; Strings &mdash; External Files]

```r
---
...
bibliography: references/ref_library.bib                                    
csl: "../../paperstyle/csl/apa.csl" # two dots (..) mean moving one folder up
...
---
```

- ❕❗locations of files  re specified as .blue-h[relative to the working directory]❕❗
    
- for reproducibility reasons, hard-coded stings should be avoided 🙏
  -  e.g., 👎 `"C:/Users/Dropbox/styles/apa.csl"` 👎️

---

# .fat[.fancy[Writing text]] 📝

---
class: middle, inverse

## .fancy[Lines]

Multiple spaces on a given line are reduced to one

```r
This is a sentence followed by four spaces.    This is another sentence on the same line.
```

Line endings with fewer than two spaces are ignored

```r
This is a sentence followed by one space.
This is another sentence on a new line.
```

---
class: middle, inverse

## .fancy[Hard Breaks]

Two or more spaces at the end of lines introduce hard breaks, forcing a new line

```r
This is a sentence followed by two spaces.  
This is another sentence on a new line.
```

.out-t[This is a sentence followed by two spaces.  
This is another sentence on a new line.]
 
---
class: middle, inverse

## .fancy[Line Blocks]

Spaces on lines that start with a vertical line .blue-h[|] are kept

```r
| a one-space indent
|     a five-space indent
|          a ten-space indent  
```

&nbsp;a one-space indent  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;a five-space indent  
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;a ten-space indent

]

---
class: middle, inverse

## .fancy[Block Quotes]

Lines starting with the greater-than sign .blue-h[&#62;] introduce block quotes*

```r
> In God, we trust. All others must bring data. 
>
> --- Anonymous 
```

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;In God, we trust. All others must bring data.    
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;    
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &mdash; Anonymous
]

---
class: middle, inverse

## .fancy[Paragraphs]

One or more blank lines introduce a new paragraph

```r
This is the first sentence of a paragraph as it is preceded by a blank line. This is the second 
sentence of that paragraph, which is followed by a blank line.

This is the first sentence of a *new paragraph* as it is preceded by a blank line. 
```

This is the first sentence of a paragraph as it is preceded by a blank line. This is the second 
sentence of that paragraph, which is followed by a blank line.

This is the first sentence of a *new paragraph* as it is preceded by a blank line.

]

---
class: middle, inverse

## .fancy[Comments]

Text with the syntax .inline-c[] is omitted from output

```md

This is the first sentence of a paragraph as it is preceded by a blank line.

This is the first sentence of a new paragraph  as it is preceded 
by a blank line.

```

This is the first sentence of a paragraph as it is preceded by a blank line.

This is the first sentence of a new paragraph as it is preceded by a blank line.

]

---
class: middle, inverse

## .fancy[Headers]

The number sign .yellow-h[&#x23;] introduces headers; lower levels are created with additional signs &mdash; up to total five levels

# Introduction

## Introduction

]

### Introduction

#### Introduction

##### Introduction

]
---

## .fancy[Emphases]

A pair of single asterisk .blue-h[&#42;] or underscores .blue-h[&#95;] introduces italics

&#42;italics&#42; becomes .out-t[*italics*]

&#95;italics&#95; becomes .out-t[*italics*] as well

A pair of double asterisk or underscores introduces bold

&#42;&#42;bold&#42;&#42; becomes .out-t[**bold**]

&#95;&#95;bold&#95;&#95; becomes .out-t[**bold**] as well

These two rules can be combined

&#42;&#42;&#95;bolditalics&#95;&#42;&#42; becomes .out-t[**_bolditalics_**]

&#95;&#42;&#42;bolditalics&#42;&#42;&#95; becomes .out-t[_**bolditalics**_] as well

---
class: middle, inverse

## .fancy[Strikethrough]

A pair of double tildes .yellow-h[~] introduces strikethrough

&#126;&#126;strikethrough&#126;&#126; becomes .out-t[~~strikethrough~~]

Strikethrough can be combined with italics or bold

&#42;&#42;&#126;&#126;strikebold&#126;&#126;&#42;&#42; or &#95;&#95;&#126;&#126;strikebold&#126;&#126;&#95;&#95;, they both become .out-t[**~~strikebold~~**]

&#126;&#126;&#42;&#42;strikebold&#42;&#42;&#126;&#126; or &#126;&#126;&#95;&#95;strikebold&#95;&#95;&#126;&#126;, they both become .out-t[~~**strikebold**~~] as well

&#42;&#126;&#126;strikeitalitcs&#126;&#126;&#42; or &#95;&#126;&#126;strikeitalitcs&#126;&#126;&#95;, they both become .out-t[*~~strikeitalitcs~~*]

&#126;&#126;&#42;strikeitalitcs&#42;&#126;&#126; or &#126;&#126;&#95;strikeitalitcs&#95;&#126;&#126;, they both become .out-t[*~~strikeitalitcs~~*] as well

---

## .fancy[External links]

You can link text to URLs

&#91;visit my website](https&#58;//anneokk.netlify.app//) becomes .out-t[[visit my website](https://anneokk.netlify.app/)]

You can also link text to an email address

&#91;email me](mailto&#58;a.k.kleine@rug.nl) becomes .out-t[[email me](mailto:a.k.kleine@rug.nl)]

&#60;a.k.kleine@rug.nl&#62; becomes .out-t[<a.k.kleine@rug.nl>]

---
class: middle, inverse

## .fancy[Equations]

Inline equations go between a pair of single dollar signs "$" with no space between the signs and the equation itself

Block equations go in between a pair of double dollar signs

]

---
class: middle, inverse
## .fancy[Inline Notes]

For inline footnotes, use the .inline-c[^[footnote]] syntax

]

---
class: middle, inverse
## .fancy[Lists]

Lines starting with asterisk .yellow-h[&#42;] as well as plus .yellow-h[&#43;] or minus .yellow-h[&#8722;] signs introduce lists

```r
- books
- articles
- reports
```

- books
- articles
- reports

]

---
class: middle, inverse

## .fancy[Lists]

Lists can be nested within each other, with indentation

```r
+ books
+ articles
    - published
    - under review
        + revised and resubmitted
    - work in progress
```

+ books
+ articles
    - published
    - under review
        + revised and resubmitted
    - work in progress
    
]

---
class: middle, inverse

## .fancy[Lists]

List items can be numbered

```r
1. books
2. articles
    - published
    - under review
        + revised and resubmitted
    - work in progress
```

1. books
2. articles
    - published
    - under review
        + revised and resubmitted
    - work in progress

]

---
class: middle, inverse
.pull-left[### .fancy[Dashes]

Two hyphens grouped together introduce an en-dash

Three hyphens grouped together introduce an em-dash

.inline-c[&#8208;&#8208;&#8208;] becomes .out-t[&mdash;]
]
.pull-right[### .fancy[Subscripts and Superscripts]

A pair of tildes introduces subscript

A pair of carets introduces superscript

]

---

# .fat[.fancy[Reference management]]

---
class: middle, inverse
## .fancy[References &mdash; Bibliography Database]

.pull-left-c[
  - References are defined in .bib files
  
  - they follow the BibTeX format
  
- `pandoc` looks for a .bib file, and for the definitions therein, to process citations

```r
---
...
*bibliography: refs.bib
...
---
```
  
- .bib files are specified with the `bibliography` variable in YAML
  
  
  
]

.pull-right-c[
 <img src="img/bibfile.png", height="300px" >
 
- A BibTeX entry consists of three elements
 - a type (e.g., `@Article`) 
 - a citation-key (e.g., `Neuro2013`) 
 - a number of tags (e.g., `title`, `volume`, ...)
]

---

## .fancy[References &mdash; Bibliography Database &mdash; Entries]
  
### Get information via `Google Scholar`:
#### follow ` cite -> BibTex ` and copy
#### paste into .bib, edit if necessary, and save

### Better options: [Zotero](https://christopherjunk.netlify.app/blog/2019/02/25/zotero-rmarkdown/#:~:text=In%20Zotero%20follow%20this%20path,and%20follow%20the%20system%20setup.), [Mendeley](https://rosannavanhespen.nl/rmarkdown/writing-your-thesis-with-r-markdown-2-text-citations-and-equations/#:~:text=Open%20Mendeley%20and%20select%20Mendeley,your%20R%20Markdown%20document%20lives.)
#### ⭐ [Useful article on how to use Zotero with R Markdown](https://gsverhoeven.github.io/post/zotero-rmarkdown-csl/) ⭐

???

- Zotero: In Rstudio, we can now press CTRL+K 
- then create the actual bib file (or json - recommended)
- export to bibtex

---
class: middle, inverse

## .fancy[References &mdash; Style]
  
- Reference styles are defined in `.csl` files

- files for different styles (e.g., APA) are available at [https://www.zotero.org/styles](https://www.zotero.org/styles)

```r
---
...
*csl: "../apa.csl"
...
---
```

- .csl files are specified with the `csl` variable in YAML

---
class: middle, inverse

## .fancy[References &mdash; In-text Citation Syntax &mdash; Author-Date Styles (APA 7)]

.pull-left[
  
  .inline-c[[@bennett2015]] becomes .out-t[(Bennett, 2015)]
  
  .inline-c[@bennett2015] becomes .out-t[Bennett (2015)]
  
  .inline-c[[-@bennett2015]] becomes .out-t[(2015)]
  
  .inline-c[-@bennett2015] becomes .out-t[2015]
  
  .inline-c[[@bennett2015 35]] becomes .out-t[(Bennett, 2015, p. 35)]
  
  .inline-c[[@bennett2015 33-35]] becomes .out-t[(Bennett, 2015, pp. 33&ndash;35)]
  
  
]

.pull-right[
  
  .inline-c[[@bennett2015, ch. 1]] becomes .out-t[(Bennett, 2015, ch. 1)]
  
  .inline-c[[@bennett2015; @gilbert2019]] becomes .out-t[(Bennett, 2015; Gilbert, 2019)]
  
  .inline-c[[see @bennett2015, for details]] becomes .out-t[(see Bennett, 2015, for details)]
  
  .inline-c[@bennett2015 [33-35]] becomes .out-t[Bennett (2015, pp. 33&ndash;35)]
  
]

---
class: middle, inverse

## .fancy[Citations &mdash; Reference List]

```r
This is the last sentence of an APA style manuscript.
## References
```

.out-t[
  
  This is the last sentence of an APA style manuscript.
  
  ### References
  
  Bennett, S. (2015). Peanut butter and jelly. *Journal of Bone, 1*(12), 3–35.
  
  Gilbert, T. (2019). Turning wine into water. In M. Albert (Ed.), *The book of ground* (pp. 124–142). Antman.
  
]

---
class: middle, inverse

# .fat[.fancy[Writing code]]
## Data: [Superhero Dataset](https://domosoftware.sharepoint.com/:x:/s/CS-Edu-PublicFiles/EfRNaW_lszlHg-m2hMNZnLABv0bM12TTLVrS3MtSD1bzrw?e=f2gBgd)

---
class: middle, inverse

## .fancy[Code, in and outside chunks]
  
### Code chunks:

```r
library(readxl)
library(dplyr) 
df <- read_excel("data/heroes_information.xlsx") %>% 
 na_if(., -99) %>% 
 mutate(bmi = round(Weight/((Height/100)**2)), 2) %>% 
 rename(., Water_allergy = Gender) %>% 
 mutate(Water_allergy = recode(Water_allergy, Male = "Yes", Female = "No")) %>% 
 select(., -...1, -`2`)
```

### Inline:

.inline-c[The average height of a superhero is <code>&grave;r round(mean(df$Height, na.rm = T), 2) &grave;</code> centimeter] becomes:

---

## .fancy[Code Chunks]
 
.pull-left-c[
 
- Code chunks are delimited spaces between a pair of three backticks <code> &#96;&#96;&#96;</code>
- their output, if there is any, appears in the output document
 
 
 
- in curly brackets `{}`, code chunks take
 
 - .blue-h[a language engine] (e.g., `r`)
 - .blue-h[a label] (e.g., `setup`)
 - .blue-h[options] (e.g., `echo = FALSE`)
 + The complete list of options is available at <https://yihui.org/knitr/options>
 
 ]

````md
  ```{r, setup, echo=FALSE}
```
````
]

---
class: middle, inverse

## .fancy[Chunk options]

#### `echo = FALSE` to exclude code 
````md
```{r, show_df, echo = FALSE}
head(df)
```
````

```
## # A tibble: 6 × 11
## name Water_allergy `Eye color` Race `Hair color` Height Publisher `Skin color` Alignment Weight bmi
## <chr> <chr> <chr> <chr> <chr> <dbl> <chr> <chr> <chr> <dbl> <dbl>
## 1 A-Bomb Yes yellow Human No Hair 203 Marvel Comics - good 441 107
## 2 Abe Sapien Yes blue Icthyo Sapien No Hair 191 Dark Horse Com… blue good 65 18
## 3 Abin Sur Yes blue Ungaran No Hair 185 DC Comics red good 90 26
## 4 Abomination Yes green Human / Radiation No Hair 203 Marvel Comics - bad 441 107
## 5 Abraxas Yes blue Cosmic Entity Black NA Marvel Comics - bad NA NA
## 6 Absorbing Man Yes blue Human No Hair 193 Marvel Comics - bad 122 33
```

---
class: middle, inverse

## .fancy[Chunk options]

#### `echo = TRUE` to include code and output 
````md
```{r, show_df_1, echo = TRUE}
head(df)
```
````

```r
head(df)
```

---
class: middle, inverse

## .fancy[Chunk options]

#### `include = FALSE` to exclude entire chunk content (code and output)

````md
```{r, show_df_2, include = FALSE}
head(df)
```
````

---

## .fancy[Chunk options]

#### `results = "hide"` to include only code (no output)

````md
```{r, show_df_3, results = "hide"}
head(df)
```
````

```r
head(df)
```

---

## .fancy[Chunk options]

Cache results, useful for complex analyses:

````md
```{r ... cache=TRUE}
```
````

Prevent evaluation:

````md
```{r ... eval=FALSE}
```
````

Show results as produced by code (no transformation with `pandoc`, necessary for some packages (e.g., stargazer)):

````md
```{r ... results="asis"}
```
````

Prevent showing warnings, messages, errors:

````md
```{r ...error=FALSE, message=FALSE, warning=FALSE}
```
````

---
class: middle, inverse

## .fancy[The Setup Chunk]
  
It is recommended to use the first code chunk for general setup, where you can

- define .blue-h[your own defaults] for chunk options, with `knitr::opts_chunk$set()`
- load the necessary packages    
- import raw data

````md
```{r, setup, include=FALSE}
## chunk option defaults
knitr::opts_chunk$set(echo=FALSE, message=FALSE)
## packages
library(dplyr)
library(ggplot2)
library(stargazer)
library(readxl)
```
````

---

## .fancy[The Data Chunk]
  
Second chunk for the main operations on raw data
- cleaning, transformations

````md
```{r, data, ...}
df <- read_excel("data/heroes_information.xlsx") %>% 
 na_if(., -99) %>% 
 mutate(bmi = round(Weight/((Height/100)**2)), 2) %>% 
 rename(., Water_allergy = Gender) %>% 
 mutate(Water_allergy = recode(Water_allergy, Male = "Yes", Female = "No")) %>% 
 select(., -...1, -`2`)

```
````

---
class: middle, inverse
## .fancy[Inline Code]

```r
If we multiply _pi_ by 5, we get `r pi * 5`.
```

```r
The average height of a superhero in the dataset is `r mean(df$Height, na.rm = T)`, which would 
round to `r round(mean(df$Height, na.rm = T), digits = 1)`.
```

```r
__Only `r nrow(subset(df, Height < 100))` superheros__ in the dataset are Smallings.
```

---

# .fat[.fancy[Figures]]

---
class: middle, inverse
## .fancy[Figures &mdash; Markdown Syntax]
 
The syntax !&#91;Figure Caption&#93;(figure.extension) embeds images, and/or figures into .Rmd documents

```r
![A superhero's best friend](img/superdog.jpg)
```

<center>Figure 1: A superhero's best friend.</center>
---
class: middle, inverse

## .fancy[Figures &mdash; `knitr`]
        
The `knitr` package offers a capable alternative with the `include_graphics()` function
      
````md
```{r, superdog, echo=FALSE, fig.cap="A superhero's best friend."}
knitr::include_graphics("img/superdog.jpg")
```
````

Figure 1: A superhero's best friend.

---
class: middle, inverse
## .fancy[Figures &mdash; `knitr`]

Size is defined with the chunk options `out.width` or `out.height`

<img src="img/superdog.jpg" width="15%" />
]

]        
---

# .fat[.fancy[Plots - ggplot2]]

---

## .fancy[`ggplot2`]

1) The `ggplot` function and the `data` argument

```r
ggplot(data = df)
```

2) The mapping aesthetics, or .blue-h[aes]; most importantly, the variable(s) that we want to plot

```r
ggplot(data = df, 
*      mapping = aes(x = Height, y = Weight, color = Alignment))
```

3) The geometric objects, or .blue-h[geom]; the visual representations

```r
ggplot(data = df, 
       mapping = aes(x = Height, y = Weight, color = Alignment)) +
*      geom_point()
```

---
class: middle, inverse

## .fancy[`ggplot2`]

Put the code in a chunk, and give it a caption

````md
```{r, scatterplot, `fig.cap = "Superheros size"`}
ggplot(data = df, 
       mapping = aes(x = Height, y = Weight, color = Alignment)) +
       geom_point()
```
````

]

![](day_one_files/figure-html/unnamed-chunk-37-1.png)

Figure 1. A scatterplot of superheros' height and weight.

]

---
class: middle, inverse
## .fancy[`ggplot2`]

Add facets for subgroups, e.g., `branch`

````md
```{r, scatterplot, fig.cap = "A scatterplot of superheros' height and weight."}
ggplot(data = df,  
       mapping = aes(x = Height, y = Weight, color = Alignment))  +
       geom_point() +
       facet_wrap(. ~ Water_allergy)
```
````

]

![](day_one_files/figure-html/unnamed-chunk-38-1.png)

Figure 1. A scatterplot of superheros' height and weight.

]
--
Every plot you can think of - you can create it in R! See [R Graph Gallery](https://r-graph-gallery.com/ridgeline-plot.html)!  
--
Also have a look at the [plotly graphical library](https://plotly.com/r/).

---

# .fat[.fancy[Tables]]

---
class: middle, inverse

## .fancy[Tables with `stargazer`]

- A capable package for creating at least three kinds of tables

- raw data, in columns and rows
    - descriptive/summary statistics
    - regression models

---

## .fancy[Tables with `stargazer`]

- The `stargazer` package requires specific settings

- in the chunk options
  - and, in the `type` argument of the `stargazer()` function

- These settings depend on the desired output format,* as shown below

|  Output       | Chunk Option    |  Type Argument |                   
|:------------- |:----------------|:-------------- |
| LaTex / PDF   |  results="asis" | latex          |  
| HTML          |  results="asis" | html           |  
| Word          |  comment=""     | text           |

]

* The following slides use the setting for LaTex and PDF outputs.

]

---
class: middle, inverse
## .fancy[Tables with `stargazer`]

- `stargazer` tables look slightly different in different output formats

- workarounds for Word:
      - `knit` to HTML as well as Word, copy the tables from HTML to Word
      - `knit` to PDF, open the PDF in Word
      - use a different package to create tables, such as `huxtable`

---
class: middle, inverse

## .fancy[Example data table with `stargazer`]
  
Table of first three rows of the dataset

````md
```{r, data_table, echo=FALSE, results="asis"}
stargazer(data = head(df, n = 3), type = "latex", summary = FALSE)
```
````
--
  
Notice the options of the chunk and the arguments of the function

--
  
- with .inline-c[results="asis"], `knitr` will pass through results without reformatting them 
- they should remain LaTeX (.inline-c[type = "latex"]) because our outcome document is PDF, converted from LaTeX
- with .inline-c[summary = FALSE], the table will present the data, not its descriptive statistics

---

## .fancy[Example data table with `stargazer`]
  
Table of the first three rows of the dataset

````md
```{r, data_table, echo=FALSE, results="asis"}
stargazer(data = head(df, n = 3), type = "latex", summary = FALSE)
```
````
 
 <center>Table 1: </center>

<table style="text-align:center"><tr><td colspan="12" style="border-bottom: 1px solid black"></td></tr><tr><td style="text-align:left"></td><td>name</td><td>Water_allergy</td><td>Eye color</td><td>Race</td><td>Hair color</td><td>Height</td><td>Publisher</td><td>Skin color</td><td>Alignment</td><td>Weight</td><td>bmi</td></tr>
<tr><td colspan="12" style="border-bottom: 1px solid black"></td></tr><tr><td style="text-align:left">1</td><td>A-Bomb</td><td>Yes</td><td>yellow</td><td>Human</td><td>No Hair</td><td>203</td><td>Marvel Comics</td><td>-</td><td>good</td><td>441</td><td>107</td></tr>
<tr><td style="text-align:left">2</td><td>Abe Sapien</td><td>Yes</td><td>blue</td><td>Icthyo Sapien</td><td>No Hair</td><td>191</td><td>Dark Horse Comics</td><td>blue</td><td>good</td><td>65</td><td>18</td></tr>
<tr><td style="text-align:left">3</td><td>Abin Sur</td><td>Yes</td><td>blue</td><td>Ungaran</td><td>No Hair</td><td>185</td><td>DC Comics</td><td>red</td><td>good</td><td>90</td><td>26</td></tr>
<tr><td colspan="12" style="border-bottom: 1px solid black"></td></tr></table>

???

Show example

---
## .fancy[Example regression table with `stargazer`]
  
.pull-left-c[

Create a table of regression models instead

````md
```{r, regression_table, echo=FALSE, results="asis"}
stargazer(data = lm(Height ~ Weight, data = df), 
          type = "html", header = FALSE,
          title = "Regression Results")
```
````

]

<table style="text-align:center"><caption>Regression Results</caption>
<tr><td colspan="2" style="border-bottom: 1px solid black"></td></tr><tr><td style="text-align:left"></td><td>Dependent variable:</td></tr>
<tr><td></td><td colspan="1" style="border-bottom: 1px solid black"></td></tr>
<tr><td style="text-align:left"></td><td>Height</td></tr>
<tr><td colspan="2" style="border-bottom: 1px solid black"></td></tr><tr><td style="text-align:left">Weight</td><td>0.109***</td></tr>
<tr><td style="text-align:left"></td><td>(0.025)</td></tr>
<tr><td style="text-align:left"></td><td></td></tr>
<tr><td style="text-align:left">Constant</td><td>174.865***</td></tr>
<tr><td style="text-align:left"></td><td>(3.843)</td></tr>
<tr><td style="text-align:left"></td><td></td></tr>
<tr><td colspan="2" style="border-bottom: 1px solid black"></td></tr><tr><td style="text-align:left">Observations</td><td>490</td></tr>
<tr><td style="text-align:left">R2</td><td>0.037</td></tr>
<tr><td style="text-align:left">Adjusted R2</td><td>0.035</td></tr>
<tr><td style="text-align:left">Residual Std. Error</td><td>57.935 (df = 488)</td></tr>
<tr><td style="text-align:left">F Statistic</td><td>18.971*** (df = 1; 488)</td></tr>
<tr><td colspan="2" style="border-bottom: 1px solid black"></td></tr><tr><td style="text-align:left">Note:</td><td style="text-align:right">*p<0.1; **p<0.05; ***p<0.01</td></tr>
</table>

]

---

## .fancy[Summary statistics with `vtable`]

```r
library(vtable)
df  %>% select(Alignment, bmi) %>% st(.) 
```

<table class="table" style="margin-left: auto; margin-right: auto;">
<caption>Summary Statistics</caption>
 <thead>
 <tr>
 <th style="text-align:left;"> Variable </th>
 <th style="text-align:left;"> N </th>
 <th style="text-align:left;"> Mean </th>
 <th style="text-align:left;"> Std. Dev. </th>
 <th style="text-align:left;"> Min </th>
 <th style="text-align:left;"> Pctl. 25 </th>
 <th style="text-align:left;"> Pctl. 75 </th>
 <th style="text-align:left;"> Max </th>
 </tr>
 </thead>
<tbody>
 <tr>
 <td style="text-align:left;"> Alignment </td>
 <td style="text-align:left;"> 734 </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 </tr>
 <tr>
 <td style="text-align:left;"> ... - </td>
 <td style="text-align:left;"> 7 </td>
 <td style="text-align:left;"> 1% </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 </tr>
 <tr>
 <td style="text-align:left;"> ... bad </td>
 <td style="text-align:left;"> 207 </td>
 <td style="text-align:left;"> 28.2% </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 </tr>
 <tr>
 <td style="text-align:left;"> ... good </td>
 <td style="text-align:left;"> 496 </td>
 <td style="text-align:left;"> 67.6% </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 </tr>
 <tr>
 <td style="text-align:left;"> ... neutral </td>
 <td style="text-align:left;"> 24 </td>
 <td style="text-align:left;"> 3.3% </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 <td style="text-align:left;"> </td>
 </tr>
 <tr>
 <td style="text-align:left;"> bmi </td>
 <td style="text-align:left;"> 490 </td>
 <td style="text-align:left;"> 38.557 </td>
 <td style="text-align:left;"> 133.965 </td>
 <td style="text-align:left;"> 0 </td>
 <td style="text-align:left;"> 21 </td>
 <td style="text-align:left;"> 30 </td>
 <td style="text-align:left;"> 2510 </td>
 </tr>
</tbody>
</table>

#### There are many alternatives for creating tables in R Markdown, see `knitr`, `kableExtra`, and `huxtable` packages.

---

# .fat[.fancy[Structure your project]]

---
class: middle, inverse

## .fancy[Structure your project]

### Minimal example

```
.
└── example_project
    ├── R
    ├── README.md 
    ├── analysis
    │    └── template.Rmd
    ├── data
    ├── docs
    ├── example_project.Rproj
    ├── output
    ├── .gitignore
```
]

- .blue-h[R] - Resuable R code (functions etc.)
- .blue-h[analysis] - R Markdown analysis files
- .blue-h[docs] - Rendered analysis reports
- .blue-h[data] - (Raw) data used for analysis
- .blue-h[output] - Output files (e.g., figures, plots...)
- .blue-h[README.md] - project description (will be displayed if added to GitHub)
- .blue-h[.gitignore] - The purpose of gitignore files is to ensure that certain files remain untracked (not added when your code is pushed to GitHub); e.g., data that is not anonymized, irrelevant files 
]

---
class: middle, inverse

## .fancy[Easy project structuring with cookiecutter]

### 1. [Install cookiecutter](https://github.com/lazappi/cookiecutter-r-analysis)

### 2. Generate a new analysis directory: type `cookiecutter gh:lazappi/cookiecutter-r-analysis` (in 📱 terminal 📱)

---

## .fancy[Useful folders to add]

### Subfolders for `/data`

```
├── data
     ├── raw
     └── processed
    
```

### Subfolders for`/output`

```
├── output
     ├── figs
     └── ...
```

### `/config` folder for csl and other custom styling

```
├── config
     
     
```

---
class: middle, inverse

## .fancy[The `R` and `analysis` folders]

#### Your .rmd file lives in the `/analysis` folder. This is where the final script is executed and the final output (e.g., a pdf) is created. 
#### The `/R` folder is used for custom functions that you load in the main .rmd file via `source("remote-functions.R")` at the top of the file.

### The setup chunk becomes:
````md
```{r, setup, include=FALSE}
## chunk option defaults
knitr::opts_chunk$set(echo=FALSE, message=FALSE)
## packages
library(dplyr)
library(ggplot2)
library(stargazer)
library(readxl)
## custom functions
source("remote-functions.R")
```
````

---

## .fancy[Alternative: Easy project structuring with templates from GitHub]

.pull-left[
- Search for an example project structure that serves the purpose, e.g., [here](https://github.com/AnneOkk/example_project). 
- Download the directory
- save at desired location
]

---
class: middle, inverse

## .fat[.fancy[Next level stuff: R packages 🎁]]

### Building R packages is beyond the scope of the workshop but definitely useful to get into. See [R Packages Book](https://r-pkgs.org/) for more information.

---

## .fancy[R Markdown templates]

#### Setup for APA7 articles:

- install and load the papaja library

```r
remotes::install_github("crsh/papaja@devel")
```

- Install the APA 7 (or another style) document class [here](https://www.zotero.org/styles?q=apa)

- Move csl into the correct folder (e.g., `/config`)

- Open an R Markdown APA template in your `/analysis` folder

---
class: middle, inverse

Add this to the YAML header (for APA7 style, see also [here](https://github.com/crsh/papaja/issues/342)):

```
header-includes:
  - |
    \makeatletter
    \renewcommand{\paragraph}{\@startsection{paragraph}{4}{\parindent}%
      {0\baselineskip \@plus 0.2ex \@minus 0.2ex}%
      {-1em}%
      {\normalfont\normalsize\bfseries\typesectitle}}
    
    \renewcommand{\subparagraph}[1]{\@startsection{subparagraph}{5}{1em}%
      {0\baselineskip \@plus 0.2ex \@minus 0.2ex}%
      {-\z@\relax}%
      {\normalfont\normalsize\bfseries\itshape\hspace{\parindent}{#1}\textit{\addperi}}{\relax}}
    \makeatother

csl : "../config/apa.csl" #< path to csl file
documentclass : "apa7"
```

Add this to the YAML header (to knit output to `docs` folder):

```
knit: (function(inputFile, encoding) {
  rmarkdown::render(inputFile, encoding = encoding, output_dir = "../docs") })
```

???

For word: output: apa6_docx

---

# .fat[.fancy[🎉 Yey, you're all set! 🎉 ]]

---

# .salt[.fancy[Your turn! 🤹]]

### Create an R project for your analysis (~ 45 min.)

1. Use `cookiecutter` to create a project from scratch or use a project template that serves the purpose, e.g., [The Example Project](https://github.com/AnneOkk/example_project)
2. Create an R Markdown template that you would like to use (e.g., APA7 paper with `papaja` package) 
3. If you already have an analysis script, move the files into the correct folders (e.g., raw data into `data/raw` subfolder, custom R functions into `R` folder) ❕❗__Do not forget to refer to the files using relative paths__ ❕❗ 
4. 🧶 KNIT to html or pdf