example.rmd

---
title             : "How to use `papaja`: An Example Manuscript Including Basic Instructions"
shorttitle        : "How to use papaja"

author: 
  - name          : "Frederik Aust"
    affiliation   : "1"
    corresponding : yes    # Define only one corresponding author
    address       : "Department Psychology, University of Cologne, Herbert-Lewin-Str. 2, 50931 Köln, Germany"
    email         : "frederik.aust@uni-koeln.de"
    role:   # Contributorship roles (e.g., CRediT, https://casrai.org/credit/)
      - Conceptualization
      - Project Administration
      - Software
      - Supervision
      - Validation
      - Writing - Original Draft Preparation
      - Writing - Review & Editing

affiliation       :
  - id            : "1"
    institution   : "University of Cologne"

authornote: |
  `papaja` has not yet been submitted to CRAN; a development version is available at https://github.com/crsh/papaja.

abstract: |
  This manuscript demonstrates how to use R Markdown and papaja to
  create an APA conform manuscript. papaja builds on R Markdown, which
  uses pandoc to turn Markdown into PDF or Word documents. The conversion
  to Word documents currently supports only a limited set of features.
  
keywords          : "APA style, knitr, R, R markdown, papaja"
wordcount         : "1,753"

bibliography      : ["references.bib", "r-references.bib"]

floatsintext      : yes
figurelist        : no
tablelist         : no
footnotelist      : no
linenumbers       : yes
linkcolor         : "blue"
mask              : no
draft             : no

classoption       : "man"
output            : papaja::apa6_pdf # Use papaja::apa6_docx for Word documents
---

```{r include = FALSE}
library("dplyr")
library("afex")
library("papaja")

knitr::opts_chunk$set(echo = TRUE)

load("../../tests/testthat/data/mixed_data.rdata")
```

# What is papaja?

