Friends don’t let friends copy-paste

### Friends don't let friends copy-paste

![:pull right, 35%](

)

# Introduction to papaja

#### Frederik Aust & Marius Barth

---
exclude: true

---
layout: true
name: footer

<div class="my-footer">
  <div style="float: left;"><span>Frederik Aust & Marius Barth</span></div>
  <div style="text-align: right;"><span>Friends don't let friends copy-paste</span></div>
  <div style="float: center;"><span>21.04.2023</span></div>
</div>

---

const zoomDefault = mediumZoom('#zoom-default')
const zoomMargin = mediumZoom('#zoom-margin', { margin: 45 })
</script>

---
layout: true
template: footer
name: papaja

# papaja

---

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

1. Designed for APA-style manuscripts
2. Templates for PDF and DOCX documents
3. Functions to report results, e.g.
    - `apa_print()`
    - `apa_table()`
    - `apa_factorial_plot()`, `theme_apa()`

---
### Getting started

Install papaja from GitHub

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

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

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

---
### Document templates

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

---
layout: false
class: inverse, middle, center

# YAML front matter

---
layout: true
template: papaja

---
name: apa6

### APA manuscript template

---
<small>

| YAML field | Metadata |
|-----------|--------------------------------------|
| `author`  | Unnamed list of author information (e.g., `name`, `affiliation`; start each new author with `-`) |
| `affiliation` | Unnamed list of institutional information (`id`, `institution`) |
| `authornote` | Author note; automatically contains corresponding author line |
| `keywords` | Keywords |
| `wordcount` | Word count |
| `note` | Text to add to the title page above author note<br />(e.g. "Preprint submitted for publication") |

</small>

---

### Rendering options

<small>

| YAML field | Effect |
|-----------|--------------------------------------|
| `bibliography` | List of bibliography files |
| `mask` | Omit identifying information from title page |
| `numbersections` | Number sections headings |
| `disambiguate_authors` | Disambiguate citations by adding authors' given names |
| `annotate_references` | Add prefix to bibliography entries, e.g. `*` for meta-analytic references |

</small>

---
<small>

