example.qmd

---
title: "Using Quarto to Generate Documents in APA Style (7th Edition)"
# If blank, the running header is the title in upper case.
shorttitle: "Template for the apaquarto Extension"
# Set names and affiliations.
# It is nice to specify everyone's orcid, if possible.
# There can be only one corresponding author, but declaring one is optional.
author:
  - name: Ana Fulano
    corresponding: true
    orcid: 0000-0000-0000-0001
    email: sm@example.org
    url: https://example.org/
    # Roles are optional. 
    # Select from the CRediT: Contributor Roles Taxonomy https://credit.niso.org/
    # conceptualization, data curation, formal Analysis, funding acquisition, investigation, 
    # methodology, project administration, resources, software, supervision, validation, 
    # visualization, writing, editing
    roles:
      - conceptualization
      - writing
    affiliations:
      - id: id1
        name: "Ana and Blanca's University"
        group: Clinical Psychology Program
        department: Department of Psychology
        address: 1234 Capital St.
        city: Albany
        region: NY
        country: USA
        postal-code: 12084-1234
  - name: Blanca Zutano
    orcid: 0000-0000-0000-0002
    roles:
      - project administration
      - formal analysis
    affiliations: 
      - ref: id1
  - name: Carina Mengano
    orcid: 0000-0000-0000-0003
    deceased: true
    roles:
      - formal analysis
      - writing
    affiliations:
      - name: "Carina's Primary Affiliation"
      - name: "Carina's Secondary Affiliation"
    # Because Dolorita is unaffiliated, specify her city instead
  - name: 
      - given: Dolorita C.
        family: Perengano
    orcid: 0000-0000-0000-0004
    roles:
      - writing
      - methodology
      - formal analysis
    # List city and region/state for unaffiliated authors
    affiliations:
      - city: Buffalo
        region: NY
author-note:
  status-changes: 
    # Example: [Author name] is now at [affiliation].
    affiliation-change: Carina Mengano is now at Generic University.
    # Example: [Author name] is deceased.
    deceased: ~
  # Disclosures condensed to one paragraph, but you can start a field with two line breaks to break them up: \n\nNew Paragraph
  disclosures:
    # Example: This study was registered at X (Identifier Y).
    study-registration: ~
    # Acknowledge and cite data/materials to be shared.
    data-sharing: ~
    # Example: This article is based on data published in [Reference].
    # Example: This article is based on the dissertation completed by [citation].  
    related-report: ~
    # Example: [Author name] has been a paid consultant for Corporation X, which funded this study.
    conflict-of-interest: The authors have no conflicts of interest to disclose.
    # Example: This study was supported by Grant [Grant Number] from [Funding Source].
    financial-support: ~
    # Example: The authors are grateful to [Person] for [Reason].
    gratitude: ~
    # Example. Because the authors are equal contributors, order of authorship was determined by a fair coin toss.
    authorship-agreements: ~
abstract: "This document is a template demonstrating the apaquarto format."
# Put as many keywords at you like, separated by commmas (e.g., [reliability, validity, generalizability])
keywords: [keyword1, keyword2, keyword3]
# If true, tables and figures are mingled with the text instead of listed at the end of the document.
floatsintext: true
# Numbered lines (.pdf and .docx only)
numbered-lines: false
# File with references
bibliography: bibliography.bib
# Suppress title page
suppress-title-page: false
# Link citations to references
link-citations: true
# Masks references that appear in the masked-citations list
mask: false
masked-citations:
  - schneider2012cattell
  - schneider2015intelligence
# If true, adds today's date below author affiliations. If text, can be any value.
# This is not standard APA format, but it is convenient.
# Works with docx, html, and typst. 
draft-date: false
# Language options. See https://quarto.org/docs/authoring/language.html
lang: en
language:
  citation-last-author-separator: "and"
  citation-masked-author: "Masked Citation"
  citation-masked-date: "n.d."
  citation-masked-title: "Masked Title"
  email: "Email"
  title-block-author-note: "Author Note"
  title-block-correspondence-note: "Correspondence concerning this article should be addressed to"
  title-block-role-introduction: "Author roles were classified using the Contributor Role Taxonomy (CRediT; https://credit.niso.org/) as follows:"
  references-meta-analysis: "References marked with an asterisk indicate studies included in the meta-analysis."
format:
  apaquarto-docx: default
  apaquarto-html: default
  apaquarto-typst: 
    keep-typ: true
  apaquarto-pdf:
    # Can be jou (journal), man (manuscript), stu (student), or doc (document)
    documentmode: man
    keep-tex: true
---

```{r}
#| label: setup
#| include: false
library(conflicted)
library(tidyverse)
library(flextable)
library(ftExtra)
library(knitr)
conflicts_prefer(dplyr::filter, .quiet = TRUE)
conflicts_prefer(flextable::separate_header, .quiet = TRUE)
```

