example.qmd

---
title: "Write APA Style Documents Using Quarto"
# 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
blank-lines-above-author-note: 2
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. The template demonstrates the use of in-text citations, possessive citations, masked citations, meta-analytpic citations, block quotes, equations, figures, and tables. Creating appendices is demonstrated."
# Put as many keywords at you like
keywords: 
  - APA Style
  - Quarto
  - Markdown
  - apaquarto
# Optional statement about the importance of the paper. The heading can be customized in the language field.
impact-statement: "The apaquarto template allow writers to apply APA style consistently with minimal fuss and bother."
# If true, a word count will appear below the keywords (tables, figure captions, and references excluded in count.)
word-count: false
# 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
# Set first page number of body
first-page: 9
# 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, nocite references are prefixed with asterisks
meta-analysis: true
nocite: |
  @bentley1929instructions, @cohen2003applied
# 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
# Additional language options
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; [credit.niso.org](https://credit.niso.org)) as follows:"
  title-impact-statement: "Impact Statement"
  references-meta-analysis: "References marked with an asterisk indicate studies included in the meta-analysis."
# Keep `false` to remain consistent with APA style. If `true`, replaces ampersands with `and` or word specified in `citation-last-author-separator` in parenthetical citations. 
no-ampersand-parenthetical: false
fontsize: 12pt
format:
  apaquarto-html: 
    toc: true
  apaquarto-docx: 
    toc: false
  apaquarto-typst: 
    keep-typ: true
    list-of-figures: false
    list-of-tables: false
    toc: false
    papersize: "us-letter"
  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(apa7)
library(knitr)
library(tinytable)
conflicts_prefer(dplyr::filter, .quiet = TRUE)
conflicts_prefer(flextable::separate_header, .quiet = TRUE)
conflicts_prefer(ggplot2::theme_void, .quiet = TRUE)
set_flextable_defaults(theme_fun = theme_apa, 
                       font.family = "Times New Roman", 
                       text.align = "center", 
                       table_align = "left")
```

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). In general, level 1 headings should be reserved for the Method, Results, Discussion, References, and Appendices sections. 

## YAML metadata

At the top of the apaquarto document, there is a lot of metadata (e.g., title, authors, affiliations, abstract, and so forth) written in YAML. Although the various options apaquarto are all documented, keeping track of them all can be difficult. Generating the initial YAML metadata can be easier if one begins with the the [apa7maker](https://wjschne.github.io/apa7maker/) web app.

## 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#citations) for explanations, examples, and citation features exclusive to apaquarto. For example, apaquarto can automatically handle possessive citations:

@CameronTrivedi2013 ['s] position differed from @brownHowKilledPluto2012 ['s, 1-2] take on the matter.

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

Here is a masked citation [@schneider2012cattell].

### Meta-analytic citations

By default, any references in the `nocite` field in your YAML heading will be assumed to be meta-analytic references that will appear in the reference section with an asterisk. If you want to use `nocite` but do not want references prefixed with asterisks, then set the  `meta-analysis` field to `false`. 

It is possible to cite meta-analytic references in text. For example, @cohen2003applied is listed in the `nocite` field.

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


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

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

A more practical example is the z-score equation seen in @eq-zscore.

$$
z=\frac{X-\mu}{\sigma}
$$ {#eq-zscore}

If no identifier label is given, a centered equation in display mode will have no identifying number:

$$
\sigma_e=\sigma_y\sqrt{1-r_{xy}^2}
$$

## Displaying Figures

Do you want the tables and figures to be at the end of the document? You can set the `floatsintext` option to false. The reference labels will work no matter where they are in the text.

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

## 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 my [apa7 package](https://wjschne.github.io/apa7/articles/apa7.html) adapts David Gohel's [flextable](https://davidgohel.github.io/flextable/) package to make a wide variety of APA-styled tables. In [this blog series](https://wjschne.github.io/posts/apatables/apa701.html), I used apa7 to  recreate the 24 example tables from chapter 7 of the *APA Publication Manual*.


```{r}
#| label: tbl-mytable
#| tbl-cap: The Table Caption. 
#| echo: false
#| apa-twocolumn: true
#| apa-note: 
#|   - This is the first paragraph.
#|   - This is a second paragraph. 

lm(price ~ carat + depth + table, data = ggplot2::diamonds) |>  
  apa_parameters() |> 
  apa_flextable()

```

To refer to this table in text, use the `@` symbol followed by the reference label like so: As seen in @tbl-mytable, the price of a diamond is related to several features of the diamond.



## 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
#| fig-pos: "tp"
ggplot(data.frame(x = c(-4, 4)), aes(x)) +
  stat_function(fun = dnorm, 
                geom = "area",
                n = 1000,
                color = NA,
                fill = "#41448780") +
  theme_void()
```

## Using Footnotes

A footnote is usually displayed at the bottom of the page on which the footnote occurs.  A short note can be specified with the `^[My note here]` syntax.^[Here is my short footnote!] A longer note can be specified with the `[^id]` syntax with the text specified on a separate line like so `[^id]: Text here`.[^mylongfootnote]

[^mylongfootnote]: This is a longer footnote. If it has multiple paragraphs, subsequent paragraphs need to be indented with two tabs.

    This paragraph is still part of the footnote because it is indented with two tabs.

A regular paragraph without any indentation is not part of the footnote and will be part of the main body of the document.

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

@tbl-mymarkdowntable2 is an example of a plain markdown table. Note the that the caption begins with a colon.

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

: My Caption. {#tbl-mymarkdowntable2 apa-note="My note"}



# 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}
:::


# My Appendix {#apx-a}

Any level 1 heading after the reference section (if it exists) is an appendix. If you do not specify a reference section, you will need to give the level-1 heading an identifier with an `#apx-` prefix. For example,

`# My Appendix {#apx-a}`

Appendices are created as level 1 headings with an  `#apx-` prefix in the identifier. Appendix titles should be in title case and should describe the content of the appendix.

If there is only one appendix, the label inserted above the the appendix title will be **Appendix**. If there are multiple appendices, the labels **Appendix A**, **Appendix B**, **Appendix C** and so forth will be inserted above the titles.

To cite an appendix as a whole, reference it with the `@apx-` prefix. For example, see @apx-a and @apx-b.

@apx-a is an appendix with a contingency table (see @tbl-chisq).

```{r}
#| label: tbl-chisq
#| tbl-cap: Contingency table
#| apa-twocolumn: true
mtcars |>
  select(Transmission = am, Gears = gear) |>
  mutate(Gears = factor(Gears),
         Transmission = factor(Transmission, 
                               labels = c("Automatic", "Manual"))) |>
  apa_chisq()
```


# Another Appendix {#apx-b}

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

See @fig-appendfig, an example of an imported graphic using markdown syntax.