Introduction to papaja

class: center, middle, inverse, title-slide

# Introduction to papaja
## R Markdown for APA-style manuscripts
### Johannes Breuer & Frederik Aust
### KU Leuven, 27.-28.04.2022

---

exclude: true

---
layout: true
template: footer

---

# Scope of the package

**P**reparing **APA** **J**ournal **A**rticles

1. Designed for APA-style manuscripts
2. Templates for PDF and DOCX documents
--

3. Functions to facilitate reporting of results, e.g.
    - `apa_print()`, `apa_num()`
    - `apa_table()`
    - `apa_factorial_plot()`, `theme_apa()`

---
# Getting started

Install papaja from GitHub

```r
# Install the stable development verions from GitHub
remotes::install_github("crsh/papaja", build_vignettes = TRUE)

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

*Ensure the [required software](http://frederikaust.com/papaja_man/introduction.html#getting-started) is also installed*

---
layout: true
template: footer
name: templates

# Document templates

---
.center-70[![](data:image/png;base64,#https://raw.githubusercontent.com/crsh/papaja/master/inst/images/template_selection.png)]

---
.center-70[<img src="data:image/png;base64,#img/papaja_skeleton.png" width="1020" style="display: block; margin: auto;" />]

---
layout: true
template: footer

---

| YAML field | Metadata |
|-----------|--------------------------------------|
| `author` | list of author information (e.g., `name` and `affiliation`; start each new author with `-`) |
| `affiliation` | list of institutional information (`id` and `institution`) |
| `authornote` | automatically contains corresponding author line |
| `keywords` | article keywords |
| `wordcount` | article word count |
| `note` | text to add above author note on the title page (e.g. "Preprint submitted for publication") |

---
### Rendering options

| YAML field | Effect |
|-----------|--------------------------------------|
| `bibliography` | List of bibliography files |
| `draft`\* | Add "DRAFT" watermark across all pages |
| `figurelist`\* `tablelist`\* `footnotelist`\* | Create lists of figure captions, table captions, or footnotes |

\* Only available for PDF documents

---
### Rendering options

| YAML field | Effect |
|-----------|--------------------------------------|
| `floatsintext`\* | Place figures and tables in the text rather than at the end |
| `linenumbers`\* | Add line numbers in margins |
| `mask` | Omit identifying information from title page |
| `classoption`\* | control the style of the document (e.g., `man` or `doc`, see [`apa6`](https://mirror.hmc.edu/ctan/macros/latex/contrib/apa6/apa6.pdf) LaTeX class options) |

\* Only available for PDF documents

???
* Only available for PDF documents

---
exclude: true
layout: false
template: templates

Use `papaja::apa6_pdf()` or `papaja::apa6_docx()` as output formats

- Extend `bookdown::pdf_document2()` and `bookdown::word_document2()`
 
- `papaja::apa6_docx()` is more limited
 
 - Some minimal manual tweaking of DOCX required for now (see [manual](https://crsh.github.io/papaja_man/limitations.html#microsoft-word-documents))

---
layout: true
template: footer
name: citations

# Citations

---
`citeproc` is a `pandoc` extension that formats references

- works well for both PDF and DOCX documents
- requires a separate reference file (e.g., CSL-JSON, Bib(La)TeX, EndNote)

Add the following to the YAML front matter:

```yaml
bibliography: references.bib
```

In **papaja**, the default citation style is APA, 6th edition.

---
The reference handle is used to select citations

| Citation type | Syntax | Rendered citation |
|:--------------|:-------|:------------------|
| Citation within parentheses | `[@james_1890]` | (James, 1890) |
| Multiple citations | `[@james_1890; @bem_2011]` | (Bem, 2011; James, 1890) |
| In-text citations | `@james_1890` | James (1890) |
| Year only | `[-@bem_2011]` | (2011) |

???
Open and show BibTeX file

---
You can add pre- and post-fixes to individual citations

- `[e.g., @bem_2011]` yields "(e.g., Bem, 2011)"
- `[see @bem_2011 for a surprising result]` yields "(see Bem, 2011, for a surpising result)"

---

Insert citations via

1. (Copy-and-paste)
2. Visual editor
3. RStudio addin [`citr`](https://github.com/crsh/citr)

Both connect directly to Zotero if the Zotero extension [Better Bib(La)TeX](https://github.com/retorquere/zotero-better-bibtex/wiki) is installed and Zotero is running

???
Demonstration!

---
layout: false
class: middle, center

# A quick demonstration!

---
layout: true
template: footer
name: citingr

# Citing R packages

---
_Reward volunteers who develop R packages for free!_ ;)

```r
citation("papaja")
```

```
## 
##   Aust, F. & Barth, M. (2020). papaja: Prepare reproducible APA journal
##   articles with R Markdown. R package version 0.1.0.9999. Retrieved
##   from https://github.com/crsh/papaja
## 
## Ein BibTeX-Eintrag für LaTeX-Benutzer ist
## 
##   @Manual{,
##     title = {{papaja}: {Prepare} reproducible {APA} journal articles with {R Markdown}},
##     author = {Frederik Aust and Marius Barth},
##     year = {2020},
##     note = {R package version 0.1.0.9999},
##     url = {https://github.com/crsh/papaja},
##   }
```

---

- `r_refs()` creates a BibTeX file with references for all loaded packages (place at the end of document)
--

- `cite_r()` automates citing R and R packages

```r
r_citations <- cite_r(file = "r-references.bib")
```

<div class="remark-code-line"><code class="r hljs remark-code">We used &#96;r r_citations&#96; for all analyses.</code></div>

> We used R (Version 4.1.3; R Core Team, 2022) and the R-package papaja (Version 0.1.0.9999; Aust & Barth, 2022) for all analyses.

---

Cite only selected packages or place package citations in a footnote

```r
r_citations <- cite_r(
 file = "r-references.bib"
 , pkgs = c("afex", "emmeans", "papaja"), withhold = FALSE
 , footnote = TRUE
)
r_citations
```

```
## Warning in cite_r(file = "../../exercises/3_papaja_example_manuscript/
## r-references.bib", : File ../../exercises/3_papaja_example_manuscript/r-
## references.bib not found. Cannot cite R-packages. If knitting again does not
## solve the problem, please check file path.
```

```
## $r
## [1] "R [Version 4.1.3; @R-base]"
```

---

Cite only selected packages or place package citations in a footnote

```r
r_citations <- cite_r(
 file = "r-references.bib"
 , pkgs = c("afex", "emmeans", "papaja"), withhold = FALSE
 , footnote = TRUE
)
```

<div class="remark-code-line"><code class="r hljs remark-code">We used &#96;r r_citations$r&#96; for all analyses.

&#96;r r_citations$pkgs&#96;
</code></div>

???
If `withhold = TRUE`, `pkgs` is a blacklist, otherwise it is a whitelist

Demonstrate what this would look like in a document

---
layout: true
template: footer
name: results

# Report statistical analyses

---
Numerical values reported inline will be rounded

<div class="remark-code-line"><code class="r hljs remark-code">Participants mean age was &#96;r age_mean&#96; years (*SD* = &#96;r age_sd&#96;).</code></div>

> Participants mean age was 32.35 years (*SD* = 6.23).

--
exclude: true

For more typesetting control use
- `apa_num()`, `apa_p()`, `apa_df()`
- `apa_interval()`, `apa_confint()`

---
Typeset numerical values for greater control

```r
apa_num(c(143234.34557, Inf))
```

```
## [1] "143,234.35" "$\\infty$"
```

```r
apa_num(42L, numerals = FALSE, capitalize = TRUE)
```

```
## [1] "Forty-two"
```

```r
apa_num(1.7e10, format = "e")
```

```
## [1] "$1.70 \\times 10^{10}$"
```

---

Special-purpose wrappers for convenience

```r
apa_p(c(1, 0.0008, 0))
```

```
## [1] "> .999" ".001" "< .001"
```

```r
apa_df(c(1, 15.93))
```

```
## [1] "1"     "15.93"
```

```r
apa_confint(c(0.01, 0.8), conf.int = 0.95)
```

```
## [1] "95\\% CI [0.01, 0.80]"
```

???
Demonstrate some of the options

---

```r
# Data from Field, Miles, & Field (2012)
load("cosmetic_surgery.Rdata")

