PSY 505: Research Issues and Practices in Psychology

.title[
# PSY 505: Research Issues and Practices in Psychology
]
.subtitle[
## R Markdown and Papaja
]
.author[
### Jason Geller, Ph.D. (he/him/his)
]
.date[
### 2022-09-13
]

---

## What are we going to cover?

- **Markdown:** a simple text-only format for writing documents
- **R markdown:** a tool for mixing R code with markdown 
- **Papaja:** tool for writing APA style articles

---
# Installing R Markdown

- First things first

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

if(!requireNamespace("tinytex", quietly = TRUE)) install.packages("tinytex")

tinytex::install_tinytex()

#this allows us to knit to pdf.You could #download latex but it is a big file.
#tinytex works beautifully
```

---
# Installing R Markdown

--- 
## R markdown is a "chimera"

### On the input side...

- Write text in markdown
- Insert code using R
- Write "metadata" with YAML
- Insert equation with LaTeX
]

---

## R markdown is a "chimera"

### On the output side...

- Output to HTML
- Output to PDF
- Output to Word
- Many other variations too
]
---
lass: middle, inverse

---

.pull-left-narrow[
 .huge-bisque-number[1]
]
.pull-right-wide[
 
.larger[.embolden[Stating the problem...]]

]

---

![](img/word_document_surface.png)

---

![](img/word_document_inside.png)

---

## Word documents are complicated

- A .docx file is a compressed folder with lots of files
- Your text is buried in with a lot of formatting information

---

---

![](img/html_document_inside.png)

---

## HTML documents are complicated

- Looks simple because I removed most formatting
- Still unpleasant to look at

---

]

---

## What do we want?

- Something that... you can write in **plain text**
- Something that... is **human readable**
- Something that... allows **formatting**
- Something that... can **build** to something pretty

---

---

.pull-left-wide[
```
# Introduction
Welcome to my **awesome** class. You will learn 
all kinds of useful things about R markdown. 
## Why should you care?
- Markdown is simple and reproducible
- You can make it pretty if you want to
- The R Markdown variant lets you add R code
```
]

---

---

# Introduction

Welcome to my **awesome** class. You will learn 
all kinds of useful things about R markdown.

## Why should you care?

- Markdown is simple and reproducible
- You can make it pretty if you want to
- The R Markdown variant lets you add R code

---

## Notice the theme!

- My slides are written using markdown (...sort of)
- So the markdown output you see here matches the slides theme
- I'll talk about modifying themes later

---
# What does this have to do with open science?

Using Markdown to generate publications, reports, websites, etc. will:
* Make dynamically updating them with new results easier
* Reduce errors from manually entering results 
* Create new venues for science communication

Using Markdown to organize your code will:
* Allow you to organize and annotate your analyses 
* Make it easier for others to tell what you did, aiding reproducibility

---

---

---

## Professional websites

---

## Visual blogs

---

## Books

---

## Academic papers

---

## Slide decks

---

]

---

.pull-left-narrow[
 .huge-bisque-number[4]
]
.pull-right-wide[
 
.larger[.embolden[Starting markdown]]

]

---

---
## Emphasising text

--
.pull-left[
### What you type...
 
```
this is *italics*
this is **bold**
this is ***bold italics***
```
]
--
.pull-right[
### What you get...

this is *italics*

this is **bold**

this is ***bold italics***
]

---

## Creating lists

--
.pull-left[
### What you type...
 
```
- unnumbered lists
- look like this
1. numbered lists
2. look like this
```
]
--
.pull-right[
### What you get...

- unnumbered lists
- look like this

1. numbered lists
2. look like this
]

---

## Creating headings

--
.pull-left[
### What you type...
 
```
# Level 1 heading
## Level 2 heading
### Level 3 heading
```
]
--
.pull-right[
### What you get...

# Level 1 heading
## Level 2 heading
### Level 3 heading
]

---

---

- Create your own RMD
- Open a new markdown document
- Save it as `my_first_markdown.md`
- Write some markdown, build it to HTML file
- Try to use all these markdown features

---

]

---

## Inserting hyperlinks

--
.pull-left-wide[
### What you type...
 
```
https://placekitten.com
[Placekitten](https://placekitten.com)
```
]
--
.pull-right-narrow[
### What you get...
 
https://placekitten.com

[Placekitten](https://placekitten.com)
]

---
## Inserting local images
--
.pull-left[
### What you type...
```
![](./img/rmarkdown.png)
```
]
--
.pull-right[
### What you get...
![](./img/rmarkdown.png)
]

---

## Inserting images from the web

--
.pull-left[
### What you type...
```
![](https://placekitten.com/200/300)
```
]
--
.pull-right[
### What you get...
![](https://placekitten.com/200/300)
]

---

## Using blockquotes

--
.pull-left[
 
### What you type...
 
```
This is normal text
> This is a block quote
```
]
--
.pull-right[
 
### What you get...
This is normal text
> This is a block quote
]

---

## Using nested lists

--
.pull-left[
 
### What you type...
 
```
1. First item in list 
2. Second item in list
 - first item in sub-list
 - second item in sub-list
3. Third item in list
```
]
--
.pull-right[
 
### What you get...
 
1. First item in list 
2. Second item in list
 - first item in sub-list
 - second item in sub-list
3. Third item in list
]

---

]

---

## What do we want?

- Something that... lets you write text in **markdown**
- Something that... lets you include **R code** (e.g. for data vis)
- Something that... can **build** to HTML, PDF, Word, etc

---

---

## Let's dissect the document we just wrote!

---

## The part inside ` --- ` is the "YAML header"

---

<h2>The part inside <code>&#96;&#96;&#96;{r}</code> is R code</h2>

---

## The rest is markdown

---

.pull-left-narrow[
 .huge-bisque-number[7]
]
.pull-right-wide[
 
.larger[.embolden[Custom documents]]

]

---

## The YAML header is used for customisation

---

## Wait... what's the YAML acronym?

- Originally: "Yet Another Markup Language"
- Later: "YAML Ain't Markup Language"
- ... it really doesn't matter 🙄

---

## Output HTML only
```
---
title: "My First R Markdown Document"
author: "Danielle J. Navarro"
date: "10/02/2021"
output: html_document
---
```

---

## Output HTML and PDF

```
---
title: "My First R Markdown Document"
author: "Danielle J. Navarro"
date: "10/02/2021"
output:
  pdf_document: default
  html_document: default
---
```

- Notice the indentation
- YAML is *very* picky about this

---

---

## Themes for HTML documents

```
---
output: 
  html_document:
    theme: readable
---
```

**Possible themes**: default, cerulean, journal, flatly, darkly, readable, spacelab, united, cosmo, lumen, paper, sandstone, simplex, yeti

---

## Table of contents

```
output:
  html_document:
    toc: true
    toc_float: true
```

---

- Practice editing the YAML header
- Delete everything but the header and knit. What changed?
- Try creating different outputs and themes
- Try creating a floating table of contents
- Try to get it to not float!

---

.pull-left-narrow[
 .huge-bisque-number[8]
]
.pull-right-wide[
 
.larger[.embolden[Inserting equations]]

]
---

## An overview

- Anything inside dollar signs `$` is treated as "inline" maths
- Anything inside two dollar `$$` is a standalone equation
- Whitespace matters: `$x$` is an equation, `$x $` is not
- Equations follow "LaTeX" rules

---

## Equations are special

.pull-left[
```
This $x^2$ is inline
This equation is standalone
$$
a^2 + b^2 = c^2
$$
```
]
--
.pull-right[This `$x^2$` is inline]

---
# Hiding the Mess

- Options for code chunks

- At the start of your document in a code chunk or within each chunk `{r}`

---

# Exercise

- Edit the code chunks that are contained within the default template

- Add a fig caption

# Visual Editor

- One fairly new feature (and one reason we're using RStudio today!) is their new [visual markdown editor](https://rstudio.github.io/visual-markdown-editing/). It's basically an ultra powerful hybrid of Markdown and Microsoft Word. But be warned, it's a little buggy if you frequently switch editing modes.

- People write whole books in Markdown, and this may make that seem a little more achievable. For example, the new visual editor allows [easy citation management with a Zotero library](https://www.rstudio.com/blog/rstudio-1-4-preview-citations/) (if we have time, I'll show you this on my computer). 
---

# Cheat Sheet

- https://www.markdownguide.org/cheat-sheet/

---

# The Future

- [Quarto](https://quarto.org/) is a sequel to RMarkdown developed by RStudio.

- While they are still maintaining RMarkdown, a lot of new development will probably happen in Quarto.

- The differences between RMarkdown and Quarto are not huge for R users ([overview here](https://yihui.org/en/2022/04/quarto-r-markdown/)), and there is much more RMarkdown documentation available, which is why I taught it today.

I encourage you to keep tabs on Quarto's development and try it out, especially if you're not an R user.

---
class: middle, inverse

# Papaja

---

# Installing Papaja

```r
# Install latest CRAN release
#install.packages("papaja")

# Install remotes package if necessary
#if(!requireNamespace("remotes", quietly = TRUE)) install.packages("remotes")

# Install the stable development version from GitHub
#remotes::install_github("crsh/papaja")

# Install the latest development snapshot from GitHub
#remotes::install_github("crsh/papaja@devel")
```

---
# Open Papaja