Title:	Prepare American Psychological Association Journal Articles with R Markdown
Version:	0.1.3
Description:	Tools to create dynamic, submission-ready manuscripts, which conform to American Psychological Association manuscript guidelines. We provide R Markdown document formats for manuscripts (PDF and Word) and revision letters (PDF). Helper functions facilitate reporting statistical analyses or create publication-ready tables and plots.
Date:	2024-10-23
URL:	https://github.com/crsh/papaja
BugReports:	https://github.com/crsh/papaja/issues
Depends:	R (≥ 4.2), tinylabels (≥ 0.2.4)
Imports:	bookdown (≥ 0.41), broom (≥ 1.0.7), glue (≥ 1.8.0), knitr (≥ 1.48), methods, rmarkdown (≥ 2.28), rmdfiltr (≥ 0.1.5), utils, yaml (≥ 2.3.10), zip (≥ 2.3.1)
Suggests:	afex, BayesFactor, beeswarm, boot, car, dplyr (≥ 1.1.0), effectsize (≥ 0.4.4), emmeans, ggforce, ggplot2, latex2exp, lme4, lmerTest, MASS, MBESS, multcomp, nlme, nnet, R.rsp, skimr, spelling, testthat, VGAM
SystemRequirements:	Rendering the document template requires pandoc (>= 2.0; https://pandoc.org) and for PDFs a TeX distribution, such as TinyTeX (>= 0.12; https://yihui.org/tinytex/)
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
VignetteBuilder:	knitr, R.rsp
Language:	en-US
NeedsCompilation:	no
Packaged:	2024-10-24 09:11:57 UTC; frederikaust
Author:	Frederik Aust [aut, cre], Marius Barth [aut], Birk Diedenhofen [ctb], Christoph Stahl [ctb], Joseph V. Casillas [ctb], Rudolf Siegel [ctb]
Maintainer:	Frederik Aust <frederik.aust@uni-koeln.de>
Repository:	CRAN
Date/Publication:	2024-10-24 11:10:02 UTC

Prepare APA Journal Articles with R Markdown

Description

papaja is an award-winning R package that facilitates creating computationally reproducible, submission-ready manuscripts which conform to the American Psychological Association (APA) manuscript guidelines (6th Edition).

Details

papaja provides

• an R Markdown template that can be used with (or without) RStudio to create PDF documents (using the apa6 LaTeX class) or Word documents (using a .docx-reference file).

• Functions to typeset the results from statistical analyses (e.g., apa_print()),

• functions to create tables (apa_table()), and

• functions to create figures in accordance with APA guidelines (e.g., apa_factorial_plot()).

System requirements

To use papaja you need either an up-to-date version of RStudio or pandoc. If you want to create PDF- in addition to DOCX-documents you additionally need a TeX distribution. We recommend TinyTex, which can be installed from within R via the tinytex package.

Please refer to the papaja manual for detailed installation instructions.

Getting help

For a comprehensive introduction to papaja, see the current draft of the manual. If you have a specific question that is not answered in the manual, feel free to ask a question on Stack Overflow using the papaja tag. If you believe you have found a bug or would like to request a new feature, open an issue on Github and provide a minimal complete verifiable example.

Authors

Frederik Aust (frederik.aust at uni-koeln.de). Marius Barth (marius.barth at uni-koeln.de).

Maintainer

Frederik Aust (frederik.aust at uni-koeln.de).

Author(s)

Maintainer: Frederik Aust frederik.aust@uni-koeln.de (ORCID)

Authors:

• Marius Barth marius.barth@uni-koeln.de (ORCID)

Other contributors:

• Birk Diedenhofen mail@birkdiedenhofen.de [contributor]

• Christoph Stahl christoph.stahl@uni-koeln.de [contributor]

• Joseph V. Casillas joseph.casillas@rutgers.edu [contributor]

• Rudolf Siegel rudolf.siegel@uni-saarland.de [contributor]

See Also

Useful links:

• https://github.com/crsh/papaja

• Report bugs at https://github.com/crsh/papaja/issues

Extract Parts of an APA Results Table

Description

These methods are only defined for backward compatibility with older versions of papaja. In the past, the column names ofapa_results_tables were less standardized than they are today. In order to maintain backwards compatibility, it is still possible to extract columns with the old columns names, because we here provide aliased indexing. Note that aliased indexing will be defunct in a future release of papaja.

Usage

## S3 method for class 'apa_results_table'
x$name

## S3 method for class 'apa_results_table'
x[[i, exact = TRUE]]

## S3 method for class 'apa_results_table'
x[i, j, ..., drop = TRUE]

Arguments

Value

A (vector of) character values as extracted from an object of class apa_results_table.

Add table headings to group columns

Description

Takes a named list of containing column numbers to group with a heading This function is not exported.

Usage

add_col_spanners(table_lines, col_spanners, n_cols, add_group_midrules = TRUE)

Arguments

See Also

apa_table()

Effect Sizes for Analysis of Variance

Description

Calculates effect-size measures for Analysis of Variance output objects. This function is not exported and will soon be deprecated.

Usage

add_effect_sizes(x, es = "ges", observed = NULL, intercept = FALSE)

Arguments

Add Equals Where Necessary

Description

This is an internal function that prepends every element of a character vector with an 'equals' sign if the respective element does not contain one of c("=", "<", ">").

Usage

add_equals(x)

Arguments

Value

Character vector

Examples

add_equals(c("42", "<= 42", "> 42", "= 42"))

Add row names as first column

Description

Adds row names as the first column of the table and sets row.name attribute to NULL. This function is not exported.

Usage

add_row_names(x, added_stub_head, force = FALSE)

Arguments

See Also

apa_table()

APA manuscript (6th edition)

Description

Template for creating an article according to APA guidelines (6th edition) in PDF or DOCX format.

Usage

apa6_pdf(
  fig_caption = TRUE,
  number_sections = FALSE,
  toc = FALSE,
  keep_tex = TRUE,
  md_extensions = NULL,
  includes = NULL,
  ...
)

apa6_docx(
  fig_caption = TRUE,
  number_sections = FALSE,
  md_extensions = NULL,
  ...
)

apa6_word(...)

apa6_doc(...)

Arguments

Details

When creating PDF documents the YAML option classoption is passed to the class options of the LaTeX apa6 document class. In this case, additional options are available. Refer to the apa6 document class documentation to find out about class options such as paper size or draft watermarks.

Please refer to the papaja online-manual for additional information on available YAML front matter settings. Note that the available settings for DOCX documents are more limited than for PDF documents.

When creating PDF documents the output device for figures defaults to c("pdf", "png"), so that each figure is saved in all four formats at a resolution of 300 dpi.

Value

R Markdown output format to pass to rmarkdown::render().

Functions

• apa6_word(): Format to create .docx-files. Alias of apa6_docx.

• apa6_doc(): Format to create .docx-files. Alias of apa6_docx.

See Also

bookdown::pdf_document2(), bookdown::word_document2()

Bar Plots for Factorial Designs that Conform to APA Guidelines

Description

Create one or more bar plots from a data.frame containing data from a factorial design and set APA-friendly defaults.

Usage

apa_barplot(data, ...)

## Default S3 method:
apa_barplot(
  data,
  id,
  factors = NULL,
  dv,
  tendency = mean,
  dispersion = conf_int,
  level = 0.95,
  fun_aggregate = mean,
  na.rm = TRUE,
  use = "all.obs",
  reference = 0,
  intercept = NULL,
  args_x_axis = NULL,
  args_y_axis = NULL,
  args_title = NULL,
  args_rect = NULL,
  args_error_bars = NULL,
  args_legend = NULL,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  set_par = TRUE,
  ...
)

## S3 method for class 'afex_aov'
apa_barplot(
  data,
  tendency = mean,
  dispersion = conf_int,
  fun_aggregate = mean,
  ...
)

Arguments

Details

The measure of dispersion can be either conf_int() for between-subjects confidence intervals, se() for standard errors, or any other standard function. For within-subjects confidence intervals, specify wsci() or within_subjects_conf_int().

If between- or within-subjects confidence intervals are requested, you can also specify the area of the cumulative distribution function that will be covered. For instance, if you want a 98% confidence interval, specify level = 0.98. The default is level = 0.95 for 95% confidence intervals.

Customization of plot elements

apa_factorial_plot() and its descendants apa_barplot(), apa_lineplot(), apa_beeplot(), and apa_violinplot() are wrapper functions that sequentially call:

• plot.new(),

• plot.window(),

• axis() (once for x axis, once for y axis),

• title() for axis labels and titles,

• rect() for bars in bar plots,

• points() for bee swarms,

• density() and polygon() for violins,

• lines() for lines connecting central tendency points,

• arrows() for error bars,

• points() for tendency points,

• legend() for a legend, and

• lines() for intercepts.

These calls can be customized by setting the respective parameters ⁠args_*** = list(...)⁠.

Value

A named (nested) list of plot options including raw and derived data. Note that the structure of the return value is about to change in a forthcoming release of papaja.

See Also

Other plots for factorial designs: apa_beeplot(), apa_factorial_plot(), apa_lineplot(), apa_violinplot()

Examples

apa_barplot(
   data = npk
   , id = "block"
   , dv = "yield"
   , factors = c("N")
)

apa_barplot(
   data = npk
   , id = "block"
   , dv = "yield"
   , factors = c("N", "P")
)

apa_barplot(
   data = npk
   , id = "block"
   , dv = "yield"
   , factors = c("N", "P", "K")
   , ylim = c(0, 80)
   , level = .34
   , las = 1
)

Bee-swarm Plots for Factorial Designs that Conform to APA Guidelines

Description

Create one or more beeswarm plots from a data.frame containing data from a factorial design and set APA-friendly defaults.

Usage

apa_beeplot(data, ...)

## Default S3 method:
apa_beeplot(
  data,
  id,
  factors = NULL,
  dv,
  tendency = mean,
  dispersion = conf_int,
  level = 0.95,
  fun_aggregate = mean,
  na.rm = TRUE,
  use = "all.obs",
  intercept = NULL,
  args_x_axis = NULL,
  args_y_axis = NULL,
  args_title = NULL,
  args_points = NULL,
  args_swarm = NULL,
  args_error_bars = NULL,
  args_legend = NULL,
  jit = 0.3,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  set_par = TRUE,
  ...
)

## S3 method for class 'afex_aov'
apa_beeplot(
  data,
  tendency = mean,
  dispersion = conf_int,
  fun_aggregate = mean,
  ...
)

Arguments

Details

The measure of dispersion can be either conf_int() for between-subjects confidence intervals, se() for standard errors, or any other standard function. For within-subjects confidence intervals, specify wsci() or within_subjects_conf_int().

If between- or within-subjects confidence intervals are requested, you can also specify the area of the cumulative distribution function that will be covered. For instance, if you want a 98% confidence interval, specify level = 0.98. The default is level = 0.95 for 95% confidence intervals.

Customization of plot elements

apa_factorial_plot() and its descendants apa_barplot(), apa_lineplot(), apa_beeplot(), and apa_violinplot() are wrapper functions that sequentially call:

• plot.new(),

• plot.window(),

• axis() (once for x axis, once for y axis),

• title() for axis labels and titles,

• rect() for bars in bar plots,

• points() for bee swarms,

• density() and polygon() for violins,

• lines() for lines connecting central tendency points,

• arrows() for error bars,

• points() for tendency points,

• legend() for a legend, and

• lines() for intercepts.

These calls can be customized by setting the respective parameters ⁠args_*** = list(...)⁠.

Value

A named (nested) list of plot options including raw and derived data. Note that the structure of the return value is about to change in a forthcoming release of papaja.

See Also

Other plots for factorial designs: apa_barplot(), apa_factorial_plot(), apa_lineplot(), apa_violinplot()

Examples

apa_beeplot(
   data = npk
   , id = "block"
   , dv = "yield"
   , factors = c("N")
)

apa_beeplot(
  data = npk
 , id = "block"
 , dv = "yield"
 , factors = c("N", "P")
 , args.legend = list(x = "center")
)

apa_beeplot(
   data = npk
   , id = "block"
   , dv = "yield"
   , factors = c("N", "P", "K")
   , ylim = c(0, 80)
   , level = .34
   , las = 1
)

Typeset Degrees of Freedom

Description

This is a function for processing degrees of freedom. It takes care that trailing digits are only printed if non-integer values are given.

Usage

apa_df(x, digits = 2L, big.mark = "", elementwise = TRUE)

print_df(x, digits = 2L, big.mark = "", elementwise = TRUE)

Arguments

Value

An object of the same class as x with all numeric values converted to character.

See Also

apa_num(), apa_p()

Examples

apa_df(c(1, 1.23151))

Plots for Factorial Designs that Conform to APA Guidelines

Description

Create one or more plots by sequentially calling functions from the graphics package. apa_factorial_plot() is the workhorse function that is called by apa_barplot(), apa_beeplot(), and apa_lineplot().

Usage

apa_factorial_plot(data, ...)

## Default S3 method:
apa_factorial_plot(
  data,
  id,
  factors = NULL,
  dv,
  tendency = mean,
  dispersion = conf_int,
  level = 0.95,
  fun_aggregate = mean,
  na.rm = TRUE,
  use = "all.obs",
  reference = 0,
  intercept = NULL,
  args_x_axis = NULL,
  args_y_axis = NULL,
  args_title = NULL,
  args_rect = NULL,
  args_points = NULL,
  args_lines = NULL,
  args_swarm = NULL,
  args_violins = NULL,
  args_density = NULL,
  args_error_bars = NULL,
  args_legend = NULL,
  plot = NULL,
  jit = 0.3,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  set_par = TRUE,
  ...
)

## S3 method for class 'afex_aov'
apa_factorial_plot(
  data,
  tendency = mean,
  dispersion = conf_int,
  fun_aggregate = mean,
  ...
)

Arguments

Details

The measure of dispersion can be either conf_int() for between-subjects confidence intervals, se() for standard errors, or any other standard function. For within-subjects confidence intervals, specify wsci() or within_subjects_conf_int().

If between- or within-subjects confidence intervals are requested, you can also specify the area of the cumulative distribution function that will be covered. For instance, if you want a 98% confidence interval, specify level = 0.98. The default is level = 0.95 for 95% confidence intervals.

Customization of plot elements

apa_factorial_plot() and its descendants apa_barplot(), apa_lineplot(), apa_beeplot(), and apa_violinplot() are wrapper functions that sequentially call:

• plot.new(),

• plot.window(),

• axis() (once for x axis, once for y axis),

• title() for axis labels and titles,

• rect() for bars in bar plots,

• points() for bee swarms,

• density() and polygon() for violins,

• lines() for lines connecting central tendency points,

• arrows() for error bars,

• points() for tendency points,

• legend() for a legend, and

• lines() for intercepts.

These calls can be customized by setting the respective parameters ⁠args_*** = list(...)⁠.

Value

A named (nested) list of plot options including raw and derived data. Note that the structure of the return value is about to change in a forthcoming release of papaja.

See Also

Other plots for factorial designs: apa_barplot(), apa_beeplot(), apa_lineplot(), apa_violinplot()

Examples

apa_factorial_plot(
  data = npk
  , id = "block"
  , dv = "yield"
  , factors = c("N", "P", "K")
  , las = 1
  , plot = c("error_bars", "points", "swarms")
  , ylim = c(0, 100)
)

Plots for factorial designs that conform to APA guidelines, two-factors internal function

Description

Internal function that is called (possibly multiple times) by apa_factorial_plot().

Usage

apa_factorial_plot_single(
  aggregated,
  y.values,
  id,
  dv,
  factors,
  intercept = NULL,
  ...
)

Arguments

Typeset Interval Estimate

Description

Creates a character string to report interval estimates, such as frequentist confidence or Bayesian credible intervals.

Usage

apa_interval(x, ...)

print_interval(x, ...)

## S3 method for class 'numeric'
apa_interval(
  x,
  y = NULL,
  ...,
  conf.int = NULL,
  interval_type = NULL,
  enclose_math = FALSE
)

## S3 method for class 'matrix'
apa_interval(
  x,
  ...,
  conf.int = NULL,
  interval_type = NULL,
  enclose_math = FALSE
)

## S3 method for class 'data.frame'
apa_interval(
  x,
  ...,
  conf.int = NULL,
  interval_type = NULL,
  enclose_math = FALSE
)

## S3 method for class 'list'
apa_interval(
  x,
  ...,
  conf.int = NULL,
  interval_type = NULL,
  enclose_math = FALSE
)

apa_confint(
  x,
  ...,
  conf.int = NULL,
  interval_type = "CI",
  enclose_math = FALSE
)

print_confint(
  x,
  ...,
  conf.int = NULL,
  interval_type = "CI",
  enclose_math = FALSE
)

apa_hdint(x, ..., conf.int = NULL, interval_type = "HDI", enclose_math = FALSE)

print_hdint(
  x,
  ...,
  conf.int = NULL,
  interval_type = "HDI",
  enclose_math = FALSE
)

Arguments

Details

If possible the confidence level of the interval is inferred from attributes of x. For a vector of length 2, the attribute conf.level is is consulted; for a matrix or data.frame the column names are used, if they are of the format "2.5 \

If x is a matrix or data.frame the row names are used as names for the returned list of intervals.

Value

A single interval is returned as a character vector of length 1; multiple intervals are returned as a named list of character vectors of length 1.

See Also

apa_num()

Examples

apa_confint(1, 2, conf.int = 0.95)
apa_confint(c(1, 2), conf.int = 0.95)
apa_confint(matrix(c(1, 2), ncol = 2), conf.int = 0.95)
apa_confint(confint(lm(cars)))
apa_confint(confint(lm(cars)), digits = 3)

Line Plots for Factorial Designs that Conform to APA Guidelines

Description

Creates one or more line plots from a data.frame containing data from a factorial design and set APA-friendly defaults.

Usage

apa_lineplot(data, ...)

## Default S3 method:
apa_lineplot(
  data,
  id,
  factors = NULL,
  dv,
  tendency = mean,
  dispersion = conf_int,
  level = 0.95,
  fun_aggregate = mean,
  na.rm = TRUE,
  use = "all.obs",
  intercept = NULL,
  args_x_axis = NULL,
  args_y_axis = NULL,
  args_title = NULL,
  args_points = NULL,
  args_lines = NULL,
  args_error_bars = NULL,
  args_legend = NULL,
  jit = 0.3,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  set_par = TRUE,
  ...
)

## S3 method for class 'afex_aov'
apa_lineplot(
  data,
  tendency = mean,
  dispersion = conf_int,
  fun_aggregate = mean,
  ...
)

Arguments

Details

The measure of dispersion can be either conf_int() for between-subjects confidence intervals, se() for standard errors, or any other standard function. For within-subjects confidence intervals, specify wsci() or within_subjects_conf_int().

If between- or within-subjects confidence intervals are requested, you can also specify the area of the cumulative distribution function that will be covered. For instance, if you want a 98% confidence interval, specify level = 0.98. The default is level = 0.95 for 95% confidence intervals.

Customization of plot elements

apa_factorial_plot() and its descendants apa_barplot(), apa_lineplot(), apa_beeplot(), and apa_violinplot() are wrapper functions that sequentially call:

• plot.new(),

• plot.window(),

• axis() (once for x axis, once for y axis),

• title() for axis labels and titles,

• rect() for bars in bar plots,

• points() for bee swarms,

• density() and polygon() for violins,

• lines() for lines connecting central tendency points,

• arrows() for error bars,

• points() for tendency points,

• legend() for a legend, and

• lines() for intercepts.

These calls can be customized by setting the respective parameters ⁠args_*** = list(...)⁠.

Value

A named (nested) list of plot options including raw and derived data. Note that the structure of the return value is about to change in a forthcoming release of papaja.

See Also

Other plots for factorial designs: apa_barplot(), apa_beeplot(), apa_factorial_plot(), apa_violinplot()

Examples

apa_lineplot(
   data = npk
   , id = "block"
   , dv = "yield"
   , factors = c("N")
)

apa_lineplot(
data = npk
 , id = "block"
 , dv = "yield"
 , factors = c("N", "P")
 , args_legend = list(x = "center")
 , jit = 0
)

apa_lineplot(
   data = npk
   , id = "block"
   , dv = "yield"
   , factors = c("N", "P", "K")
   , ylim = c(0, 80)
   , level = .34
   , las = 1
)

Typeset Numerical Values for Printing and Reporting

Description

Converts numerical values to character strings for printing and reporting.

Usage

apa_num(x, ...)

printnum(x, ...)

print_num(x, ...)

## Default S3 method:
apa_num(x, na_string = getOption("papaja.na_string"), ...)

## S3 method for class 'list'
apa_num(x, ...)

## S3 method for class 'integer'
apa_num(
  x,
  numerals = TRUE,
  capitalize = FALSE,
  zero_string = "no",
  na_string = getOption("papaja.na_string"),
  ...
)

## S3 method for class 'numeric'
apa_num(
  x,
  gt1 = TRUE,
  zero = TRUE,
  na_string = getOption("papaja.na_string"),
  use_math = TRUE,
  add_equals = FALSE,
  ...
)

## S3 method for class 'data.frame'
apa_num(x, margin = 2, ...)

## S3 method for class 'matrix'
apa_num(x, margin = 2, ...)

## S3 method for class 'tiny_labelled'
apa_num(x, ...)

Arguments

Details

If x is a vector, all arguments can be vectors according to which each element of the vector is formatted. Parameters are recycled if length of x exceeds the length of the parameter vectors. If x is a matrix or data.frame, the vectors specify the formatting of either rows or columns according to the value of margin.

We recommend to use apa_num(), rather than printnum() or print_num(), which are aliases kept only for backward compatibility.

Value

An object of the same class as x with all numeric values converted to character.

See Also

apa_p(), apa_df()

Examples

apa_num(1/3)
apa_num(1/3, gt1 = FALSE)
apa_num(1/3, digits = 5)

apa_num(0)
apa_num(0, zero = FALSE)

Prepare Numeric Values for Printing as p value

Description

Convenience wrapper for apa_num to print p values.

Usage

apa_p(x, digits = 3L, na_string = "", add_equals = FALSE)

printp(x, digits = 3L, na_string = "", add_equals = FALSE)

print_p(x, digits = 3L, na_string = "", add_equals = FALSE)

Arguments

Value

An object of the same class as x with all numeric values converted to character.

See Also

apa_num(), apa_df()

Examples

apa_p(0.05)
apa_p(0.0005)
apa_p(0.99999999)
apa_p(c(.001, 0), add_equals = TRUE)

Prepare APA document (deprecated)

Description

Prepares objects to be used in the rendering process and creates title page and abstract for MS Word documents. This function has been defunct. It is no longer needed.

Usage

apa_prepare_doc()

Details

The function creates and locks a non-exported object apa_lang that is used by other papaja-functions. apa_lang is a list containing localizations for document elements such as abstract and title. The selected language is defined by the lang-parameter in the documents yaml-header. Currently, English (default) and German ("german") are supported.

If the output document is MS Word (⁠output: \link{apa6_word}⁠) the function additionally creates a title page and adds the abstract. You should, therefore, always call apa_prepare_doc at the very beginning of the R Markdown document.

Value

Returns NULL invisibly.

See Also

apa6_docx()

Typeset Statistical Results

Description

A generic function that takes objects from various statistical methods to create formatted character strings to report the results in accordance with APA manuscript guidelines. The function invokes particular methods, which depend on the class of the first argument.

Usage

apa_print(x, ...)

Arguments

Value

apa_print()-methods return a named list of class apa_results containing the following elements:

Column names in apa_results_table are standardized following the broom glossary (e.g., term, estimate conf.int, statistic, df, df.residual, p.value). Additionally, each column is labelled (e.g., $\hat{\eta}^2_G$ or $t$) using the tinylabels package and these labels are used as column names when an apa_results_table is passed to apa_table().

See Also

Other apa_print: apa_print.BFBayesFactor(), apa_print.aov(), apa_print.emmGrid(), apa_print.glht(), apa_print.htest(), apa_print.list(), apa_print.lm(), apa_print.lme(), apa_print.merMod()

Examples

# List methods for apa_print()
methods("apa_print")

Typeset Bayes Factors

Description

These methods take result objects from the BayesFactor package to create formatted character strings to report the results in accordance with APA manuscript guidelines.

Usage

## S3 method for class 'BFBayesFactor'
apa_print(
  x,
  stat_name = NULL,
  est_name = NULL,
  subscript = NULL,
  escape_subscript = FALSE,
  scientific_threshold = NULL,
  reciprocal = FALSE,
  log = FALSE,
  mcmc_error = any(x@bayesFactor$error > 0.05),
  iterations = 10000,
  standardized = FALSE,
  central_tendency = median,
  interval = hd_int,
  interval_type = "HDI",
  bf_r1 = NULL,
  bf_1r = NULL,
  ...
)

## S3 method for class 'BFBayesFactorTop'
apa_print(x, reciprocal = FALSE, ...)

Arguments

Details

stat_name and est_name are placed in the output string and are thus passed to pandoc or LaTeX through knitr. To the extent it is supported by the final document type, you can pass LaTeX-markup to format the final text (e.g., M_\Delta yields M_\Delta).

For models with order constraint, the evidence for the order constraint relative to the null model can be obtained by multiplying the Bayes factor BF_{r1} for the order constraint relative to the unconstrained model (bf_r1) with the Bayes factor BF_{10} for the unconstrained model relative to the null model,

\frac{p(y \mid {\cal M}_r)}{p(y \mid {\cal M}_0)} = \frac{p(y \mid {\cal M}_r)}{p(y \mid {\cal M}_1)} \times \frac{p(y \mid {\cal M}_1)}{p(y \mid {\cal M}_0)}

.

BF_{r1} can be calculated from the prior and posterior odds of the order constraint (e.g., Morey & Wagenmakers, 2014). If bf_r1 (or bf_1r) is specified they are multiplied with the corresponding Bayes factor supplied in x before the reciprocal is taken and the results are formatted. Note, that it is not possible to determine whether x gives BF_{10} or BF_{01} and, hence, bf_r1 and bf_1r are treated identically; the different argument names only serve to ensure the expressiveness of the code. It is the user's responsibility to ensure that the supplied Bayes factor is correct!

Value

apa_print()-methods return a named list of class apa_results containing the following elements:

Column names in apa_results_table are standardized following the broom glossary (e.g., term, estimate conf.int, statistic, df, df.residual, p.value). Additionally, each column is labelled (e.g., $\hat{\eta}^2_G$ or $t$) using the tinylabels package and these labels are used as column names when an apa_results_table is passed to apa_table().

References

Morey, R. D., & Wagenmakers, E.-J. (2014). Simple relation between Bayesian order-restricted and point-null hypothesis tests. Statistics & Probability Letters, 92, 121–124. doi: doi:10.1016/j.spl.2014.05.010

See Also

Other apa_print: apa_print(), apa_print.aov(), apa_print.emmGrid(), apa_print.glht(), apa_print.htest(), apa_print.list(), apa_print.lm(), apa_print.lme(), apa_print.merMod()

Examples

# ANOVA

data(sleep, package = "BayesFactor")
bayesian_anova <- BayesFactor::anovaBF(
  extra ~ group + ID
  , data = sleep
  , whichRandom = "ID"
  , progress = FALSE
)

# Paired t-test
ttest_paired <- BayesFactor::ttestBF(
  x = sleep$extra[sleep$group == 1]
  , y = sleep$extra[sleep$group == 2]
  , paired = TRUE
)

# Results for paired t-tests are indistinguishable
# from one-sample t-tests. We therefore specify the
# appropriate `est_name` manually.
apa_print(
  ttest_paired
  , est_name = "M_D"
  , iterations = 1000
)

apa_print(
  ttest_paired
  , iterations = 1000
  , interval = function(x) quantile(x, probs = c(0.025, 0.975))
  , interval_type = "CrI"
)

Typeset Statistical Results from Analysis of Variance (or Deviance)

Description

These methods take objects from various R functions that calculate analysis of variance (i.e., ANOVA) or analysis of deviance. They create formatted character strings to report the results in accordance with APA manuscript guidelines. For anova-objects from model comparisons see apa_print.list().

Usage

## S3 method for class 'aov'
apa_print(
  x,
  estimate = getOption("papaja.estimate_anova", "ges"),
  observed = NULL,
  intercept = FALSE,
  mse = getOption("papaja.mse", TRUE),
  in_paren = FALSE,
  ...
)

## S3 method for class 'summary.aov'
apa_print(
  x,
  estimate = getOption("papaja.estimate_anova", "ges"),
  observed = NULL,
  intercept = FALSE,
  mse = getOption("papaja.mse", TRUE),
  in_paren = FALSE,
  ...
)

## S3 method for class 'aovlist'
apa_print(
  x,
  estimate = getOption("papaja.estimate_anova", "ges"),
  observed = NULL,
  intercept = FALSE,
  mse = getOption("papaja.mse", TRUE),
  in_paren = FALSE,
  ...
)

## S3 method for class 'summary.aovlist'
apa_print(
  x,
  estimate = getOption("papaja.estimate_anova", "ges"),
  observed = NULL,
  intercept = FALSE,
  mse = getOption("papaja.mse", TRUE),
  in_paren = FALSE,
  ...
)

## S3 method for class 'Anova.mlm'
apa_print(
  x,
  estimate = getOption("papaja.estimate_anova", "ges"),
  observed = NULL,
  correction = getOption("papaja.sphericity_correction"),
  intercept = FALSE,
  mse = getOption("papaja.mse", TRUE),
  in_paren = FALSE,
  ...
)

## S3 method for class 'summary.Anova.mlm'
apa_print(
  x,
  estimate = getOption("papaja.estimate_anova", "ges"),
  observed = NULL,
  correction = getOption("papaja.sphericity_correction"),
  intercept = FALSE,
  mse = getOption("papaja.mse", TRUE),
  in_paren = FALSE,
  ...
)

## S3 method for class 'afex_aov'
apa_print(
  x,
  estimate = getOption("papaja.estimate_anova", "ges"),
  observed = NULL,
  correction = getOption("papaja.sphericity_correction"),
  intercept = FALSE,
  mse = getOption("papaja.mse", TRUE),
  in_paren = FALSE,
  ...
)

## S3 method for class 'anova'
apa_print(
  x,
  estimate = getOption("papaja.estimate_anova", "ges"),
  observed = NULL,
  intercept = FALSE,
  mse = getOption("papaja.mse", TRUE),
  in_paren = FALSE,
  ...
)

## S3 method for class 'manova'
apa_print(x, test = "Pillai", in_paren = FALSE, ...)

## S3 method for class 'summary.manova'
apa_print(x, in_paren = FALSE, ...)

Arguments

Details

The factor names are sanitized to facilitate their use as list names (see Value section). Parentheses are omitted and other non-word characters are replaced by ⁠_⁠.

Argument estimate determines which measure of effect size is to be used: It is currently possible to provide one of three characters to specify the to-be-calculated effect size: "ges" for generalized \eta^2, "pes" for partial \eta^2, and "es" for \eta^2. Note that \eta^2 is calculated correctly if and only if the design is balanced.

It is also possible to provide a data.frame with columns estimate, conf.low, and conf.high, which allows for including custom effect- size measures.

A third option is to provide a function from the effectsize package that will be used to calculate effect-size measures from x. If effectsize is installed (and papaja is loaded), this is the new default. This default can be changed via options(papaja.estimate_anova = ...).

Value

apa_print()-methods return a named list of class apa_results containing the following elements:

Column names in apa_results_table are standardized following the broom glossary (e.g., term, estimate conf.int, statistic, df, df.residual, p.value). Additionally, each column is labelled (e.g., $\hat{\eta}^2_G$ or $t$) using the tinylabels package and these labels are used as column names when an apa_results_table is passed to apa_table().

References

Bakeman, R. (2005). Recommended effect size statistics for repeated measures designs. Behavior Research Methods , 37 (3), 379–384. doi: doi:10.3758/BF03192707

See Also

aov(), car::Anova(), apa_print.list()

Other apa_print: apa_print(), apa_print.BFBayesFactor(), apa_print.emmGrid(), apa_print.glht(), apa_print.htest(), apa_print.list(), apa_print.lm(), apa_print.lme(), apa_print.merMod()

Examples

   ## From Venables and Ripley (2002) p. 165.
   npk_aov <- aov(yield ~ block + N * P * K, npk)
   apa_print(npk_aov)

   # Use the effectsize package to calculate partial eta-squared with
   # confidence intervals
   apa_print(npk_aov, estimate = effectsize::omega_squared)

Typeset Statistical Results from Estimated Marginal Means

Description

Takes various emmeans objects to create formatted character strings to report the results in accordance with APA manuscript guidelines. emmeans supports a wide range of analyses, not all of which are currently (fully) supported. Proceed with caution.

Usage

## S3 method for class 'emmGrid'
apa_print(x, infer = TRUE, conf.int = 0.95, ...)

## S3 method for class 'summary_emm'
apa_print(
  x,
  contrast_names = NULL,
  est_name = "\\hat{\\theta}",
  in_paren = FALSE,
  ...
)

## S3 method for class 'lsmobj'
apa_print(x, ...)

## S3 method for class 'summary.ref.grid'
apa_print(x, ...)

Arguments

Details

When p-values and confidence intervals are adjusted for multiple testing, the correction method is added as an index to the output (e.g. ⁠p_{Tukey(3)}⁠). Values in parenthesis indicate the size of the family of tests or the rank of the set of linear functions (for the Scheffé method).

If possible, each family of tests is additionally marked in the returned table by alphabetic superscripts.

Generally, the summary_emm objects returned by emmeans::summary_emm omit information that may be needed to add some of the information on the adjustments made to p-values and confidence intervals. It is therefore preferable to pass emmGrid-objects if possible. For example, by using emmeans(object, 1 ~ x1, adjust = "scheffe").

Value

apa_print()-methods return a named list of class apa_results containing the following elements:

Column names in apa_results_table are standardized following the broom glossary (e.g., term, estimate conf.int, statistic, df, df.residual, p.value). Additionally, each column is labelled (e.g., $\hat{\eta}^2_G$ or $t$) using the tinylabels package and these labels are used as column names when an apa_results_table is passed to apa_table().

See Also

Other apa_print: apa_print(), apa_print.BFBayesFactor(), apa_print.aov(), apa_print.glht(), apa_print.htest(), apa_print.list(), apa_print.lm(), apa_print.lme(), apa_print.merMod()

Examples

  # From the emmeans manual:
  library(emmeans)
  warp.lm <- lm(breaks ~ wool*tension, data = warpbreaks)
  warp.emm <- emmeans(warp.lm, ~ tension | wool)
  warp.contr <- contrast(warp.emm, "poly")

  apa_print(warp.contr)

  # In this example, because degrees of freedom are equal across all rows
  # of the output, it is possible to move that information to the variable
  # labels. This is useful if a compact results table is required:

  df_into_label(apa_print(warp.contr))

Typeset Statistical Results from General Linear Hypothesis Tests

Description

These methods are not properly tested and should be considered experimental.

Usage

## S3 method for class 'glht'
apa_print(x, test = multcomp::adjusted(), ...)

## S3 method for class 'summary.glht'
apa_print(x, conf.int = 0.95, in_paren = FALSE, ...)

Arguments

Value

apa_print()-methods return a named list of class apa_results containing the following elements:

Column names in apa_results_table are standardized following the broom glossary (e.g., term, estimate conf.int, statistic, df, df.residual, p.value). Additionally, each column is labelled (e.g., $\hat{\eta}^2_G$ or $t$) using the tinylabels package and these labels are used as column names when an apa_results_table is passed to apa_table().

See Also

Other apa_print: apa_print(), apa_print.BFBayesFactor(), apa_print.aov(), apa_print.emmGrid(), apa_print.htest(), apa_print.list(), apa_print.lm(), apa_print.lme(), apa_print.merMod()

Examples

   # From the multcomp::glht() examples:
   library(multcomp)
   amod <- aov(breaks ~ tension, data = warpbreaks)
   glht_out <- glht(amod, linfct = mcp(tension = "Tukey"))
   apa_print(glht_out)

  # In this example, because degrees of freedom are equal across all rows
  # of the output, it is possible to move that information to the variable
  # labels. This is useful if a compact results table is required:

  df_into_label(apa_print(glht_out))

Typeset Statistical Results from Hypothesis Tests

Description

Takes htest objects from various statistical methods (e.g., t.test(), wilcox.test(), cor.test()) to create formatted character strings to report the results in accordance with APA manuscript guidelines.

Usage

## S3 method for class 'htest'
apa_print(
  x,
  stat_name = NULL,
  est_name = NULL,
  n = NULL,
  conf.int = NULL,
  in_paren = FALSE,
  ...
)

Arguments

Details

The function should work on a wide range of htest objects. Due to the large number of functions that produce these objects and their idiosyncrasies, the returned strings should be compared to the original object. If you experience inaccuracies you may report these here (please include a reproducible example in your report).

stat_name and est_name are placed in the output string and are thus passed to pandoc or LaTeX through knitr. Thus, to the extent it is supported by the final document type, you can pass LaTeX-markup to format the final text (e.g., \\tau yields \tau).

Value

apa_print()-methods return a named list of class apa_results containing the following elements:

Column names in apa_results_table are standardized following the broom glossary (e.g., term, estimate conf.int, statistic, df, df.residual, p.value). Additionally, each column is labelled (e.g., $\hat{\eta}^2_G$ or $t$) using the tinylabels package and these labels are used as column names when an apa_results_table is passed to apa_table().

See Also

Other apa_print: apa_print(), apa_print.BFBayesFactor(), apa_print.aov(), apa_print.emmGrid(), apa_print.glht(), apa_print.list(), apa_print.lm(), apa_print.lme(), apa_print.merMod()

Examples

# Comparisons of central tendencies
t_stat <- t.test(extra ~ group, data = sleep)
apa_print(t_stat)
apa_print(t_stat, stat_name = "tee")

wilcox_stat <- wilcox.test(extra ~ group, data = sleep, exact = FALSE)
apa_print(wilcox_stat)

# Correlations
## Data from Hollander & Wolfe (1973), p. 187f.
x <- c(44.4, 45.9, 41.9, 53.3, 44.7, 44.1, 50.7, 45.2, 60.1)
y <- c( 2.6,  3.1,  2.5,  5.0,  3.6,  4.0,  5.2,  2.8,  3.8)
cor_stat <- cor.test(x, y, method = "spearman")
apa_print(cor_stat)

# Contingency tables
## Data from Fleiss (1981), p. 139.
smokers  <- c(83, 90, 129, 70)
patients <- c(86, 93, 136, 82)
prop_stat <- prop.test(smokers, patients)
apa_print(prop_stat, n = sum(patients))

Typeset Statistical Results from Linear-Model Comparisons

Description

This method performs comparisons of lm-objects and creates formatted character strings and a model comparison table to report the results in accordance with APA manuscript guidelines.

Usage

## S3 method for class 'list'
apa_print(
  x,
  anova_fun = stats::anova,
  conf.int = 0.9,
  boot_samples = 10000,
  progress_bar = interactive(),
  observed = TRUE,
  in_paren = FALSE,
  ...
)

Arguments

Details

As demonstrated by Algina, Keselman & Penfield (2007), asymptotic confidence intervals for \Delta R^2 are often unreliable. Confidence intervals for model comparisons of lm objects are, therefore, estimated using their modified percentile bootstrap method. Note that the accuracy of the confidence intervals depends on the number of predictors p, their distribution, and the sample size n:

"When the predictor distribution is multivariate normal, one can obtain accurate CIs for \rho^2 with n \geq~50 when p = 3. For p = 6 and for p = 9, n \geq~100 is advisable. When the predictor distribution is nonnormal in form, sample size requirements vary with type of nonnormality." (p. 939, Algina, Keselman & Penfield, 2010)

If MBESS is available, confidence intervals for R^2 are computed using MBESS::ci.R2() to obtain a confidence region that corresponds to the confidence level conf.int, the default being a 90% CI (see Steiger, 2004). If observed = FALSE, it is assumed that predictors are fixed variables, i.e., "the values of the [predictors] were selected a priori as part of the research design" (p. 15, Kelly, 2007); put differently, it is assumed that predictors are not random. The confidence intervals for the regression coefficients in the model comparison table correspond to the \alpha-level chosen for R^2 and \Delta R^2 (e.g., 90% CI or \alpha = 0.10 for R^2 and \Delta R^2 yields a 95% CI for regression coefficients, Steiger, 2004).

Value

apa_print()-methods return a named list of class apa_results containing the following elements:

Column names in apa_results_table are standardized following the broom glossary (e.g., term, estimate conf.int, statistic, df, df.residual, p.value). Additionally, each column is labelled (e.g., $\hat{\eta}^2_G$ or $t$) using the tinylabels package and these labels are used as column names when an apa_results_table is passed to apa_table().

References

Algina, J., Keselman, H. J., & Penfield, R. D. (2007). Confidence intervals for an effect size measure in multiple linear regression. Educational and Psychological Measurement, 67(2), 207–218. doi: doi:10.1177/0013164406292030

Algina, J., Keselman, H. J., & Penfield, R. D. (2010). Confidence intervals for squared semipartial correlation coefficients: The effect of nonnormality. Educational and Psychological Measurement, 70(6), 926–940. doi: doi:10.1177/0013164410379335

Steiger (2004). Beyond the F test: Effect size confidence intervals and tests of close fit in the analysis of variance and contrast analysis. Psychological Methods, 9(2), 164–182. doi: doi:10.1037/1082-989X.9.2.164

Kelley, K. (2007). Confidence intervals for standardized effect sizes: Theory, application, and implementation. Journal of Statistical Software, 20(8), 1–24. doi: doi:10.18637/jss.v020.i08

See Also

stats::anova()

Other apa_print: apa_print(), apa_print.BFBayesFactor(), apa_print.aov(), apa_print.emmGrid(), apa_print.glht(), apa_print.htest(), apa_print.lm(), apa_print.lme(), apa_print.merMod()

Examples

  mod1 <- lm(Sepal.Length ~ Sepal.Width, data = iris)
  mod2 <- update(mod1, formula = . ~ . + Petal.Length)
  mod3 <- update(mod2, formula = . ~ . + Petal.Width)

  # No bootstrapped Delta R^2 CI
  apa_print(list(Baseline = mod1, Length = mod2, Both = mod3), boot_samples = 0)

Typeset Statistical Results from GLM

Description

These methods take (generalized) linear model objects to create formatted character strings to report the results in accordance with APA manuscript guidelines.

Usage

## S3 method for class 'lm'
apa_print(
  x,
  est_name = NULL,
  standardized = FALSE,
  conf.int = 0.95,
  observed = TRUE,
  in_paren = FALSE,
  ...
)

## S3 method for class 'glm'
apa_print(
  x,
  est_name = NULL,
  standardized = FALSE,
  conf.int = 0.95,
  observed = TRUE,
  in_paren = FALSE,
  ...
)

## S3 method for class 'summary.glm'
apa_print(x, ...)

## S3 method for class 'summary.lm'
apa_print(x, ...)

Arguments

Details

The coefficient names are sanitized to facilitate their use as list names. Parentheses are omitted and other non-word characters are replaced by ⁠_⁠ (see sanitize_terms()).

est_name is placed in the output string and is then passed to pandoc or LaTeX through knitr. Thus, to the extent it is supported by the final document type, you can pass LaTeX-markup to format the final text (e.g., "\\\\beta" yields \beta).

If standardized = TRUE, scale() is removed from coefficient names (see examples). This option is currently ignored for glm-objects.

If conf.int is a single value, confidence intervals are calculated using stats::confint().

If x is an lm object and the MBESS package is available, confidence intervals for R^2 are computed using MBESS::ci.R2() to obtain a confidence region that corresponds to the \alpha-level chosen for the confidence intervals of regression coefficients (e.g., 95% CI or \alpha = 0.05 for regression coefficients yields a 90% CI for R^2, see Steiger, 2004). If observed = FALSE, it is assumed that predictors are fixed variables, i.e., "the values of the [predictors] were selected a priori as part of the research design" (p. 15, Kelly, 2007); put differently, it is assumed that predictors are not random.

Value

apa_print()-methods return a named list of class apa_results containing the following elements:

Column names in apa_results_table are standardized following the broom glossary (e.g., term, estimate conf.int, statistic, df, df.residual, p.value). Additionally, each column is labelled (e.g., $\hat{\eta}^2_G$ or $t$) using the tinylabels package and these labels are used as column names when an apa_results_table is passed to apa_table().

References

Steiger (2004). Beyond the F Test: Effect Size Confidence Intervals and Tests of Close Fit in the Analysis of Variance and Contrast Analysis. Psychological Methods, 9(2), 164-182. doi: doi:10.1037/1082-989X.9.2.164

Kelley, K. (2007). Confidence intervals for standardized effect sizes: Theory, application, and implementation. Journal of Statistical Software, 20(8), 1-24. doi: doi:10.18637/jss.v020.i08

See Also

stats::confint(), MBESS::ci.pvaf()

Other apa_print: apa_print(), apa_print.BFBayesFactor(), apa_print.aov(), apa_print.emmGrid(), apa_print.glht(), apa_print.htest(), apa_print.list(), apa_print.lme(), apa_print.merMod()

Examples

# Data from Dobson (1990), p. 9.
ctl <- c(4.17, 5.58, 5.18, 6.11, 4.50, 4.61, 5.17, 4.53, 5.33, 5.14)
trt <- c(4.81, 4.17, 4.41, 3.59, 5.87, 3.83, 6.03, 4.89, 4.32, 4.69)
group <- gl(2, 10, 20, labels = c("Ctl", "Trt"))
weight <- c(ctl, trt)
lm_fit <- lm(weight ~ group)

apa_print(lm_fit)

trt <- rep(trt, 2) # More data is always better
ctl <- rep(ctl, 2)
lm_fit2 <- lm(scale(trt) ~ scale(ctl))

apa_print(lm_fit2, standardized = TRUE)

# It is possible to simplify the regression table with transmute_df_into_label():
transmute_df_into_label(apa_print(lm_fit2, standardized = TRUE))


# Dobson (1990) Page 93: Randomized Controlled Trial :
counts <- c(18,17,15,20,10,20,25,13,12)
outcome <- gl(3,1,9)
treatment <- gl(3,3)
d.AD <- data.frame(treatment, outcome, counts)
glm.D93 <- glm(counts ~ outcome + treatment, family = poisson())

apa_print(glm.D93)

Typeset Statistical Results from Nonlinear Hierarchical Models

Description

These methods take mixed-effects models fitted with the nlme package and create formatted character strings report the results in accordance with APA manuscript guidelines.

Usage

## S3 method for class 'lme'
apa_print(x, conf.int = 0.95, in_paren = FALSE, est_name = NULL, ...)

## S3 method for class 'anova.lme'
apa_print(x, in_paren = FALSE, ...)

Arguments

Value

apa_print()-methods return a named list of class apa_results containing the following elements:

Column names in apa_results_table are standardized following the broom glossary (e.g., term, estimate conf.int, statistic, df, df.residual, p.value). Additionally, each column is labelled (e.g., $\hat{\eta}^2_G$ or $t$) using the tinylabels package and these labels are used as column names when an apa_results_table is passed to apa_table().

See Also

Other apa_print: apa_print(), apa_print.BFBayesFactor(), apa_print.aov(), apa_print.emmGrid(), apa_print.glht(), apa_print.htest(), apa_print.list(), apa_print.lm(), apa_print.merMod()

Examples

  library(nlme)
  fm1 <- lme(distance ~ age, data = Orthodont, method = "ML") # random is ~ age
  apa_print(fm1, conf.int = .9)
  # ANOVA-like tables
  single_anova <- anova(fm1)
  apa_print(single_anova)

Typeset Statistical Results from Hierarchical GLM

Description

These methods take objects from various R functions that calculate hierarchical (generalized) linear models to create formatted character strings to report the results in accordance with APA manuscript guidelines.

Usage

## S3 method for class 'merMod'
apa_print(
  x,
  effects = "fixed",
  conf.int = 0.95,
  in_paren = FALSE,
  est_name = NULL,
  ...
)

## S3 method for class 'mixed'
apa_print(x, ...)

Arguments

Details

Confidence intervals are calculated by calling lme4::confint.merMod(). By default, Wald confidence intervals are calculated, but this may change in the future.

Value

apa_print()-methods return a named list of class apa_results containing the following elements:

Column names in apa_results_table are standardized following the broom glossary (e.g., term, estimate conf.int, statistic, df, df.residual, p.value). Additionally, each column is labelled (e.g., $\hat{\eta}^2_G$ or $t$) using the tinylabels package and these labels are used as column names when an apa_results_table is passed to apa_table().

See Also

Other apa_print: apa_print(), apa_print.BFBayesFactor(), apa_print.aov(), apa_print.emmGrid(), apa_print.glht(), apa_print.htest(), apa_print.list(), apa_print.lm(), apa_print.lme()

Examples

  # Fit a linear mixed model using the lme4 package
  # or the lmerTest package (if dfs and p values are desired)
  library(lmerTest)
  fm1 <- lmer(Reaction ~ Days + (Days | Subject), sleepstudy)
  # Format statistics for fixed-effects terms (the default)
  apa_print(fm1)

Typeset Within-Subjects Confidence Intervals

Description

This method takes an output object from wsci and creates a table and character strings to report means and within-subjects confidence intervals in a table or in text.

Usage

## S3 method for class 'papaja_wsci'
apa_print(x, ...)

Arguments

Value

apa_print()-methods return a named list of class apa_results containing the following elements:

Column names in apa_results_table are standardized following the broom glossary (e.g., term, estimate conf.int, statistic, df, df.residual, p.value). Additionally, each column is labelled (e.g., $\hat{\eta}^2_G$ or $t$) using the tinylabels package and these labels are used as column names when an apa_results_table is passed to apa_table().

Prepare Table for Printing and Reporting

Description

Formats matrices and data frames to report them as tables in R Markdown documents according to APA guidelines.

Usage

apa_table(x, ...)

## Default S3 method:
apa_table(x, ...)

## S3 method for class 'apa_results_table'
apa_table(x, escape = FALSE, ...)

## S3 method for class 'apa_results'
apa_table(x, ...)

## S3 method for class 'matrix'
apa_table(
  x,
  caption = NULL,
  note = NULL,
  stub_indents = NULL,
  added_stub_head = NULL,
  col_spanners = NULL,
  midrules = NULL,
  placement = "tbp",
  landscape = FALSE,
  font_size = NULL,
  escape = TRUE,
  span_text_columns = TRUE,
  ...,
  format.args = NULL
)

## S3 method for class 'list'
apa_table(
  x,
  caption = NULL,
  note = NULL,
  stub_indents = NULL,
  added_stub_head = NULL,
  col_spanners = NULL,
  midrules = NULL,
  placement = "tbp",
  landscape = FALSE,
  font_size = NULL,
  escape = TRUE,
  merge_method = "indent",
  span_text_columns = TRUE,
  ...,
  format.args = NULL
)

## S3 method for class 'data.frame'
apa_table(
  x,
  caption = NULL,
  note = NULL,
  stub_indents = NULL,
  added_stub_head = NULL,
  col_spanners = NULL,
  midrules = NULL,
  placement = "tbp",
  landscape = FALSE,
  font_size = NULL,
  escape = TRUE,
  span_text_columns = TRUE,
  ...,
  format.args = NULL
)

Arguments

Details

When using apa_table, the type of the output (LaTeX or Word) is determined automatically by the rendered document type. In interactive R session the output defaults to LaTeX.

If x is a list, all list elements are merged by columns into a single table and the names of list elements are added according to the setting of merge_method.

By default, the width of the table is set to accommodate its contents. In some cases, this may cause the table to exceed the page width. To address this, tables can be rotated 90 degrees by setting langscape = TRUE or, by explicitly using "paragraph columns" with fixed column widths, such that the contents is automatically broken into multiple lines. For example, set align = "lm{5cm}l" to limit the second column to a width of 5 cm. Similarly, to space columns equally use align = paste0("m{", 1/(ncol(x) + 1), "\\linewidth}")

Note that placement options are not supported in appendices of apa6 documents and will be printed to the document. To omit the printed options set placement = NULL.

Value

A character vector of the table source code of class knit_asis, see knitr::asis_output().

See Also

knitr::kable(), apa_num()

Examples

my_table <- t(apply(cars, 2, function(x) # Create data
  round(c(Mean = mean(x), SD = sd(x), Min = min(x), Max = max(x)), 2)
))

apa_table(
  my_table
  , align = c("l", rep("r", 3))
  , caption = "A summary table of the cars dataset."
)

apa_table(
  cbind(my_table, my_table)
  , align = c("l", rep("r", 8))
  , caption = "A summary table of the cars dataset."
  , note = "This table was created using apa\\_table()"
  , added_stub_head = "Variables"
  , col_spanners = list(`Cars 1` = c(2, 5), `Cars 2` = c(6, 9))
)

apa_table(
  list(`Cars 1` = my_table, `Cars 2` = my_table)
  , caption = "A summary table of the cars dataset."
  , added_stub_head = "Variables"
)

Violin Plots for Factorial Designs that Conform to APA Guidelines

Description

Creates one or more violin plots from a data.frame containing data from a factorial design and sets APA-friendly defaults.

Usage

apa_violinplot(data, ...)

## Default S3 method:
apa_violinplot(
  data,
  id,
  factors = NULL,
  dv,
  tendency = mean,
  dispersion = conf_int,
  level = 0.95,
  fun_aggregate = mean,
  na.rm = TRUE,
  use = "all.obs",
  intercept = NULL,
  args_x_axis = NULL,
  args_y_axis = NULL,
  args_title = NULL,
  args_points = NULL,
  args_lines = NULL,
  args_error_bars = NULL,
  args_legend = NULL,
  jit = 0.3,
  xlab = NULL,
  ylab = NULL,
  main = NULL,
  ...
)

## S3 method for class 'afex_aov'
apa_violinplot(
  data,
  tendency = mean,
  dispersion = conf_int,
  fun_aggregate = mean,
  ...
)

Arguments

Details

The measure of dispersion can be either conf_int() for between-subjects confidence intervals, se() for standard errors, or any other standard function. For within-subjects confidence intervals, specify wsci() or within_subjects_conf_int().

If between- or within-subjects confidence intervals are requested, you can also specify the area of the cumulative distribution function that will be covered. For instance, if you want a 98% confidence interval, specify level = 0.98. The default is level = 0.95 for 95% confidence intervals.

Customization of plot elements

apa_factorial_plot() and its descendants apa_barplot(), apa_lineplot(), apa_beeplot(), and apa_violinplot() are wrapper functions that sequentially call:

• plot.new(),

• plot.window(),

• axis() (once for x axis, once for y axis),

• title() for axis labels and titles,

• rect() for bars in bar plots,

• points() for bee swarms,

• density() and polygon() for violins,

• lines() for lines connecting central tendency points,

• arrows() for error bars,

• points() for tendency points,

• legend() for a legend, and

• lines() for intercepts.

These calls can be customized by setting the respective parameters ⁠args_*** = list(...)⁠.

Value

A named (nested) list of plot options including raw and derived data. Note that the structure of the return value is about to change in a forthcoming release of papaja.

See Also

Other plots for factorial designs: apa_barplot(), apa_beeplot(), apa_factorial_plot(), apa_lineplot()

Examples

apa_violinplot(
   data = npk
   , id = "block"
   , dv = "yield"
   , factors = c("N")
)

apa_violinplot(
  data = npk
  , id = "block"
  , dv = "yield"
  , factors = c("N", "P")
  , args_legend = list(x = "center")
  , jit = 0.1
)

Create Variance Table from Various ANOVA objects

Description

These methods take objects from various R functions that calculate ANOVA to create a data.frame containing a variance table. This function is not exported and will most likely be deprecated, soon.

Usage

arrange_anova(x, ...)

## S3 method for class 'anova'
arrange_anova(x, ...)

## S3 method for class 'summary.aov'
arrange_anova(x, ...)

## S3 method for class 'summary.Anova.mlm'
arrange_anova(x, correction = "GG", ...)

Arguments

Details

The returned data.frame can be passed to functions such as print_anova().

Currently, methods for the following objects are available:

• summary.aov

• summary.aovlist

• Anova.mlm

Value

data.frame of class apa_variance_table or apa_model_comp.

See Also

print_anova(), print_model_comp()

Create a Regression Table (defunct)

Description

These methods take glm or lm objects to create a data frame containing a regression table. This function has been defunct. It is no longer needed.

Usage

arrange_regression(x, est_name, standardized, conf.int, ...)

Arguments

Value

data.frame of class apa_regression_table.

Beautify a Canonical Table

Description

Internal function that takes an object created by canonize() and applies proper rounding. Term names are beautified by removing parentheses and replacing colons with "$\\times$". Moreover, both rows and columns are sorted.

Usage

beautify(x, standardized = FALSE, use_math = FALSE, args_stat = NULL, ...)

Arguments

Prettify Term Names

Description

Remove parentheses, replace colons with $\times$. Useful to prettify term names in apa_print() tables.

Usage

beautify_terms(x, ...)

## S3 method for class 'character'
beautify_terms(x, standardized = FALSE, retain_period = FALSE, ...)

## S3 method for class 'numeric'
beautify_terms(x, standardized = FALSE, ...)

## S3 method for class 'factor'
beautify_terms(x, standardized = FALSE, ...)

## S3 method for class 'data.frame'
beautify_terms(x, ...)

Arguments

Value

A character vector or data.frame (if x is a data.frame) containing term names modified for nicer printing.

Examples

beautify_terms("a:b")
beautify_terms("scale(x)", standardized = TRUE)
beautify_terms("snake_case")

Brighten up a Color

Description

Brighten up a specified color (e.g., the swarm color in apa_beeplot()). This function is not exported.

Usage

brighten(col, factor)

Arguments

Value

A character vector as returned by rgb().

Transform to a Canonical Table

Description

Internal function that puts a data frame into a canonical structure by renaming and labelling columns.

Usage

canonize(x, stat_label = NULL, est_label = NULL, interval_type = "CI")

Arguments

Cite R and R Packages

Description

Creates character strings to cite R and R packages.

Usage

cite_r(
  file = NULL,
  prefix = "R-",
  footnote = FALSE,
  pkgs = NULL,
  omit = TRUE,
  lang = NULL,
  ...
)

Arguments

Details

If footnote = FALSE, a character string citing R and R packages including version numbers is returned. Otherwise a named list with the elements r and pkgs is returned. The former element holds a character string citing R and a reference to a footnote; the latter element contains a character string that creates the footnote. For correct rendering, the footnote string needs to be a separate paragraph in the R Markdown document.

Value

If footnote = FALSE a character string is returned, otherwise a named list with the elements r and pkgs.

See Also

r_refs(), knitr::write_bib()

Examples

cite_r()

Combine to Expression

Description

We use this internal function to generate expressions that can be used for plotting. Accepts a list of elements that are coerced, currently supported elements are character, expression, and character that contain latex elements. This function is not exported.

Usage

combine_plotmath(x)

Arguments

Value

An expression

Remove Incomplete Observations from Data Frame

Description

This is an internal function that is used to remove incomplete observations from a data.frame. It removes (1) explicit NAs and (2) cases with implicit NAs, i.e. participants who did not provide observations for all combinations of (possibly multiple) within-subjects factors.

Usage

complete_observations(data, id, within, dv)

Arguments

Value

A data.frame where NAs and incomplete observations are removed. It also has up to two additional attributes removed_cases_explicit_NA and removed_cases_implicit_NA, carrying the subject identifiers of participants whose data has been removed.

Between-Subjects Confidence Intervals

Description

Calculates the deviation that is needed to construct confidence intervals for a vector of observations.

Usage

conf_int(x, level = 0.95, na.rm = TRUE)

conf.int(x, level = 0.95, na.rm = TRUE)

ci(x, level = 0.95, na.rm = TRUE)

Arguments

Value

Returns a single numeric value, the deviation of the symmetric confidence bounds from the mean based on the t distribution.

Corresponding-Author Line

Description

Internal function. Construct corresponding-author line.

Usage

corresponding_author_line(x)

Arguments

Set Default Variable Labels from Column Names

Description

This internal function creates variable labels from the column names of a1 data frame.

Usage

default_label(x, ...)

## Default S3 method:
default_label(x, ...)

## S3 method for class 'data.frame'
default_label(x, ...)

Arguments

Value

Returns a data.frame with labelled columns. Labels are preserved (if already specified), otherwise generated from column names.

Set Defaults

Description

A helper function that is intended for internal use. A list ellipsis may be manipulated by overwriting (via set) or adding (via set.if.null) list elements.

Usage

defaults(ellipsis, set = NULL, set.if.null = NULL)

Arguments

Escape Symbols for LaTeX Output

Description

This function is a copy of the non-exported function escape_latex() from the knitr package. This function is not exported.

Usage

escape_latex(x, newlines = FALSE, spaces = FALSE)

Arguments

Aggregate data much faster using dplyr

Description

This is a convenience wrapper for aggregating your data using dplyr functions that tend to be much faster than the usual stats::aggregate() command. It is also easy to call from within a function. This function is not exported.

Usage

fast_aggregate(data, factors, dv, fun, na.rm = TRUE)

Arguments

Fetch a .bib-reference file from the web (defunct)

Description

Downloads and saves a .bib-reference file form the web, so it can be used to cite references in a Markdown-document using pandoc or LaTeX. This function has been defunct. Please use download from the downloader instead.

Usage

fetch_web_refs(x, bib_name)

Arguments

Details

If the function is called in an RMarkdown-document the file name specified as bib_name can be used in the YAML header as bibliography.

Value

Returns NULL invisibly.

See Also

cite_r(), r_refs(), knitr::write_bib()

Save a collection from a Zotero-Account to a BibTeX-file (defunct)

Description

Downloads and saves a Zotero reference library (or a subset) and saves it as BibTeX file. This function has been defunct. Use ReadZotero() from the RefManageR package instead.

Usage

fetch_zotero_refs(
  x,
  bib_name,
  API_key = NULL,
  collection = NULL,
  lib_type = "user"
)

Arguments

Details

This function retrieves references through the Zotero web API. x takes a Zotero user or group ID that can be retrieved from the Zotero.org user or group Feeds/API settings. An authentication key (API_key) is required to access nonpublic Zotero libraries. Authentication keys can also be generated in the Zotero.org user or group Feeds/API settings.

If the requested reference collection is larger than 100 records, multiple API calls are initiated because the number of retrieved records is limited to 100 per API call. Frequent API calls will result in a temporary access block. Thus, there is an (currently unknown) upper limit to the length of reference collections that can be retrieved through this function. It is generally recommended to comment out calls to this function in R Markdown documents during periods of frequent knitting to limit the number of API calls and limit the number of references to those needed for the current document by setting up collections in your Zotero library.

Collection keys (collection), i.e. identifiers of reference library subsets, can be retrieved by accessing them via a web browser. They keys are contained in the URL:

⁠https://www.zotero.org/<USERNAME>/items/collectionKey/<COLLECTIONKEY>⁠

Zotero web API calls can be slow, especially for large reference collections. If available, this function will use the downloader-package, which speeds up reference downloads considerably.

Value

Returns bib_name invisibly.

Author(s)

Christoph Stahl, Frederik Aust

See Also

cite_r(), r_refs()

Format numeric table cells

Description

Format all numeric cells of a table using apa_num. This function is not exported.

Usage

format_cells(x, format.args = NULL)

Arguments

See Also

apa_num()

generate_author_yml

Description

This function helps organize YAML author and affiliation fields such that authorship order can be changed without having to also update the order of affiliations.

Usage

generate_author_yml(
  researchers,
  affiliations,
  corres_name,
  corres_address,
  corres_email
)

Arguments

Examples

library(papaja)

generate_author_yml (
 researchers = list(
  "Emma J. Citizen" = c("example_hospital", "example_college"),
  "John H. Smith" = "example_college",
  "Kate C. Jones" = "example_hospital"
   ),
 affiliations = list(
   "example_hospital" = "Southern Example Hospital, NSW, Australia",
   "example_college" = "New Example College, VIC, Australia"
   ),
 corres_name = "Emma J. Citizen",
 corres_address = "123 Example Street, Epping, NSW 2121",
 corres_email = "jane@example.com"
)

Create a New apa_results Object

Description

Typeset the contents of an object according to the specified expression strings and create a new or extend an existing apa_results object.

Usage

glue_apa_results(x = NULL, term_names = NULL, ...)

add_glue_to_apa_results(
  ...,
  est_glue,
  stat_glue,
  container,
  sublist = NULL,
  term_names = NULL,
  in_paren = FALSE,
  est_first = TRUE,
  simplify = TRUE
)

Arguments

Value

Returns a list of class apa_results, see apa_print().

Examples

# Tidy and typeset output
iris_lm <- lm(Sepal.Length ~ Petal.Length + Petal.Width, iris)
tidy_iris_lm <- broom::tidy(iris_lm, conf.int = TRUE)
tidy_iris_lm$p.value <- apa_p(tidy_iris_lm$p.value)

glance_iris_lm <- broom::glance(iris_lm)
glance_iris_lm$p.value <- apa_p(glance_iris_lm$p.value, add_equals = TRUE)
glance_iris_lm$df <- apa_num(as.integer(glance_iris_lm$df))
glance_iris_lm$df.residual <- apa_num(as.integer(glance_iris_lm$df.residual))

# Create `apa_results`-list
lm_results <- glue_apa_results(
    x = tidy_iris_lm
    , df = glance_iris_lm$df.residual
    , est_glue = "$b = <<estimate>>, 95% CI $[<<conf.low>>,~<<conf.high>>]$"
    , stat_glue = "$t(<<df>>) = <<statistic>>$, $p <<p.value>>$"
    , term_names = make.names(names(coef(iris_lm)))
)

# Add modelfit information
add_glue_to_apa_results(
    .x = glance_iris_lm
    , container = lm_results
    , sublist = "modelfit"
    , est_glue = c(
        r2 = "$R^2 = <<r.squared>>$"
        , aic = ""
    )
    , stat_glue = c(
        r2 = "$F(<<df>>, <<df.residual>>) = <<statistic>>$, $p <<add_equals(p.value)>>$"
        , aic = "$\\mathrm{AIC} = <<AIC>>$"
    )
)

Highest-Density Intervals

Description

Calculates the highest-density interval of a vector of values.

Usage

hd_int(x, level = 0.95)

Arguments

Replace Parentheses with Brackets

Description

Takes a single character or a list of characters and replaces parentheses with brackets. Can be used to prepare a string of statistics (e.g. containing degrees of freedom) for reporting within parentheses.

Usage

in_paren(x)

Arguments

Value

An object of the same type as x, where all parentheses have been replaced by brackets.

See Also

apa_print()

Examples

t_stat <- t.test(extra ~ group, data = sleep)
t_test_res <- apa_print(t_stat)
in_paren(t_test_res$stat)
in_paren(t_test_res[1:3])

Add stub indentation

Description

Indents stubs by line and adds section headings This function is not exported.

Usage

indent_stubs(x, lines, filler = "   ")

Arguments

See Also

apa_table()

Create Empty Container for Results

Description

Creates the default empty container for the results of apa_print(). This function is not exported.

Usage

init_apa_results()

Value

A named list (with additional class apa_results) containing the following components:

estimate

A (named list of) character strings giving effect-size estimates.

statistic

A (named list of) character strings giving test statistic, parameters, and p values.

full_result

A (named list of) character strings comprised of estimate and statistic for each factor.

table

A data frame containing all results; can, for example, be passed to apa_table().

Matrix Method for lines()

Description

Internal function for convenient plotting of multiple lines. This function is not exported.

Usage

## S3 method for class 'matrix'
lines(x, y, type = "l", ...)

Lookup Table for Generated Words and Phrases

Description

Some words and phrases used throughout a papaja manuscript are automatically generated and need to vary when the locale of a document is changed. This function returns the words and phrases by language.

Usage

localize(x)

Arguments

Lookup Tables for Column Names and Variable Labels

Description

apa_print() converts many statistical output objects to output objects that contain an apa_results_table/data.frame with standardized column names and variable labels. For this purpose, it relies on the lookup tables provided here.

apa_print() converts many statistical output objects that include inferential statistics adjusted for multiple comparisons. To make these adjustments transparent the statistics get an index with the corresponding name. This function returns the proper names for these indices.

Usage

lookup_names

lookup_labels

lookup_adjust_names(x)

Format

An object of class character of length 116.

An object of class character of length 110.

Merge tables in list

Description

Takes a list of containing one or more matrix or data.frame and merges them into a single table. This function is not exported and currently unused.

Usage

merge_tables(x, empty_cells, row_names, added_stub_head)

Arguments

See Also

apa_table()

Package Available

Description

Internal function to check if a specified package is installed.

Usage

package_available(x)

Arguments

Value

Logical. Is the specified package installed?

Simple language names from BCP 47 tags

Description

Internal function to translate BCP 47 tags to simple language names.

Usage

parse_bcp47(x)

Arguments

Value

Character. Simple language name.

Matrix Method for points()

Description

Internal function for convenient plotting of multiple points. This function is not exported.

Usage

## S3 method for class 'matrix'
points(x, y, type = "p", ...)

Format statistics from ANOVA (APA 6th edition)

Description

This function is the former internal workhorse of the apa_print-family for ANOVA. It takes a data.frame of class apa_variance_table and produces strings to report the results in accordance with APA manuscript guidelines. It is already deprecated and will soon be defunct. This function is not exported.

Usage

print_anova(
  x,
  intercept = FALSE,
  observed = NULL,
  es = "ges",
  mse = getOption("papaja.mse"),
  in_paren = FALSE
)

Arguments

Value

A named list containing the following components:

statistic

A named list of character strings giving the test statistic, parameters, and p value for each factor.

estimate

A named list of character strings giving the effect size estimates for each factor.

% , either in units of the analyzed scale or as standardized effect size.

full_result

A named list of character strings comprised of estimate and statistic for each factor.

table

A data.frame containing the complete ANOVA table, which can be passed to apa_table.

See Also

arrange_anova(), apa_print.aov()

Typeset Statistical Results from Model Comparisons

Description

This function is the workhorse of the apa_print() method for model comparisons. It takes a data frame of class apa_model_comp and produces strings to report the results in accordance with APA manuscript guidelines. This function is not exported.

Usage

print_model_comp(
  x,
  models = NULL,
  conf.int = NULL,
  boot_samples = 1000,
  progress_bar = FALSE,
  in_paren = FALSE,
  observed = TRUE
)

Arguments

See Also

arrange_anova(), apa_print.aov()

Typeset scientific notation

Description

Typesets scientific notation of numbers into properly typeset math strings.

Usage

print_scientific(x)

Arguments

Quote from TeX document

Description

Includes a labelled quote from a LaTeX document 'asis'.

Usage

quote_from_tex(
  x,
  file = paste0(rmarkdown::metadata[["manuscript-tex"]], ".tex")
)

Arguments

Details

Searches the LaTeX document specified in file for labelled quotes, i.e. paragraphs that are enclosed in ⁠% <@~{#quote-label}⁠ and ⁠% ~@>⁠ tags in LaTeX comments on separate lines. The labelled quote is then inserted and rendered asis. To use labelled quote-tags in a apa6_pdf()-document, set the YAML front matter options quote_labels: true.

Value

A character vector of LaTeX document text of class knit_asis, see knitr::asis_output().

Create a Reference File for R and R Packages

Description

Creates a .bib-reference file for the installed R version and R-packages, so they can be cited in an R Markdown-document.

Usage

r_refs(
  file,
  append = TRUE,
  prefix = "R-",
  type_pref = c("Article", "Book"),
  tweak = TRUE
)

create_bib(
  x,
  file,
  append = TRUE,
  prefix = "R-",
  type_pref = c("Article", "Book"),
  tweak = TRUE
)

Arguments

Details

r_refs is a wrapper for create_bib to create a bibliography for R and all attached or cached packages.

By default, if a file exists at the specified location, r_refs reads the file and appends missing citation information to the end of the file (create_bib always overwrites existing files). It is recommended to use a bibliography-file dedicated to R-references.

Beware that chunks loading packages should generally not be cached. r_refs will make all packages loaded in cached chunks citable, but it won't know when you remove a package from a cached chunk. This can result in unused package references in your bibliography-file that will be cited when using cite_r.

If a package provides citation information in a CITATION file, a reference is selected based on the preferred order of reference types specified in type_pref. By default, available articles are cited rather than books. If no reference of the specified types is available, the first reference is used. If multiple references of the preferred type are given all of them are cited. Finally, if no CITATION file exists a reference is generated from the DESCRIPTION file by citation.

Value

Invisibly returns the bibliography written to file.

See Also

cite_r(), knitr::write_bib(), utils::citation(), utils::toLatex()

Remove Comments

Description

Removes markdown comments from an R Markdown file.

Usage

remove_comments(x, file)

Arguments

Value

No return value, called to write text to file.

Render Appendix (defunct)

Description

This function renders an R Markdown document without YAML header to a TeX fragment inside an appendix environment, or to a markdown fragment (for Word output). This function has been defunct. Please use the appendix syntax provided by bookdown (see the bookdown manual).

Usage

render_appendix(
  x,
  bibliography = rmarkdown::metadata$bibliography,
  csl = rmarkdown::metadata$csl,
  quiet = TRUE,
  ...
)

Arguments

Details

This function is only exported for backwards compatibility. It is now recommended not to call render_appendix() directly. Instead, to add appendices to your manuscript, add the R Markdown file to the YAML front matter by using appendix: "appendix.Rmd".

Default chunk options and hooks are set to those used in the R Markdown document from which render_appendix is called; otherwise defaults of md_document are used.

By default, x is converted to a TeX file, which can be included in an R Markdown document as include:

  output:
    pdf_document:
      include:
        after_body: appendix.tex
  

If render_appendix is called form an R Markdown document with a target document type other than a PDF file, a markdown fragment is included.

Value

Returns NULL invisibly.

Revision Letter

Description

Template for creating a journal revision letters.

Usage

revision_letter_pdf(...)

Arguments

Details

This document format is adapted from by the revision letter template by Martin Schrön.

It is possible to reference sections, figures, or tables in the revised manuscript, either by their number or by page. To do so, specify a path to the revised manuscript (omitting the file extension) in the YAML front matter (i.e., manuscript-tex: file_name) and ensure that you retain the aux file when rendering the revised manuscript. To do so, set the following option in a code chunk of the revised manuscript: options(tinytex.clean = FALSE). To reference section, figure, or table numbers it is possible to use LaTeX (i.e., ⁠\ref{label}⁠) or bookdown cross-referencing syntax (i.e., ⁠\@ref(label)⁠). To reference the corresponding page numbers you must use the LaTeX syntax (i.e., ⁠\pageref{label}⁠).

To quote entire paragraphs directly from the revised manuscript see quote_from_tex().

Value

R Markdown output format to pass to rmarkdown::render().

See Also

bookdown::pdf_document2()], rmarkdown::pdf_document()

Sanitize Term Names

Description

Remove characters from term names that will be difficult to address using the $-operator. This function is not exported.

Usage

sanitize_terms(x, standardized = FALSE)

## S3 method for class 'character'
sanitize_terms(x, standardized = FALSE)

## S3 method for class 'factor'
sanitize_terms(x, standardized = FALSE)

## S3 method for class 'data.frame'
sanitize_terms(x, standardized = FALSE)

## S3 method for class 'list'
sanitize_terms(x, standardized = FALSE)

Arguments

Value

An object of the same class as x containing sanitized term names as characters.

Examples

  sanitize_terms(c("(Intercept)", "Factor A", "Factor B", "Factor A:Factor B", "scale(FactorA)"))

Standard Error of the Mean

Description

Calculates the standard error of the mean.

Usage

se(x, na.rm = TRUE)

Arguments

Value

The standard error of the mean as numeric vector of length 1.

Select Parameters

Description

If a list holds vectors of parameter values, this function extracts the i-th parameter value from each vector and creates a new list with these values. Especially helpful if a function is called repeatedly via do.call with different parameter values from within a function.

Usage

sel(x, i)

Arguments

Simple Codebook

Description

Generate a simple codebook in CSV-format from a (labelled) data.frame.

Usage

simple_codebook(x, ...)

Arguments

Details

If the skimr package is installed, an in-line histogram is added for all numeric variables. If columns are labelled, the labelles are included in the codebook.

Value

Returns NULL invisibly.

See Also

utils::write.csv()

Examples

variable_labels(cars) <- c(speed = "Speed [ft/s]", dist = "Distance traveled [m]")
simple_codebook(cars, file = file.path(tempdir(), "cars_codebook.csv"))

Sort the Columns of an APA Results Table

Description

An internal function that sorts the columns of a data.frame according to our standards.

Usage

sort_columns(x)

Arguments

Sort ANOVA or Regression Table by Predictors/Effects

Description

Sort rows in ANOVA or regression tables produced by apa_print() by complexity (i.e., main effects, two-way interactions, three-way interactions, etc.).

Usage

sort_terms(x, colname)

Arguments

Value

Returns the same data.frame with reordered rows.

Examples

## From Venables and Ripley (2002) p. 165.
npk_aov <- aov(yield ~ block + N * P * K, npk)
npk_aov_results <- apa_print(npk_aov)
sort_terms(npk_aov_results$table, "term")

Summarize Within-Subjects Confidence Intervals

Description

Calculate upper and lower limits of within-subjects confidence intervals calculated with wsci() and return them along their respective means.

Usage

## S3 method for class 'papaja_wsci'
summary(object, ...)

Arguments

Value

A data.frame containing means as well as lower and upper confidence bounds for each cell of the design.

Strip Math Tags from Variable Labels or Strings

Description

Internal function to strip math tags from variable labels or strings. svl() returns the stripped variable label of x, if available. strip_math_tags returns the stripped character x.

Usage

svl(x, use_math = FALSE)

strip_math_tags(x)

Arguments

APA-style ggplot2 Theme

Description

ggplot2 theme with a white panel background, no grid lines, large axis and legend titles, and increased text padding for better readability.

Usage

theme_apa(base_size = 12, base_family = "", box = FALSE)

Arguments

Value

Object of class theme and gg, see ggplot2::theme().

See Also

ggplot2::theme_bw(), ggplot2::theme()

Examples

 
   # Copied from ?ggtheme
   mtcars2 <- within(mtcars, {
   vs <- factor(vs, labels = c("V-shaped", "Straight"))
   am <- factor(am, labels = c("Automatic", "Manual"))
   cyl  <- factor(cyl)
   gear <- factor(gear)
   })

   library("ggplot2")
   p1 <- ggplot(mtcars2) +
     geom_point(aes(x = wt, y = mpg, colour = gear)) +
     labs(
       title = "Fuel economy declines as weight increases",
       subtitle = "(1973-1974)",
       x = "Weight (1000 lbs)",
       y = "Fuel economy (mpg)",
       colour = "Gears"
     )

   p1
   p1 + theme_apa()
 

Transmute Degrees-of-Freedom Columns into Variable Labels

Description

Takes the output from apa_print() methods and modifies the results table by transmuting information about degrees of freedom into the variable labels of test-statistic columns.

Usage

transmute_df_into_label(x, check_df = TRUE, ...)

df_into_label(x, check_df = TRUE, ...)

## S3 method for class 'apa_results'
transmute_df_into_label(x, check_df = TRUE, ...)

## S3 method for class 'apa_results_table'
transmute_df_into_label(x, check_df = TRUE, ...)

Arguments

Value

An object of the same class as x, where a redundant column with degrees of freedom has been incorporated into the column label of the column statistic.

Examples

  apa_out <- apa_print(aov(yield ~ N * P, npk))

  # Standard output with separate columns for degrees of freedom:
  apa_out$table

  # Modified output where degrees of freedom are incorporated into the variable
  # label of column 'statistic':
  transmute_df_into_label(apa_out)$table

Validate Function Input

Description

This function can be used to validate the input to functions. This function is not exported.

Usage

validate(
  x,
  name = NULL,
  check_class = NULL,
  check_mode = NULL,
  check_integer = FALSE,
  check_NA = TRUE,
  check_infinite = TRUE,
  check_length = NULL,
  check_dim = NULL,
  check_range = NULL,
  check_cols = NULL
)

Arguments

Create title page

Description

Creates text for the title and abstract page for MS Word documents. This function is not exported.

Usage

word_title_page(x)

Arguments

See Also

apa6_docx()

Within-Subjects Confidence Intervals

Description

Calculate Cousineau-Morey within-subjects confidence intervals.

Usage

wsci(data, id, factors, dv, level = 0.95, method = "Morey")

within_subjects_conf_int(data, id, factors, dv, level = 0.95, method = "Morey")

Arguments

Value

A data.frame with additional class papaja_wsci. The summary() method for this class returns a data.frame with means along lower and upper limit for each cell of the design.

References

Morey, R. D. (2008). Confidence Intervals from Normalized Data: A correction to Cousineau (2005). Tutorials in Quantitative Methods for Psychology, 4(2), 61–64.

Cousineau, D. (2005). Confidence intervals in within-subjects designs: A simpler solution to Loftus and Masson's method. Tutorials in Quantitative Methods for Psychology, 1(1), 42–45.

Examples

wsci(
   data = npk
   , id = "block"
   , dv = "yield"
   , factors = c("N", "P")
)