(cor_res <- with(cosmetic_surgery, cor.test(Post_QoL, BDI)))
```

```
## 
## 	Pearson's product-moment correlation
## 
## data:  Post_QoL and BDI
## t = 7.7581, df = 274, p-value = 1.71e-13
## alternative hypothesis: true correlation is not equal to 0
## 95 percent confidence interval:
##  0.3224754 0.5165716
## sample estimates:
##       cor 
## 0.4243863
```

---
`apa_print()` facilitates reporting of results. It returns a `list` with the following elements:

- `estimate`: Effect size estimate
- `statistic`: Hypothesis test statistic
- `full_result`: Combined estimates and statistics
- `table`

---

```r
cor_apa_res <- apa_print(cor_res)
cor_apa_res[c("estimate", "statistic", "full_result")]
```

```
## $estimate
## [1] "$r = .42$, 95\\% CI $[.32, .52]$"
## 
## $statistic
## [1] "$t(274) = 7.76$, $p < .001$"
## 
## $full_result
## [1] "$r = .42$, 95\\% CI $[.32, .52]$, $t(274) = 7.76$, $p < .001$"
```

---

```r
cor_apa_res$table
```

```
## A data.frame with 5 labelled columns:
## 
## estimate conf.int statistic df p.value
## 1 .42 [.32, .52] 7.76 274 < .001
## 
## estimate : $r$ 
## conf.int : 95\\% CI 
## statistic: $t$ 
## df : $\\mathit{df}$ 
## p.value : $p$
```

---
`apa_print()` adjusts behavior according to input

```r
class(cor_res) # Result from cor.test()
```

```
## [1] "htest"
```

```r
?apa_print.htest
```

`methods(apa_print)` provides a list of supported classes

---

<table>
 <thead>
 <tr>
 <th style="text-align:left;"> A-B </th>
 <th style="text-align:left;"> D-L </th>
 <th style="text-align:left;"> L-S </th>
 <th style="text-align:left;"> S-Z </th>
 </tr>
 </thead>
<tbody>
 <tr>
 <td style="text-align:left;"> afex_aov </td>
 <td style="text-align:left;"> default </td>
 <td style="text-align:left;"> lsmobj </td>
 <td style="text-align:left;"> summary.glht </td>
 </tr>
 <tr>
 <td style="text-align:left;"> anova </td>
 <td style="text-align:left;"> emmGrid </td>
 <td style="text-align:left;"> manova </td>
 <td style="text-align:left;"> summary.glm </td>
 </tr>
 <tr>
 <td style="text-align:left;"> anova.lme </td>
 <td style="text-align:left;"> glht </td>
 <td style="text-align:left;"> merMod </td>
 <td style="text-align:left;"> summary.lm </td>
 </tr>
 <tr>
 <td style="text-align:left;"> Anova.mlm </td>
 <td style="text-align:left;"> glm </td>
 <td style="text-align:left;"> mixed </td>
 <td style="text-align:left;"> summary.manova </td>
 </tr>
 <tr>
 <td style="text-align:left;"> aov </td>
 <td style="text-align:left;"> htest </td>
 <td style="text-align:left;"> papaja_wsci </td>
 <td style="text-align:left;"> summary.ref.grid </td>
 </tr>
 <tr>
 <td style="text-align:left;"> aovlist </td>
 <td style="text-align:left;"> list </td>
 <td style="text-align:left;"> summary.Anova.mlm </td>
 <td style="text-align:left;"> summary_emm </td>
 </tr>
 <tr>
 <td style="text-align:left;"> BFBayesFactor </td>
 <td style="text-align:left;"> lm </td>
 <td style="text-align:left;"> summary.aov </td>
 <td style="text-align:left;"> </td>
 </tr>
 <tr>
 <td style="text-align:left;"> BFBayesFactorTop </td>
 <td style="text-align:left;"> lme </td>
 <td style="text-align:left;"> summary.aovlist </td>
 <td style="text-align:left;"> </td>
 </tr>
</tbody>
</table>

See `vignette("extending_apa_print", package = "papaja")`.

---

```r
lm_res <- lm(Post_QoL ~ Base_QoL + BDI, data = cosmetic_surgery)