This is my introductory paragraph. The title will be placed above it automatically. *Do not start with an introductory heading* (e.g., "Introduction"). The title acts as your Level 1 heading for the introduction.

Details about writing headings with markdown in APA style are [here](https://wjschne.github.io/apaquarto/writing.html#headings-in-apa-style).

## Displaying Figures

A reference label for a figure must have the prefix `fig-`, and in a code chunk, the caption must be set with `fig-cap`. Captions are in [title case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case).

```{r}
#| label: fig-myplot
#| fig-cap: The Figure Caption
#| apa-note: This is the note below the figure.
#| fig-height: 2
#| fig-width: 3
ggplot(data.frame(x = c(0, 35)), aes(x)) +
  stat_function(fun = dchisq, 
                args = list(df = 10),
                geom = "area",
                n = 1000,
                color = NA,
                fill = "#41448780") +
  theme_void(base_size = 18)
```

To refer to any figure or table, use the `@` symbol followed by the reference label (e.g., @fig-myplot).

## Imported Graphics

One way to import an existing graphic as a figure is to use `knitr::include_graphics` in a code chunk. For example, @fig-import1 is an imported image. Note that in apaquarto-pdf documents, we can specify that that a figure or table should span both columns when in journal mode by setting the `apa-twocolumn` chunk option to `true`. For other formats, this distinction does not matter.

```{r}
#| label: fig-import1
#| fig-cap: An Imported Graphic
#| apa-note: A note below the figure
#| fig-width: 3
#| out-width: 48%
knitr::include_graphics("sampleimage.png")
```

Figure graphics can be imported directly with Markdown, as with @fig-import2.

![Another Way to Import Graphics](sampleimage.png){#fig-import2 apa-note="A note below the figure" width="49%"}

Which style of creating figures you choose depends on preference and need.

## Displaying Tables

We can make a table the same way as a figure. Generating a table that conforms to APA format in all document formats can be tricky. When the table is simple, the `kable` function from knitr works well. Feel free to experiment with different methods, but I have found that David Gohel's [flextable](https://davidgohel.github.io/flextable/) to be the best option when I need something more complex.

```{r}
#| label: tbl-mytable
#| tbl-cap: The Table Caption
#| apa-note: The note below the table.
tibble(Numbers = seq(1,4), Letters = LETTERS[seq(Numbers)]) %>%
  knitr::kable()

```

To refer to this table in text, use the `@` symbol followed by the reference label like so: As seen in @tbl-mytable, the first few numbers and letters of the alphabet are displayed.

In @tbl-mymarkdowntable, there is an example of a plain markdown table with a note below it.

::: {#tbl-mymarkdowntable apa-note="This is a note below the markdown table."}
| Default | Left | Right | Center |
|---------|:-----|------:|:------:|
| 12      | 12   |    12 |   12   |
| 123     | 123  |   123 |  123   |
| 1       | 1    |     1 |   1    |

Table Caption of a Markdown Table
:::

What if you want the tables and figures to be at the end of the document? In the .pdf format, you can set the `floatsintext` option to false. For .html and .docx documents, there is not yet an automatic way to put tables and figures at the end. You can, of course, just put them all at the end, in order. The reference labels will work no matter where they are in the text.

## Tables and Figures Spanning Two Columns in Journal Mode

When creating tables and figures in journal mode, care must be taken not to make figures and tables wider than the columns, otherwise $\LaTeX$ sometimes makes them disappear.

As demonstrated in @fig-twocolumn, you can make figures tables span the two columns by setting the `apa-twocolumn` chunk option to `true`.

```{r}
#| label: fig-twocolumn
#| fig-cap: A Figure Spanning Two Columns When in Journal Mode
#| apa-note: Figures in two-column mode are only different for jou mode in .pdf documents
#| apa-twocolumn: true
#| fig-height: 3
#| fig-width: 6.2
#| fig-align: center
ggplot(data.frame(x = c(-4, 4)), aes(x)) +
  stat_function(fun = dnorm, 
                geom = "area",
                n = 1000,
                color = NA,
                fill = "#41448780") +
  theme_void()
```

## Math and Equations

Inline math uses $\LaTeX$ syntax with single dollar signs. For example, the reliability coefficient of my measure is $r_{XX}=.95$.

If you want to display and refer to a specific formula, enclose the formula in two dollar signs. After the second pair of dollar signs, place the label in curly braces. The label should have an `#eq-` prefix. To refer to the formula, use the same label but with the `@` symbol. For example, @eq-euler is Euler's Identity, which is much admired for its elegance.

## Citations

See [here](https://quarto.org/docs/authoring/footnotes-and-citations.html) for instructions on setting up citations and references.

A parenthetical citation requires square brackets [@CameronTrivedi2013]. This reference was in my bibliography file. An in-text citation is done like so:

@CameronTrivedi2013 make some important points ...

See [here](https://wjschne.github.io/apaquarto/writing.html#references) for explanations, examples, and citation features exclusive to apaquarto. For example, apaquarto can automatically handle possessive citations:

@schneider2012cattell ['s] position was ...

## Masking Author Identity for Peer Review

Setting `mask` to `true` will remove author names, affiliations, and correspondence from the title page. Any references listed in the `masked-citations` field will be masked as well. See [here](https://wjschne.github.io/apaquarto/writing.html#masked-citations-for-anonymous-peer-review) for more information.

$$
e^{i\pi}+1=0
$$ {#eq-euler}

## Block Quotes

Sometimes you want to give a longer quote that needs to go in its own paragraph. Block quotes are on their own line starting with the \> character. For example, @austenMansfieldPark1990 ['s] *Mansfield Park* has some memorable insights about the mind:

> If any one faculty of our nature may be called more wonderful than the rest, I do think it is memory. There seems something more speakingly incomprehensible in the powers, the failures, the inequalities of memory, than in any other of our intelligences. The memory is sometimes so retentive, so serviceable, so obedient; at others, so bewildered and so weak; and at others again, so tyrannic, so beyond control! We are, to be sure, a miracle every way; but our powers of recollecting and of forgetting do seem peculiarly past finding out. (p. 163)

If your quote has multiple paragraphs, like this passage from @brownHowKilledPluto2012, separate them with a lone `>` character between the lines:

> In the entire field of astronomy, there is no word other than *planet* that has a precise, lawyerly definition, in which certain criteria are specifically enumerated. Why does *planet* have such a definition but *star*, *galaxy*, and *giant molecular cloud* do not? Because in astronomy, as in most sciences, scientists work by concepts rather than by definitions. The concept of a star is clear; a star is a collection of gas with fusion reactions in the interior giving off energy. A galaxy is a large, bound collection of stars. A giant molecular cloud is a giant cloud of molecules. The concept of a planet---in the eight-planet solar system---is equally simple to state. A planet is a one of a small number of bodies that dominate a planetary system. That is a concept, not a definition. How would you write that down in a precise definition?
>
> I wouldn’t. Once you write down a definition with lawyerly precision, you get the lawyers involved in deciding whether or not your objects are planets. Astronomers work in concepts. We rarely call in the attorneys for adjudication. (p. 242)

## Hypotheses, Aims, and Objectives

The last paragraph of the introduction usually states the specific hypotheses of the study, often in a way that links them to the research design.

# Method

General remarks on method. This paragraph is optional.

Not all papers require each of these sections. Edit them as needed. Consult the [Journal Article Reporting Standards](https://apastyle.apa.org/jars) for what is needed for your type of article.

## Participants

Who are they? How were they recruited? Report criteria for participant inclusion and exclusion. Perhaps some basic demographic stats are in order. A table is a great way to avoid repetition in statistical reporting.

## Measures

This section can also be titled **Materials** or **Apparatus**. Whatever tools, equipment, or measurement devices used in the study should be described.

### Measure A

Describe Measure A.

### Measure B

Describe Measure B.

#### Subscale B1

A paragraph after a 4th-level header will appear on the same line as the header.

#### Subscale B2

A paragraph after a 4th-level header will appear on the same line as the header.

##### Subscale B2a

A paragraph after a 5th-level header will appear on the same line as the header.

##### Subscale B2b

A paragraph after a 5th-level header will appear on the same line as the header.

## Procedure

What did participants do? How are the data going to be analyzed?

# Results

## Descriptive Statistics

Describe the basic characteristics of the primary variables. My ideal is to describe the variables well enough that someone conducting a meta-analysis can include the study without needing to ask for additional information.

<!-- Add Additional Sections as Needed -->

# Discussion

Describe results in non-statistical terms. <!-- Add sections as needed. -->

## Limitations and Future Directions

Every study has limitations. Based on this study, some additional steps might include...

## Conclusion

Describe the main point of the paper.

# References

<!-- References will auto-populate in the refs div below -->

::: {#refs}
:::

# Appendix

# The Title for Appendix

If there are multiple appendices, label them with level 1 headings as Appendix A, Appendix B, and so forth.

Tables and figures in the first appendix automatically get the prefix "A", and the numbering starts again at 1. See @fig-appendfig.

If there were a second appendix, tables and figures would get the prefix "B", and the numbering starts again at 1. Make as many appendices as needed.

![Appendix Figure](sampleimage.png){#fig-appendfig apa-note="A note below the figure"}