apa_print.BFBayesFactor: Typeset Bayes Factors

In papaja: Prepare American Psychological Association Journal Articles with R Markdown

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: \Sexpr[results=rd]{tools:::Rd_expr_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"
)

papaja documentation built on Sept. 29, 2023, 9:07 a.m.