lm_res_apa <- apa_print(lm_res, observed = TRUE)
str(lm_res_apa, max.level = 2)
```

```
## List of 4
## $ estimate :List of 4
## ..$ Intercept: chr "$b = 18.50$, 95\\% CI $[13.10, 23.91]$"
## ..$ Base_QoL : chr "$b = 0.59$, 95\\% CI $[0.50, 0.67]$"
## ..$ BDI : chr "$b = 0.17$, 95\\% CI $[0.11, 0.22]$"
## ..$ modelfit :List of 4
## $ statistic :List of 4
## ..$ Intercept: chr "$t(273) = 6.74$, $p < .001$"
## ..$ Base_QoL : chr "$t(273) = 13.23$, $p < .001$"
## ..$ BDI : chr "$t(273) = 6.08$, $p < .001$"
## ..$ modelfit :List of 1
## $ full_result:List of 4
## ..$ Intercept: chr "$b = 18.50$, 95\\% CI $[13.10, 23.91]$, $t(273) = 6.74$, $p < .001$"
## ..$ Base_QoL : chr "$b = 0.59$, 95\\% CI $[0.50, 0.67]$, $t(273) = 13.23$, $p < .001$"
## ..$ BDI : chr "$b = 0.17$, 95\\% CI $[0.11, 0.22]$, $t(273) = 6.08$, $p < .001$"
## ..$ modelfit :List of 1
## $ table :Classes 'apa_results_table' and 'data.frame':	3 obs. of 6 variables:
## ..$ term : 'tiny_labelled' chr [1:3] "Intercept" "Base QoL" "BDI"
## .. ..- attr(*, "label")= chr "Predictor"
## ..$ estimate : 'tiny_labelled' chr [1:3] "18.50" "0.59" "0.17"
## .. ..- attr(*, "label")= chr "$b$"
## ..$ conf.int : 'tiny_labelled' chr [1:3] "[13.10, 23.91]" "[0.50, 0.67]" "[0.11, 0.22]"
## .. ..- attr(*, "label")= chr "95\\% CI"
## ..$ statistic: 'tiny_labelled' chr [1:3] "6.74" "13.23" "6.08"
## .. ..- attr(*, "label")= chr "$t$"
## ..$ df : 'tiny_labelled' chr [1:3] "273" "273" "273"
## .. ..- attr(*, "label")= chr "$\\mathit{df}$"
## ..$ p.value : 'tiny_labelled' chr [1:3] "< .001" "< .001" "< .001"
## .. ..- attr(*, "label")= chr "$p$"
## ..- attr(*, "family")= chr "gaussian"
## ..- attr(*, "link")= chr "identity"
## - attr(*, "class")= chr [1:2] "apa_results" "list"
```

---

```r
lm_res_apa$estimate$Intercept
```

```
## [1] "$b = 18.50$, 95\\% CI $[13.10, 23.91]$"
```

> `$b = 18.50$`, 95% CI `$[13.10, 23.91]$`

```r
lm_res_apa$full_result$modelfit$r2
```

```
## [1] "$R^2 = .50$, 90\\% CI $[0.42, 0.57]$, $F(2, 273) = 136.78$, $p < .001$"
```

> `$R^2 = .50$`, 90% CI `$[0.42, 0.57]$`, `$F(2, 273) = 136.78$`, `$p < .001$`

???
Show how to look up method arguments

---
layout: true
template: footer
name: tables

# Rendering Tables

---
Tables returned by `apa_print()` have variable labels

```r
lm_res_apa$table
```

```
## A data.frame with 6 labelled columns:
## 
## term estimate conf.int statistic df p.value
## 1 Intercept 18.50 [13.10, 23.91] 6.74 273 < .001
## 2 Base QoL 0.59 [0.50, 0.67] 13.23 273 < .001
## 3 BDI 0.17 [0.11, 0.22] 6.08 273 < .001
## 
## term : Predictor 
## estimate : $b$ 
## conf.int : 95\\% CI 
## statistic: $t$ 
## df : $\\mathit{df}$ 
## p.value : $p$
```

---
Tables returned by `apa_print()` have variable labels

```r
variable_labels(lm_res_apa$table)
```

```
## $term
## [1] "Predictor"
## 
## $estimate
## [1] "$b$"
## 
## $conf.int
## [1] "95\\% CI"
## 
## $statistic
## [1] "$t$"
## 
## $df
## [1] "$\\mathit{df}$"
## 
## $p.value
## [1] "$p$"
```

---
`apa_table()` renders tables with variable labels

```r
apa_table(
  lm_res_apa$table
  , caption = "Cosmetic surgery regression table."
)
```

<center>Table 1. *Cosmetic surgery regression table.*<center>

| `$\mathrm{Predictor}$` | `$b$` | `$\mathrm{95\% CI}$` | `$t$` | df         | `$p$` |
|:--------------|-------:|:-------------------:|-------:|-----------:|----:|
| Intercept     | 18.50  |  `$[13.10$`, `$23.91]$` | 6.74   | 273 | &lt; .001  |
| Base QoL      | 0.59   |  `$[0.50$`, `$0.67]$`   | 13.23  | 273 | &lt; .001  |
| BDI           | 0.17   |  `$[0.11$`, `$0.22]$`   | 6.08   | 273 | &lt; .001  |

---
`apa_table()`

- was designed with table examples from the APA manual in mind
- is much more powerful in PDF documents

???
Point out what's not possible in Word

`kableExtra` is another powerful alternative

---
layout: false
class: middle, center

# A quick demonstration!

[GitHub folder](https://github.com/crsh/reproducible-research-practices-workshop/tree/main/exercises/3_papaja_table_example/)

---
template: results

---
layout: true
template: footer

# Creating figures

---
`apa_barplot()`, `apa_beeplot()`, `apa_lineplot()` can be used to visualize factorial designs

```r
apa_barplot(
  id = "ID"
  , dv = "Post_QoL"
  , factors = c("Reason", "Surgery", "Gender")
  , data = cosmetic_surgery
  , ylab = "Quality of life post surgery"
  , las = 1
)
```

---

???
Discuss some of the arguments

---
`apa_barplot()`, `apa_beeplot()`, `apa_lineplot()` can be used to visualize factorial designs

```r
# This time with bees
*apa_beeplot(
  id = "ID"
  , dv = "Post_QoL"
  , factors = c("Reason", "Surgery", "Gender")
  , data = cosmetic_surgery
  , ylab = "Quality of life post surgery"
  , las = 1
* , args_legend = list(x = 0.25, y = 30)
* , args_points = list(bg = c("skyblue2", "indianred1"))
* , args_error_bars = list(length = 0.03)
)
```

---

---
All plot functions render variable labels, with some LaTeX math support (see `?latex2exp::TeX`)

```r
*variable_labels(cosmetic_surgery) <- c(
* Post_QoL = "Quality of life post surgery ($\\bar{y}_{post}$)"
*)

