Workshop: Writing reproducible APA-style manuscripts in R

background-image: url("data:image/png;base64,#https://github.com/allisonhorst/stats-illustrations/raw/master/rstats-artwork/welcome_to_rstats_twitter.png")
background-position: 50% 0%
background-size: 60%
class: bottom

## Writing reproducible manuscripts in R
[**Shilaan Alzahawi**](http://shilaan.rbind.io) @ Stanford Graduate School of Business  
Artwork by [@allison_horst](https://github.com/allisonhorst/stats-illustrations)

---

### Do your data sci like it's going to need an alibi

Slides at [bit.ly/shilaan-apa](https://bit.ly/shilaan-apa)  
Artwork by [@allison_horst](https://github.com/allisonhorst/stats-illustrations)

---
background-image: url("data:image/png;base64,#https://github.com/allisonhorst/stats-illustrations/raw/master/make-your-own-stats-cartoons/ex_3.png")
background-position: 90% 50%
background-size: 38%

# Introduction 🧊🔨

`\(~~\)`  
`\(~~\)`

**Statistics** @ Ghent University  
**Organizational Behavior** @ Stanford GSB

🔎 `\(~\)` Statistical inference & hypothesis testing  
🔎 `\(~\)` Open and reproducible science  
🔎 `\(~\)` Crowdsourced & big team science

---

# Outline

**What?**

📝  `\(~\)` Reproducible manuscripts

**Why?**

✅ `\(~\)` Benefits

**How?**

🛠 `\(~\)` Tutorial   
`\(~~~~~~\)` pt. 1: An introduction to **R Markdown**   
`\(~~~~~~\)` pt. 2: An introduction to **papaja**

`\(~~\)`  
Example manuscripts at [github.com/shilaan/example-manuscripts](https://github.com/shilaan/example-manuscripts)

---

# The typical workflow

When writing a scientific report, the typical workflow is to ...

1. Do your analyses (e.g., in `R`, `Python`, `SPSS`, `SAS`, `Matlab`, or `Stata`)

--
2. Copy-paste or otherwise save your graphs and results

--
3. Open a program (e.g., `Microsoft Word`) to communicate the results

4. Manually format your results and citations

### Discussion questions

What are common challenges when working in this fashion?  
What kind of problems could arise?

---
class:center, middle

---

---

# Typical workflow challenges

- Time-consuming

- Error-prone (e.g., rounding or transcription errors)

- Lacks transparency; difficult to reproduce (by others **and** yourself!)

- Difficult to maintain and update (endless rewriting and reformatting...)

- Overhead costs of different computing/software environments

- **Anything else...?**

---
background-image: url("data:image/png;base64,#https://upload.wikimedia.org/wikipedia/en/f/ff/SuccessKid.jpg")
background-position: 50% 92%
background-size: 45%

## An alternative workflow: What?

- Fuse your code and writing

- Directly embed results in your report

- Automatically reflect analytic changes in your documentation

- Update all your results, figures, and tables automatically

- Automatic formatting (including citations!)

---
background-image: url("data:image/png;base64,#https://raw.githubusercontent.com/allisonhorst/stats-illustrations/master/rstats-artwork/data_cowboy.png")
background-position: 90% 40%
background-size: 50%

## An alternative workflow: Why?

Less...

⬇️ Error-prone  
 
 
--

⬇️ Time-consuming
 
 
--

More...

⬆️ Dynamic     
 
--

⬆️ Reproducible

⬆️ Transparent  (for others **and** yourself)

---
background-image: url("data:image/png;base64,#https://bookdown.org/yihui/rmarkdown/images/hex-rmarkdown.png")
background-position: 50% 90%
background-size: 20%

## Our weapon of choice: RMarkdown

- RMarkdown is an **authoring framework for data science**, designed for reproducibility

- The same document holds the code and the narrative surrounding the data

- Results are automatically generated from the code

- You can use a single R Markdown file to    
✓ save and execute code, and   
✓ generate high quality reports that can be shared with an audience

---

Artwork by [@allison_horst](https://github.com/allisonhorst/stats-illustrations):  
**Get your code, text, and outputs in the same (reproducible) place**

---

## Introduction to RMarkdown
--

- Create dynamic analysis documents that combine code, output (incl. figures and tables), and writing

- Can be used to  
✓ Reproduce your analyses  
✓ Collaborate and share code with others  
✓ Communicate your results with others

- Output formats include HTML, PDF, Word and...  
🤩 Slide shows ([bit.ly/shilaan-apa](https://shilaan-apa.netlify.app))    
🤩 Websites ([shilaan.rbind.io](http://shilaan.rbind.io))  
🤩 Blogs  
🤩 Books  
🤩 CVs    
🤩 Dashboards  
🤩 Interactive documents   
🤩 Conference posters  
🤩 Manuscripts

---
background-image: url("data:image/png;base64,#images/manuscript.png")
background-position: 50% 80%
background-size: contain

## Sneak peek: the power of RMarkdown
---

background-image: url("data:image/png;base64,#images/cites.png")
background-position: 50% 70%
background-size: contain

## Sneak peek: the power of RMarkdown
---

background-image: url("data:image/png;base64,#images/refs.png")
background-position: 50% 50%
background-size: contain

## Sneak peek: the power of RMarkdown
---
## Discussion question

#### Are there good reasons for **not** using **RMarkdown**?

--
<svg viewBox="0 0 512 512" style="position:relative;display:inline-block;top:.1em;fill:#035AA6;height:1.5em;" xmlns="http://www.w3.org/2000/svg">  <path d="M256 8C119.043 8 8 119.083 8 256c0 136.997 111.043 248 248 248s248-111.003 248-248C504 119.083 392.957 8 256 8zm0 448c-110.532 0-200-89.431-200-200 0-110.495 89.472-200 200-200 110.491 0 200 89.471 200 200 0 110.53-89.431 200-200 200zm107.244-255.2c0 67.052-72.421 68.084-72.421 92.863V300c0 6.627-5.373 12-12 12h-45.647c-6.627 0-12-5.373-12-12v-8.659c0-35.745 27.1-50.034 47.579-61.516 17.561-9.845 28.324-16.541 28.324-29.579 0-17.246-21.999-28.693-39.784-28.693-23.189 0-33.894 10.977-48.942 29.969-4.057 5.12-11.46 6.071-16.666 2.124l-27.824-21.098c-5.107-3.872-6.251-11.066-2.644-16.363C184.846 131.491 214.94 112 261.794 112c49.071 0 101.45 38.304 101.45 88.8zM298 368c0 23.159-18.841 42-42 42s-42-18.841-42-42 18.841-42 42-42 42 18.841 42 42z"></path></svg> `\(~~~\)` Anything else?

---

# Part 1: RMarkdown

---

# Getting started with RMarkdown

- Install [`R`](https://cran.r-project.org/mirrors.html)
- Install [`RStudio`](https://www.rstudio.com/products/rstudio/download/)
- Install the `RMarkdown` package  
- Install `\(\LaTeX\)` (e.g., `TinyTex`)

```r
install.packages("rmarkdown")
install.packages("tinytex") # for generating PDF output
tinytex::install_tinytex()  # install TinyTeX
```

---

## Opening a new R Markdown

- Create a new R Markdown document from the menu  
`File -> New File -> R Markdown`

---

## Notebook interface

- Allows for direct interaction with R (execute code and display results inline)
- Makes it easy to test and iterate
- Produces a reproducible document with publication-quality output

---

## Three types of content
- YAML meta-data / frontmatter (between `---` and `---`)
- Text with Markdown formatting
- R code

---

# Metadata

---
background-image: url("data:image/png;base64,#https://cwextensions.com/images/logo-someta.png")
background-position: 92% 7%
background-size: 10%

# YAML metadata

The YAML header contains basic metadata and rendering instructions

```yaml
---
title: My R Markdown Report
author: Shilaan Alzahawi
output: pdf_document
date: "2021-11-09"
---
```

The date will be **dynamically updated** every time we knit the report,  
with the help of the following line of code (more on **in-line code** later):

---

# Preview an RMarkdown

---

# Rendering a document

✓ ![knit](data:image/png;base64,#images/knit.png)  
✓ Windows/Linux: `Control + Shift + K`   
✓ OS X: `Command + Shift + K`

---

Artwork by [@allison_horst](https://github.com/allisonhorst/stats-illustrations):  
**Become an RMarkdown knitting wizard**

---

## Output formats

![](data:image/png;base64,#https://d33wubrfki0l68.cloudfront.net/ece57b678854545e6602a23daede51ad72da2170/21cca/lesson-images/outputs-1-word.png)

---

## Output formats

![](data:image/png;base64,#https://d33wubrfki0l68.cloudfront.net/ebcf2beeb67cc21693d73b8708d5af0fa9769f57/de9a9/lesson-images/outputs-2-pdf.png)

---

## What's happening behind the scenes?

![A diagram illustrating how an R Markdown document is converted to the final output document](data:image/png;base64,#https://bookdown.org/yihui/rmarkdown-cookbook/images/workflow.png)

☞ The code within the `.Rmd` file is executed and converted into an `.md` file;  
☞ The `.md` file is converted to the output format specified in the metadata

---

## What's happening behind the scenes?

Knitting an `RMarkdown` file...

1. Starts a new R session  
✓ No packages or objects loaded

2. Sets your working directory to the location of the `RMarkdown` file

3. Executes all code chunks from top to bottom

### ⚠️ **Make sure to load all R packages you use!**

<img src="data:image/png;base64,#https://github.com/allisonhorst/stats-illustrations/raw/master/make-your-own-stats-cartoons/ex_4.png" width="45%" style="display: block; margin: auto;" />
Artwork by [@allison_horst](https://github.com/allisonhorst/stats-illustrations)

---

# Code

---

## Two types of code in RMarkdown

1. A code chunk, surrounded by three backticks and `{r}`
2. An inline code expression, surrounded by one backtick and `r`

---

## Code chunks

"*Code chunks are the beating heart of our R Markdown.*" 
[Xie, Dervieux, Riederer 2021](https://bookdown.org/yihui/rmarkdown-cookbook/rmarkdown-anatomy.html)

```r
summary(Orange)
```

```
##  Tree       age         circumference  
##  3:7   Min.   : 118.0   Min.   : 30.0  
##  1:7   1st Qu.: 484.0   1st Qu.: 65.5  
##  5:7   Median :1004.0   Median :115.0  
##  2:7   Mean   : 922.1   Mean   :115.9  
##  4:7   3rd Qu.:1372.0   3rd Qu.:161.5  
##        Max.   :1582.0   Max.   :214.0
```

### Inserting a code chunk

--
✓ Windows/Linux: `Control + Alt + I`

--
✓ OS X: `Command + Option + I`

--
✓ Enclosing code with three backticks and `{r}`

--
✓ ![](data:image/png;base64,#https://d33wubrfki0l68.cloudfront.net/b8b19518e688e3ca1390e0a1588916f04908d33f/8a4dc/images/notebook-insert-chunk.png)
---

## Inserting code chunks

---

## Chunk anatomy

---

## Naming your code chunks

It's recommended to name your chunks. This allows you to quickly navigate code, automatically name figures, and troubleshoot errors.

---

## Chunk options

Control a chunk's behavior by passing additional, comma-separated arguments

✓ `echo = TRUE` show code and output (*default*)

✓ `echo = FALSE` show output only (hide code)

✓ `include = FALSE` do not show output (run code)

✓ `eval = FALSE` show code (do not run; no output)

✓ `warning = FALSE` removes warning messages

✓ `error = FALSE` removes error messages

✓ `message = FALSE` removes all messages

```r
summary(Orange)
```

--
**Bonus question:** What chunk option did I set here?

---

## Chunk options

Credit for all GIFs goes to [Shannon Pileggi](https://www.pipinghotdata.com/posts/2020-09-07-introducing-the-rstudio-ide-and-r-markdown/#rmd)

---
## Chunk execution

`Ctrl + Enter` or `Command + Enter` or press ![](data:image/png;base64,#https://www.pipinghotdata.com/posts/2020-09-07-introducing-the-rstudio-ide-and-r-markdown/img/run-chunk.PNG)

---

## In-line code

To insert in-line code, wrap your code in a single backtick. RMarkdown will always
- display the results of inline code, but not the code  
- apply relevant text formatting to the results

**R Markdown document**   
<img src="data:image/png;base64,#images/inline.png" width="1867" />

--
**Knitted HTML document**  
<img src="data:image/png;base64,#images/inline-knitted.png" width="1667" />

---

# Text

---

# Markdown formatting basics

![](data:image/png;base64,#https://d33wubrfki0l68.cloudfront.net/59f29676ef5e4d74685e14f801bbc10c2dbd3cef/c0688/lesson-images/markdown-1-markup.png)

---

![](data:image/png;base64,#images/syntax-becomes.png)

For more formatting options, see the [R Markdown Reference guide](https://www.rstudio.com/wp-content/uploads/2015/03/rmarkdown-reference.pdf?_ga=2.157796986.1542626288.1625161001-1806201684.1624641897)

---

## Tables