apa7_manuscript.qmd

---
title: "Exercise: Formatting Quarto documents in APA 7 style"
lang: en
---

::: {.callout-note}
This exercise is only relevant, if you are a psychologist or want to publish in journals that require manuscripts to be formatted in the [APA 7 style](https://apastyle.apa.org/) (Publication Manual of the American Psychological Association: 7th Edition). If you are from another discipline, checkout whether Quarto already provides [article templates](https://quarto.org/docs/journals/formats.html) for your most beloved journals.
:::

## Description

Pick a preprint of your own and implement it using Quarto in the [APA 7](https://apastyle.apa.org/) manuscript style. You also can view an [example document](demo_manuscript.pdf) that incorporates all features from this exercise.

## Getting started

The official Quarto extension [`apaquarto`](https://github.com/wjschne/apaquarto) can be used to format documents according to the [APA 7](https://apastyle.apa.org/) guidelines^[For a list of Quarto extensions for specific journal formats, click [here](https://quarto.org/docs/extensions/listing-journals.html).]. After installing the extension into the current project, we can set the `format` to `apaquarto-pdf` or `apaquarto-docx`. Here are the detailed steps that are necessary to create a manuscript in APA 7 style (**Note:** skip step 1 if you want to use an already existing Quarto document).

0. Prerequisites
   - Install required packages
     - Click on _Console_
     - Enter\
       ```r
       install.packages(c("rmarkdown", "conflicted", "tidyverse", "flextable", "ftExtra"))
       ```
   - Install TinyTeX
     - Click on _Terminal_
     - Enter `quarto install tinytex`
1. **Optional:** Create a new Quarto Document
   - Click on _File_ > _New File_ > _Quarto Document_
   - Fill _Title_ and _Author_
   - Choose _PDF_
   - Click _Create_
2. Add APA 7 Quarto extension
   - Go to _Terminal_
   - Enter `quarto add wjschne/apaquarto`
   - Confirm installation by entering <kbd>Y</kbd> twice, then avoid opening the documentation by entering <kbd>n</kbd>
   - If you want to update the extension at a later point, enter `quarto update wjschne/apaquarto`
3. Declare the language of the document by setting e.g. `lang: en` in the YAML header (see the [Quarto documentation on document language](https://quarto.org/docs/authoring/language.html) for more information)
4. Change `format` as follows:\
   ```yaml
   format:
     apaquarto-pdf:
       documentmode: man
       a4paper: true
       pdf-engine: lualatex
       keep-tex: false
   ```
5. Click on the disk symbol to save (maybe call the file `manuscript.qmd`)
6. Click on _Render_\
   (alternatively, go to the _Terminal_ and enter `quarto render manuscript.qmd`)

We can now provide additional information in the YAML header as detailed below.

## Short title

A running header in upper case can be added like this:

```yaml
shorttitle: "My short title"
```

## Authors

Say we have two authors called _Ana Fulana_ and _Blanca Zutana_, each with their own ORCID, email address and [<abbr title="Contributor Roles Taxonomy">CRediT</abbr> roles](https://credit.niso.org/). They have a common affiliation and Ana acts as corresponding author. In the YAML header this looks as follows:

```yaml
author:
  - name: Ana Fulana
    corresponding: true
    orcid: "0000-0000-0000-0000"
    email: "af@example.org"
    roles:
      - conceptualization
      - writing
    affiliations:
      - id: "lmu"
        name: "Ludwig-Maximilians-Universität München, Munich, Germany"
        department: "Department of Psychology"
        ror: "https://ror.org/05591te55"
        url: "https://www.lmu.de/"
  - name: Blanca Zutana
    roles:
      - project administration
    affiliations: 
      - ref: lmu
```

Available CRediT roles are:

- [`conceptualization`](https://credit.niso.org/contributor-roles/conceptualization/)
- [`data curation`](https://credit.niso.org/contributor-roles/data-curation/)
- [`formal analysis`](https://credit.niso.org/contributor-roles/formal-analysis/)
- [`funding acquisition`](https://credit.niso.org/contributor-roles/funding-acquisition/)
- [`investigation`](https://credit.niso.org/contributor-roles/investigation/)
- [`methodology`](https://credit.niso.org/contributor-roles/methodology/)
- [`project administration`](https://credit.niso.org/contributor-roles/project-administration/)
- [`resources`](https://credit.niso.org/contributor-roles/resources/)
- [`software`](https://credit.niso.org/contributor-roles/software/)
- [`supervision`](https://credit.niso.org/contributor-roles/supervision/)
- [`validation`](https://credit.niso.org/contributor-roles/validation/)
- [`visualization`](https://credit.niso.org/contributor-roles/visualization/)
- [`writing`](https://credit.niso.org/contributor-roles/writing-original-draft/)
- [`editing`](https://credit.niso.org/contributor-roles/writing-review-editing/)

See the [Quarto documentation on author roles](https://quarto.org/docs/authoring/front-matter.html#roles) for more information.

## Abstract

You can add an abstract using the `abstract` YAML key:

```yaml
abstract: "Lorem ipsum dolor sit amet, consectetur adipisici elit, sed eiusmod tempor incidunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquid ex ea commodi consequat. Quis aute iure reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint obcaecat cupiditat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum."
```

## Keywords

One can add multiple keywords by using a list:

```yaml
keywords:
  - meta science
  - replication
  - multiverse analysis
```

## Author Note

The author note can be populated with various disclosures as follows:

```yaml
author-note:
  disclosures:
    study-registration: "This study was preregistered at OSF at ...."
    data-sharing: "Code and data of this study are available at ..."
    related-report: "This article is based on data published in ..."
    conflict-of-interest: "We declare we have no competing interests."
    financial-support: "This research was funded by the German Research Foundation (DFG SCHO ..., Blanca Zutana)."
    gratitude: "We would like to thank Carina Mengana and Dolorita Perengana for their very helpful comments and discussions on this project."
    authorship-agreements: "Because the authors are equal contributors, order of authorship was determined by a fair coin toss."
```

## Figures

For including images, it is recommended to define a label starting with `fig-` to make the figure cross-referencable. One can also add a note and set the image width and height. In APA 7 style, captions are to be written in [title case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case).

<!-- image from <https://picsum.photos/id/360/1000/1000.jpg> -->

```md
![This Image Depicts a Flower.](flower.jpg){#fig-flower apa-note="This is the note below the figure." height="5cm" width="5cm"}
```

For figures that are computed dynamically, the following might serve as an example:

``````qmd
```{{r}}
#| label: fig-cars
#| fig-cap: Plot of the cars Dataset.
#| apa-note: Another note.
#| out-height: 5cm
#| out-width: 5cm
#| fig-height: 3
#| fig-width: 3

plot(cars)
```
``````

When using the `apaquarto` extension, by default, figures appear at the end of the document, unless one sets `floatsintext: true` in the YAML header. Therefore it might make sense to add a final heading `Appendix` below which the figures will appear. Figures can be cross-referenced by using the `@` symbol followed by the reference label: `For an image of a flower, see @fig-flower.`

For more information on how to work with figures, head over to the [Quarto documentation on figures](https://quarto.org/docs/authoring/figures.html).

## Tables

Tables need to have labels prefixed with `tbl-`:

```qmd
| Letters | Numbers |
|:-------:|:-------:|
| A       | 1       |
| B       | 2       |
| C       | 3       |

: My Caption {#tbl-mytable apa-note="Note below table" data-quarto-disable-processing="true"}
```

As an alternative to using markdown, tables can be created dynamically, e.g. using the R packages `tibble` and `flextable`:

``````qmd
```{{r}}
#| label: tbl-ingredients
#| tbl-cap: Substances and Their Key Ingredients.
#| apa-note: The note below the table.

tibble::tribble(
  ~"Substance", ~"Key Ingredient",
  "a",   "None",
  "b",   "Sugar",
  "c",   "Salt"
  ) |>
  flextable::flextable() |>
  flextable::theme_apa()
```
``````

When using the `apaquarto` extension, by default, tables appear at the end of the document, unless one sets `floatsintext: true` in the YAML header. One can refer to tables by using the `@` symbol followed by the reference label: `Key ingredients are given in @tbl-ingredients.`

For more information on how to create tables, head over to the [Quarto documentation on tables](https://quarto.org/docs/authoring/tables.html).

## Footnotes

The following serves as an example for how to add footnotes:

```md
Here is an inline note.^[This text appears as a footnote.]
```

## References

Put your bibliography in a BibTeX file (extension `.bib`) and reference it in your YAML metadata:

```yaml
bibliography: literature.bib
```

Add a level one heading and a [Div](https://quarto.org/docs/authoring/markdown-basics.html#divs-and-spans) with the id `refs` at the end of the document (but before the appendix, if you have one):

```md
# References

::: {#refs}
:::
```

You can now cite from your bibliography using the syntax `[@id]`.

For more information on how to cite literature, head over to the [Quarto documentation on citations](https://quarto.org/docs/authoring/footnotes-and-citations.html).

## Numbered lines

If you would like to have your lines numbered, set `numbered-lines: true` in the YAML header.

## Generate `.tex` file

Sometimes you might need the intermediate `.tex` file in addition to the final `.pdf` file. In order to keep that, set `keep-tex: true` in the YAML header.

## Use publication style

In the YAML header shared above, the style of the document is a manuscript as required when submitting to an APA journal. To switch to publication style which resembles the format of an article printed in an APA journal, change the document mode by setting `documentmode: jou`

## Generate `.docx` file

If you prefer to create your manuscript as DOCX rather than PDF, you can set the format as follows:

```yml
format:
  apaquarto-docx: default
```

## Final notes

You can download a manuscript with all the features presented on this page via the following button:

{{< downloadthis demo_manuscript.zip dname="demo_manuscript" label="Download source files as ZIP">}}

If you are interested in all the options provided by the `apaquarto` extension (e.g., [masked citations for anonymous peer review](https://wjschne.github.io/apaquarto/writing.html#masked-citations-for-anonymous-peer-review)), have a look at the [apaquarto documentation](https://wjschne.github.io/apaquarto/options.html). Also, we recommend reading the guide [APA Style via Markdown](https://wjschne.github.io/apaquarto/writing.html).