apa_beeplot(
  id = "ID"
  , dv = "Post_QoL"
  , factors = c("Reason", "Surgery", "Gender")
  , data = cosmetic_surgery
  , las = 1
  , args_legend = list(x = 0.25, y = 30)
  , args_points = list(bg = c("skyblue2", "indianred1"))
  , args_error_bars = list(length = 0.03)
)
```

---

---
For `ggplot2` users, `papaja` provides `theme_apa()`

```r
ggplot(
    cosmetic_surgery
    , aes(x = Base_QoL, y = Post_QoL, color = Reason)
  ) +
  geom_point() +
  geom_smooth(method = "lm") +
  labs(
    x = "Baseline quality of life"
    , y = "Quality of life post surgery"
  ) +
  scale_color_brewer(palette = "Set1") +
* theme_apa(box = TRUE) +
  theme(legend.position = c(0.2, 0.8))
```

---

---
layout: true
template: footer

# Figure and table captions

---

Add a figure caption with the chunk option `fig.cap`

- Caption is reused for every figure in a chunk
  - Only one figure per chunk
  - Combine plots into multi-panel figures (e.g., `layout()`, `cowplot::plot_grid()`, or the **patchwork** package)

---

It's recommended to use "text-references"

<code class = "markdown hljs remark-code" style = "background: #F2F2F2;">(ref:volcano) This is a caption written as text reference. 
&#96;&#96;&#96;{r fig.cap = "(ref:volcano)"}<img src="data:image/png;base64,#img/chunk_buttons.png" style = "float:right;" /> 
image(volcano) 
&#96;&#96;&#96; 
&#96;&#96;&#96;{r} 
apa_table(volcano, caption = "(ref:volcano)") 
&#96;&#96;&#96;</code>

???
- Allow for LaTeX syntax and inline R code chunks
- Enable citations in captions and spell checking
- Text-references can be utilized anywhere

---
layout: true
template: footer

---

# Cross-referencing

To cross-reference figures and tables use `\@ref(fig:chunk-label)` or `\@ref(tab:chunk-label)`

- Chunk labels must not contain `_`
- Precede by non-breaking spaces, e.g. `Figure\ \@ref(fig:chunk-label)`

---

# If you are stuck

1. Try our [work-in-progress manual](http://frederikaust.com/papaja_man/)
2. Ask on StackOverflow using the [`papaja`-tag](https://stackoverflow.com/questions/tagged/papaja)
3. Open a [GitHub issue](https://github.com/crsh/papaja/issues)

---
layout: false
class: middle, center

# Example manuscript

[GitHub folder](https://github.com/crsh/reproducible-research-practices-workshop/tree/main/exercises/3_papaja_example_manuscript)

---
layout: true
template: footer

# Serial response time task

---

???
If you like, use your own data.

---

???
By comparing reaction times for regular transitions with random transitions,
is is possible to distinguish sequence-specific learning from general practice effects

increasing RT differences between regular and irregular transitions is a measure of sequence-specific learning

---
layout: true
template: footer

---
# Process Dissociation

Distinguish implicit and explicit learning

- Implicit: automatic, not controllable
- Explicit: controllable, may be used intentionally

.pull-left-40[
**Inclusion** 
"Generate a sequence that is as *similar* as possible"
]

.pull-right-40[
**Exclusion** 
"Generate a sequence that is as *dissimilar* as possible"
]

???

Implicit and explicit sequence knowledge are dissociated by their controllability

It is assumed that implicit knowledge is automatic and not controllable,
while explicit knowledge is controllable and may be used intentionally.

Participants work on two versions of a generation task: inclusion and exclusion

---
# The present study

Do variants of the PD task differ with respect to "baseline" performance?

- Generation task (**free** vs. **cued** generation tasks)
- Types of "random" material (**permuted** vs. **random** material)
- Performance without prior task exposure (**no-learning** group)

.grey[(Stahl, Barth, & Haider, 2015)]

---
# The present study

The following files are provided:

- The paper `manuscript.pdf` and `manuscript.docx`
- Bibliography file `references.bib`
- Data in the folder `data`
- Analysis script `analyses.R`

.center[https://tinyurl.com/rrpp-papaja]

---
layout: false
class: middle, center

# Exercise time

.center[[Exercise](http://frederikaust.com/reproducible-research-practices-workshop/exercises/3_papaja_question.html)]

.center[[Solutions](http://frederikaust.com/reproducible-research-practices-workshop/exercises/3_papaja_solution.html)]