| YAML field | Effect |
|-----------|--------------------------------------|
| `floatsintext`<sup>\*</sup> | Place figures and tables in the text, not at the end |
| `linenumbers`<sup>\*</sup> | Add line numbers in left margin |
| `draft`<sup>\*</sup> | Add "DRAFT" watermark across all pages |
| `figurelist`<sup>\*</sup><br />`tablelist`<sup>\*</sup><br />`footnotelist`<sup>\*</sup> | Create lists of figure and table captions, or footnotes |
| `classoption`<sup>\*</sup> | control the style of the document<br />(e.g., `man` or `doc`, see [`apa6`](https://mirror.hmc.edu/ctan/macros/latex/contrib/apa6/apa6.pdf) LaTeX class options) |

<sup>\*</sup> Only available for PDF documents

</small>

---
template: apa6

To change the output format choose either

- `apa6_pdf()` or
- `apa6_docx()`
--

- More limited functionality
    - May require a bit of manual tweaking (see [manual](http://frederikaust.com/papaja_man/limitations.html#microsoft-word-documents))

---

`papaja` extends the `bookdown` formats

- `pdf_document2()` and
- `word_document2()`

Inherits useful features (which we will get to)

<small>

- Text-references
- Cross-referencing
- Special appendix syntax

</small>

---
layout: false
class: inverse, middle, center

# Reporting statistical analyses

---
layout: true
template: papaja
name: results

### Report statistical analyses

---
Inline code chunks round numerical results

<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).

---
Typeset numerical values "manually" 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_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]"
```

---

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

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

```
## 
## 	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

```r
apa_print(cor_res)
```

```
## $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$"
## 
## $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$ 
## attr(,"class")
## [1] "apa_results" "list"
```

---
`apa_print()` returns a standardized `list` object

<small>

| Sublist | Content |
|:--------|:--------|
| `estimate` | (List of Un)standardized effect size estimate |
| `statistic` | (List of) inferential test statistic |
| `full_result` | (List of) Effect size and test statistic |
| `table` | All results in a `data.frame` |

</small>

---

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

lm_res_apa <- apa_print(lm_res, observed = TRUE)
*lm_res_apa$estimate$Intercept
```

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

> Check out that intercept, `$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$"
```

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

---

Objects of different S3/S4 classes are treated differently

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

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

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

---
layout: false
template: papaja

<small>

<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.aovlist </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.glht </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.glm </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.lm </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.manova </td>
  </tr>
  <tr>
   <td style="text-align:left;"> aovlist </td>
   <td style="text-align:left;"> list </td>
   <td style="text-align:left;"> summary_emm </td>
   <td style="text-align:left;"> summary.ref.grid </td>
  </tr>
  <tr>
   <td style="text-align:left;"> BFBayesFactor </td>
   <td style="text-align:left;"> lm </td>
   <td style="text-align:left;"> summary.Anova.mlm </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.aov </td>
   <td style="text-align:left;">  </td>
  </tr>
</tbody>
</table>

</small>

---
layout: false
class: inverse, middle, center

# Tables and figures

---
layout: true
template: papaja
name: tabs-figs

### Tables and figures

---
Tables produced 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$
```

---
exclude: true

Tables produced 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$"
```

---

Let's simplify the redundant degrees-of-freedom column

```r
lm_res_apa$table <- transmute_df_into_label(lm_res_apa$table)
```

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

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

```r
cap <- "Cosmetic surgery"

apa_table(
  lm_res_apa$table
  , caption = cap
)
```

]

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Table 1. *Cosmetic surgery*

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

</small>

]

---

`apa_table()`

- tries to enable table designs from the APA manual
- can merge `data.frame` of the same structure
- is much more powerful in PDF documents<br />(see `apa_table_example.Rmd`)

---
layout: false
template: papaja

---
class: middle, center
template: footer

# A quick demonstration!

---
layout: true
template: tabs-figs

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

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

---

---

`apa_factorial_plot()` can combine visualizations

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

---

---

Variable labels are supported (incl. some LaTeX math, see [`latex2exp::TeX()`](https://www.rdocumentation.org/packages/latex2exp/topics/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
* # , 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)
)
```

---

---
`papaja` also provides a `ggplot2` theme

```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))
```

---

---

Add captions with the chunk option `fig.cap`

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

---
Use so-called "text-references" for captions

````md
*(ref:volcano) This is a caption written as text reference.

```{r}
*#| fig.cap: "(ref:volcano)"

image(volcano)
```
````

---
Use so-called "text-references" for captions

- LaTeX syntax
- Inline R code chunks
- Citations
- Spell checking

---
Cross-reference with<br />`\@ref(fig:chunk-label)` or<br />`\@ref(tab:chunk-label)`

````md
(ref:volcano) This is a caption written as text reference.

```{r}
#| label: volcano-plot
#| fig.cap: "(ref:volcano)"

image(volcano)
```

*It's so pretty, Figure\ \@ref(fig:volcano-plot).
````

---

Figures are saved as PDF and 300 dpi PNG

<small>

| Chunk option | Meaning |
|:-------------|:--------|
| `fig.path` | Figure path |
| `dev` | File format, (e.g., `tiff`, `svg`) |
| `dev.args` | File format settings (e.g. `compression = 'lzw'`) |
| `dpi` | Dots per inch resolution |

</small>

---
layout: false
class: inverse, middle, center

# Citing R packages

---
layout: true
template: papaja

### Citing R packages

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

`r_refs()` creates a bibliography for all currently loaded packages

- Call after loading all packages

---
`cite_r()` creates text to cite R and R packages

````md
```{r}
my_citations <- cite_r(file = "r-references.bib")
```

We used `r my_citations` for all analyses.
````

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

---

Cite selected packages and move citations to a footnote

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

```
## $r
## [1] "R [Version 4.2.3\\; @R-base][^papaja_pkg_citations]"
## 
## $pkgs
## [1] "\n\n[^papaja_pkg_citations]: We, furthermore, used the R-packages *afex* [Version 1.2.1\\; @R-afex], *emmeans* [Version 1.8.4.1\\; @R-emmeans], and *papaja* [Version 0.1.1.9001\\; @R-papaja].\n\n"
```

---

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

*We used `r my_citations$r` for all analyses.
*
*`r my_citations$pkgs`
````

---

# Appendices

---

### Appendices

---

Use special heading to start the appendix section

```md
# References

::: {#refs}
:::

\clearpage

*# (APPENDIX) Appendix {-}

# The Appendix

This is the start of an appendix.
```

---

Multiple appendices are separated by level 1-headings

```md
# (APPENDIX) Appendix {-}

# Additional analyses

...

# Stimulus material

...
```

---

Appendices can also be placed in separate file(s)

````md
# (APPENDIX) Appendix {-}

```{r}
*#| child: "appendix-a.Rmd"
```

```{r}
*#| child: "appendix-b.Rmd"
```
````

---

# A quick demonstration!

---
layout: true
template: papaja

### Troubleshooting

---

---

- YAML front matter is read
    - `Error in yaml::yaml.load(enc2utf8(string), ...) :`
- R code is executed
    - `Error: Object 'experiment_data' not found.`
    - Gives first line of erroneous R code chunk

---
- `bookdown` adds cross- and text-references
    - No error messages
    - look for `(#fig:chunk-name)` or `(ref:label)` in rendered document
    - Don't use `_` in chunk names!

---
- `pandoc` and `citeproc` convert Markdown
    - `Error: pandoc document conversion failed with error 1`
    - `citeproc: reference XYZ not found`,<br />shows up as **???** in text (see [manual](https://pandoc.org/MANUAL.html#exit-codes))

---
- LaTeX creates a PDF
    - `! Missing $ inserted`

_Google error messages!_

---
layout: false
template: papaja

### "How do I ..."

- Try our [work-in-progress manual](https://crsh.github.io/papaja_man/)
- Ask on StackOverflow using the [`papaja`-tag](https://stackoverflow.com/questions/tagged/papaja)

### "I think I found a bug ..." or<br />"How about this feature ..."

- Open a [GitHub issue](https://github.com/crsh/papaja/issues)

---
template: footer
class: middle, center

# [Let's get some exercise](http://frederikaust.com/papaja-workshop/exercises/3_papaja_question.html)!