apa_print.BFBayesFactor {papaja}

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

x

Output object. See details.

stat_name

Character. If NULL (the default), the name given in x is used for the test statistic, otherwise the supplied name is used. See details.

est_name

Character. If NULL (the default), the name given in x (or a formally correct adaptation) is used for the estimate, otherwise the supplied name is used. See details.

subscript

Character. Index used to specify the model comparison for the Bayes factors, e.g., "+0" yields BF_{+0}. If NULL default to "10".

escape_subscript

Logical. If TRUE special LaTeX characters, such as % or _, in subscript are escaped.

scientific_threshold

Numeric. Named vector of length 2 taking the form c(min = 1/10, max = 1e6). Bayes factors that exceed these thresholds will be printed in scientific notation.

reciprocal

Logical. If TRUE the reciprocal of all Bayes factors is taken before results are formatted. The advantage over specifying x = t(x) is that the default (only the default) index specifying the model comparison is automatically reversed, see subscript.

log

Logical. If TRUE the logarithm of the Bayes factor is reported.

mcmc_error

Logical. If TRUE estimation error of the Bayes factor(s) is reported.

iterations

Numeric. Number of iterations of the MCMC sampler to estimate HDIs from the posterior.

standardized

Logical. Whether to return standardized or unstandardized effect size estimates.

central_tendency

Function to calculate central tendency of MCMC samples to obtain a point estimate from the posterior.

interval

Function to calculate an interval estimate of MCMC samples from the posterior. The returned object must be either a named vector or matrix with (column) names giving the interval bounds (e.g., ⁠2.5%⁠ and ⁠97.5%⁠) or with an attribute conf.level (e.g., 0.95).

interval_type

Character. Used to specify the type of interval in the formatted text.

bf_r1

Numeric. Vector of the same length as x giving Bayes factors in favor of an order constraint relative to the unconstrained model (see details). Must be on log-scale if log = TRUE.

bf_1r

Numeric. Same as bf_r1 (see details).

...

Arguments passed on to apa_num.numeric

gt1

Logical. Indicates if the statistic can, in principle, have an absolute value greater than 1. If FALSE, leading zeros are omitted.

zero

Logical. Indicates if the statistic can, in principle, be 0. If FALSE, a string of the form ⁠< 0.001⁠ is returned instead of 0.

na_string

Character. String to print if any element of x is NA.

use_math

Logical. Indicates whether to use $ in the output so that Inf or scientific notation is rendered correctly.

add_equals

Logical. Indicates if the output string should be prepended with an =.

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:

estimate

One or more character strings giving point estimates, confidence intervals, and confidence level. A single string is returned in a vector; multiple strings are returned as a named list. If no estimate is available the element is NULL.

statistic

One or more character strings giving the test statistic, parameters (e.g., degrees of freedom), and p-value. A single string is returned in a vector; multiple strings are returned as a named list. If no estimate is available the element is NULL.

full_result

One or more character strings comprised 'estimate' and 'statistic'. A single string is returned in a vector; multiple strings are returned as a named list.

table

A data.frame of class apa_results_table that contains all elements of estimate and statistics. This table can be passed to apa_table() for reporting.

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.aov(), apa_print.emmGrid(), apa_print.glht(), apa_print.htest(), apa_print.list(), apa_print.lme(), apa_print.lm(), apa_print.merMod(), apa_print()

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