Reproducible data analysis is an easy to implement and important aspect of the strive towards reproducibility in science.
For *R* users, R Markdown has been suggested as one possible framework for reproducible analyses.
`papaja` is a R-package in the making including a [R Markdown](https://rmarkdown.rstudio.com/) template that can be used with (or without) [RStudio](https://posit.co/) to produce documents, which conform to the American Psychological Association (APA) manuscript guidelines (6th Edition).
The package uses the \LaTeX document class [apa6](http://www.ctan.org/pkg/apa6) and a .docx-reference file, so you can create PDF documents, or Word documents if you have to.
Moreover, `papaja` supplies R-functions that facilitate reporting results of your analyses in accordance with APA guidelines.

Markdown is a simple formatting syntax that can be used to author HTML, PDF, and MS Word documents (among others).
In the following I will assume you know how to use R Markdown to conduct and comment your analyses.
If this is not the case, I recommend you familiarize yourself with [R Markdown](https://rmarkdown.rstudio.com/) first.
I use [RStudio](https://posit.co/) to create my documents, but the general process works with any text editor.


# How to use papaja

Once you have installed `papaja` and all other [required software](https://github.com/crsh/papaja#requirements), you can select the APA template when creating a new R Markdown file through the RStudio menus, see Figure\ \@ref(fig:menu).
When you click RStudio's *Knit* button (see Figure\ \@ref(fig:knit)), `papaja`, `bookdown`, `rmarkdown,` and `knitr` work together to create an APA conform manuscript that includes both your text and the output of any embedded R code chunks within the manuscript.

(ref:menu-caption) `papaja`'s APA6 template is available through the RStudio menus.

```{r menu, fig.cap = "(ref:menu-caption)", fig.align = "center", echo = FALSE}
knitr::include_graphics("../images/template_selection.png", dpi = 108)
```

(ref:knit-caption) The Knit button in the RStudio.

```{r knit, fig.cap = "(ref:knit-caption)", fig.align = "center", echo = FALSE}
knitr::include_graphics("../images/knitting.png", dpi = 108)
```


## Printing R output

Any output from R is included as you usually would using R Markdown.
By default the R code will not be displayed in the final documents.
If you wish to show off your code you need to set `echo = TRUE` in the chunk options.
For example, to include summary statistics of your data you could use the following code:

```{r}
summary(mixed_data[, -1])
```

But, surely, this is not what you want your submission to look like.


### Print tables

For prettier tables, I suggest you try `apa_table()`, which builds on `knitr`'s `kable()`, and `apa_num()`, which can be used to properly round and report numbers.

(ref:descriptives-caption) Descriptive statistics of correct recall by dosage.

(ref:descriptives-note) This table was created with `apa_table()`.

```{r descriptives}
descriptives <- mixed_data %>%
  group_by(Dosage) %>%
  summarize(
    Mean = mean(Recall)
    , Median = median(Recall)
    , SD = sd(Recall)
    , Min = min(Recall)
    , Max = max(Recall)
  )
descriptives[, -1] <- apa_num(descriptives[, -1])

apa_table(
  descriptives
  , caption = "(ref:descriptives-caption)"
  , note = "(ref:descriptives-note)"
)
```

Of course popular packages like `xtable`[^xtable] or `tables` can also be used to create tables when knitting PDF documents.
These packages, however, cannot be used when you want to create Microsoft Word documents because they rely on \LaTeX for typesetting.
`apa_table()` creates tables that conform to APA guidelines and are correctly rendered in PDF and Word documents.
But don't get too excited; table formatting is somewhat limited for Word documents due to missing functionality in pandoc (e.g., it is not possible to have cells or headers span across multiple columns).

[^xtable]: When you use `xtable()`, table captions are [set to the left page margin](http://tex.stackexchange.com/questions/42209/centering-tables-in-document-class-apa6).

As required by the APA guidelines, tables are deferred to the final pages of the manuscript when creating a PDF.
Again, this is not the case in Word documents due to limited pandoc functionality.
To place tables and figures in your text instead, set the `figsintext` parameter in the YAML header to `yes` or `true`, as I have done in this document.

The bottom line is, Word documents will be less polished than PDF.
The resulting documents should suffice to enable collaboration with Wordy colleagues and prepare a journal submission with limited manual labor.


### Embed plots

As usual in R Markdown, you can embed R-generated plots into your document, see Figure\ \@ref(fig:beeplot).

(ref:beeplot-caption) Bee plot of the example data set. Small points represent individual observations, large points represent means, and error bars represent 95% confidence intervals.

```{r beeplot, fig.cap = "(ref:beeplot-caption)", dev.args = list(bg = 'white')}
apa_beeplot(
  mixed_data
  , id = "Subject"
  , dv = "Recall"
  , factors = c("Task", "Valence", "Dosage")
  , dispersion = conf_int
  , ylim = c(0, 30)
  , las = 1
  , args_points = list(cex = 1.5)
  , args_arrows = list(length = 0.025)
)
```

Again, as required by the APA guidelines, figures are deferred to the final pages of the document unless you set `figsintext` to `yes`.


### Referencing figures and tables

`papaja` builds on the `bookdown` package, which provides limited cross-referencing capabilities within documents.
By default you can insert figure and table numbers into the text using `\@ref(fig:chunk-name)` for figures or `\@ref(tab:chunk-name)` for tables.
Note that for this syntax to work chunk names cannot include `_`.
If you need to embed an external image that is not generated by R use the `knitr::include_graphics()` function.
See the [great book on `bookdown`](https://bookdown.org/yihui/bookdown/cross-references.html) for details.
Cross-referencing is currently not available for equations in `bookdown`.
However, as anywhere in R Markdown documents you can use \LaTeX commands if the functionality is not provided by `rmarkdown`/`bookdown` and you don't need to create Word documents.


### Report statistical analyses

`apa_print()` will help you report the results of your statistical analyses.
The function will format the contents of R objects and produce readily reportable text.

```{r}
recall_anova <- afex::aov_car(
  Recall ~ (Task * Valence * Dosage) + Error(Subject/(Task * Valence)) + Dosage
  , data = mixed_data
  , type = 3
)
recall_anova_results <- apa_print(recall_anova, es = "pes")
recall_anova_results_p <- apa_print(recall_anova, es = "pes", in_paren = TRUE)
```

Now, you can report the results of your analyses like so:

```{r eval = FALSE}
Item valence (`r recall_anova_results_p$full$Valence`) and the task
affected recall performance, `r recall_anova_results$full$Task`; the dosage,
however, had no effect on recall, `r recall_anova_results$full$Dosage`.
There was no significant interaction.
```

> Item valence (`r recall_anova_results_p$full$Valence`) and the task affected recall performance, `r recall_anova_results$full$Task`;
> the dosage, however, had no effect on recall, `r recall_anova_results$full$Dosage`.
> There was no significant interaction.

What's even more fun, you can easily create a complete ANOVA table using by passing `recall_anova_results$table` to `apa_table()`, see Table\ \@ref(tab:anova).

(ref:anova-caption) ANOVA table for the analyis of the example data set.

(ref:anova-note) This is a table created using `apa_print()` and `apa_table()`.

```{r anova}
apa_table(
  recall_anova_results$table
  , align = c("l", "r", "c", "r", "r", "r")
  , caption = "(ref:anova-caption)"
  , note = "(ref:anova-note)"
)
```


## Citations

No manuscript is complete without citation.
In order for citations to work, you need to supply a .bib-file to the `bibliography` parameter in the YAML front matter.
Once this is done, `[e.g., @james_1890; @bem_2011]` produces a regular citation within parentheses [e.g., @bem_2011; @james_1890].
To cite a source in text simply omit the brackets; for example, write `@james_1890` to cite @james_1890.
For other options see the [overview of the R Markdown citation syntax](https://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html).

The citation style is automatically set to APA style.
If you need to use a different citation style, you can set in the YAML front matter by providing the `csl` parameter.
See the [R Markdown documentation](https://rmarkdown.rstudio.com/authoring_bibliographies_and_citations.html) and [Citation Style Language](http://citationstyles.org/) for further details.

If you use RStudio, I have created an [easy-to-use add-in](https://github.com/crsh/citr) that facilitates inserting citations into a document.
The relevant references will, of course, be added to the documents reference section automatically.
Moreover, the addin can directly access you Zotero database.

I think it is important to credit the software we use.
A lot of R packages are developed by academics free of charge.
As citations are the currency of science, it's easy to compensate volunteers for their work by citing the R packages we use.
I suspect that, among other things, this is rarely done because it is tedious work.
That's why papaja makes citing R and its packages easy:

```{r}
r_refs(file = "r-references.bib")
my_citation <- cite_r(file = "r-references.bib")
```

`r_refs()` creates a BibTeX file containing citations for R and all currently loaded packages.
`cite_r()` takes these citations and turns them into readily reportable text.
`my_citation` now contains the following text that you can use in your document: `r my_citation`


## Math

If you need to report formulas, you can use the flexible \LaTeX syntax (it will work in Word documents, too).
Inline math must be enclosed in `$` or `\(` and `\)` and the result will look like this: $d' = z(H) - z(FA)$.
For larger formulas displayed equations are more appropriate; they are enclosed in `$$` or `\[`and `\]`,

$$
d' = \frac{\mu_{old} - \mu_{new}}{\sqrt{0.5(\sigma^2_{old} + \sigma^2_{new})}}.
$$


## Document options

This text is set as manuscript.
If you want a thesis-like document you can change the `class` in the YAML front matter from `man` to `doc`.
You can also preview a polished journal typesetting by changing the `class` to `jou`.
Refer to the `apa6` document class [documentation](ftp://ftp.fu-berlin.de/tex/CTAN/macros/latex/contrib/apa6/apa6.pdf) for further `class` options, such as paper size or draft watermarks.

When creating PDF documents, line numbering can be activated by setting the `linenumbers` argument in the YAML front matter to `yes`.
Moreover, you can create lists of figure or table captions at the end of the document by setting `figurelist` or `tablelist` to `yes`, respectively.
These option have no effect on Word documents.


## Last words

That's all I have; enjoy writing your manuscript.
If you have any trouble or ideas for improvements, open an [issue](https://github.com/crsh/papaja/issues) on GitHub or open a pull request.
If you want to contribute, take a look at the [open issues](https://github.com/crsh/papaja/issues) if you need inspiration.
Other than that, there are many output objects from analysis methods that we would like `apa_print()` to support.
Any new S3/S4-method for this function are always appreciated (e.g., `factanal`, `fa`, `lavaan`, `lmer`, or `glmer`).


# References

<!-- These lines ensure references are set with hanging indents in PDF documents; they are ignored in Word. -->
\setlength{\parindent}{-0.5in}
\setlength{\leftskip}{0.5in}