Package 'BFF'

Title: Bayes Factor Functions
Description: Bayes factors represent the ratio of probabilities assigned to data by competing scientific hypotheses. However, one drawback of Bayes factors is their dependence on prior specifications that define null and alternative hypotheses. Additionally, there are challenges in their computation. To address these issues, we define Bayes factor functions (BFFs) directly from common test statistics. BFFs express Bayes factors as a function of the prior densities used to define the alternative hypotheses. These prior densities are centered on standardized effects, which serve as indices for the BFF. Therefore, BFFs offer a summary of evidence in favor of alternative hypotheses that correspond to a range of scientifically interesting effect sizes. Such summaries remove the need for arbitrary thresholds to determine "statistical significance." BFFs are available in closed form and can be easily computed from z, t, chi-squared, and F statistics. They depend on hyperparameters "r" and "tau^2", which determine the shape and scale of the prior distributions defining the alternative hypotheses. Plots of BFFs versus effect size provide informative summaries of hypothesis tests that can be easily aggregated across studies.
Authors: Rachael Shudde [aut, cre], František Bartoš [aut], Saptati Datta [aut], Riana Guha [aut], Sandy Pramanik [aut], Valen Johnson [aut]
Maintainer: Rachael Shudde <[email protected]>
License: GPL (>= 2)
Version: 4.3.0
Built: 2025-02-12 04:56:40 UTC
Source: https://github.com/rshudde/bff

Help Index

BFF Object

Description

The BFF object is a class that contains the results of a Bayes Factor Function. The BFF object contains the following fields:

BFF the object containing the log_bf (log Bayes factor values) and corresponding omega values
input the object containing the input values
log_bf_h1 maximized Bayes factor in favor of the alternative, or the corresponding Bayes factor if an omega is supplied
omega_h1 corresponding omega value for maximized Bayes factor in favor of the alternative, orthe corresponding omega for the Bayes factor if an omega is supplied
log_bf_h0 minimized Bayes factor in favor of the null (for medium or large effect sizes, only returned if a specific omega is not set)
omega_h0 corresponding omega value for minimized Bayes factor in favor of the null (for medium or large effect sizes, only returned if a specific omega is not set)
alternative alternative hypothesis used in calculations
omega_set was an omega value provided?
r r value (default is 1 if not provided by user)
test_type type of BFF test
generic_test FALSE

chi2_test_BFF

Description

chi2_test_BFF constructs BFFs based on the t test. BFFs depend on hyperparameters r and tau^2 which determine the shape and scale of the prior distributions which define the alternative hypotheses. By setting r > 1, we use higher-order moments for replicated studies. Fractional moments are set with r > 1 and r not an integer. All results are on the log scale.

Usage

chi2_test_BFF(
  chi2_stat,
  n,
  LRT = FALSE,
  omega = NULL,
  omega_sequence = if (is.null(omega)) seq(0.01, 1, by = 0.01),
  r = 1
)

Arguments

chi2_stat

chi-square statistic
n

sample size (if one sample test)
LRT

should LRT be performed? Default is FALSE
omega

standardized effect size. For the chi^2-test, this is often called Cohen's w (can be a single entry or a vector of values)
omega_sequence

sequence of standardized effect sizes. If no omega is provided, omega_sequence is set to be seq(0.01, 1, by = 0.01)
r

variable controlling dispersion of non-local priors. Default is 1.

Value

Returns an S3 object of class 'BFF' (see 'BFF.object' for details).

Examples

chi2BFF = chi2_test_BFF(chi2_stat = 6.5, n = 10)
chi2BFF
plot(chi2BFF)

f_test_BFF

Description

f_test_BFF constructs BFFs based on the t test. BFFs depend on hyperparameters r and tau^2 which determine the shape and scale of the prior distributions which define the alternative hypotheses. By setting r > 1, we use higher-order moments for replicated studies. Fractional moments are set with r > 1 and r not an integer. All results are on the log scale.

Usage

f_test_BFF(
  f_stat,
  n,
  df1,
  df2,
  omega = NULL,
  omega_sequence = if (is.null(omega)) seq(0.01, 1, by = 0.01),
  r = 1
)

Arguments

f_stat

T statistic
n

sample size (if one sample test)
df1

sample size of group one for two sample test.
df2

sample size of group two for two sample test
omega

standardized effect size. For the f-test, this is often called Cohen's f (can be a single entry or a vector of values)
omega_sequence

sequence of standardized effect sizes. If no omega is provided, omega_sequence is set to be seq(0.01, 1, by = 0.01)
r

variable controlling dispersion of non-local priors. Default is 1.

Value

Returns an S3 object of class 'BFF' (see 'BFF.object' for details).

Examples

fBFF = f_test_BFF(f_stat = 1.5, n = 50, df1 = 25, df2 = 48)
fBFF
plot(fBFF)

Check whether x is a BFF object

Description

Check whether x is a BFF object

Usage

is.BFF(x)

Arguments

x

an object to test

Value

returns a boolean.

Non-local Normal Moment Distribution

Description

Non-local Normal Moment Distribution

Usage

dnlnm(x, tau2, r, log = FALSE)

Arguments

x

vector of quantiles.
tau2

the tau2 parameter
r

the r parameter
log

logical; if TRUE, probabilities p are given as log(p).

Value

dnlnm gives the density of non-local normal moment distribution

Plot Bayes Factor Function

Description

Creates a Bayes factor function plot of an BFF object. The BFF object needs to be specified with omega = NULL or .

Usage

## S3 method for class 'BFF'
plot(x, plot = TRUE, ...)

Arguments

x

a BFF object
plot

whether plot should be generated. Default to TRUE. If FALSE a data frame with the support, prior ordinates, and posterior ordinates is returned instead.
...

additional arguments to the plotting function. These include:

  • "title"tile of the figure

  • "xlab"x-axis label of the figure

  • "ylab"y-axis label of the figure

  • "add_segments"whether effect size segments should be added to the figure. Available only for standardized effect sizes. Defaults to TRUE

Value

either a ggplot2 object if plot = TRUE or a data.frame with a Bayes factor function if plot = FALSE

See Also

[z_test_BFF()], [t_test_BFF()], [chi2_test_BFF()], [f_test_BFF()]

Plot Prior and Posterior Distribution

Description

Creates a prior and posterior plot of an BFF object. If no specific omega was set when fitting the model, the omega resulting in maximum BF against the null hypothesis is selected.

Usage

posterior_plot(x, prior = FALSE, plot = TRUE, ...)

Arguments

x

a BFF object
prior

whether prior distribution should be added to the figure
plot

whether plot should be generated. Default to TRUE. If FALSE a data frame with the support, prior ordinates, and posterior ordinates is returned instead.
...

additional arguments to the plotting function. These include:

  • "x_limit"vector defining the plotting range, defaults to c(-3, 3).

  • "color"vector with color for the posterior and prior line. Defaults to c("black", "grey")

  • "linetype"vector with linetype for the posterior and prior line. Defaults to c(2, 1)

  • "linewidth"vector with linewidth for the posterior and prior line. Defaults to c(1, 1)

Value

either a ggplot2 object if plot = TRUE or a data.frame with prior and posterior densities if plot = FALSE

See Also

[z_test_BFF()], [t_test_BFF()], [chi2_test_BFF()], [f_test_BFF()]

Summarize BFF object

Description

Summarize BFF object

Usage

## S3 method for class 'BFF'
print(x, ...)

Arguments

x

a BFF object
...

additional arguments (unused)

Value

prints summary of a BFF object.

See Also

[z_test_BFF()], [t_test_BFF()], [chi2_test_BFF()], [f_test_BFF()]

regression_test_BFF

Description

regression_test_BFF constructs BFFs based on the t test. BFFs depend on hyperparameters r and tau^2 which determine the shape and scale of the prior distributions which define the alternative hypotheses. By setting r > 1, we use higher-order moments for replicated studies. Fractional moments are set with r > 1 and r not an integer. All results are on the log scale.

Usage

regression_test_BFF(
  t_stat,
  n = NULL,
  k = NULL,
  alternative = "two.sided",
  omega = NULL,
  omega_sequence = if (is.null(omega)) seq(0.01, 1, by = 0.01),
  r = 1
)

Arguments

t_stat

T statistic
n

sample size (if one sample test)
k

number of predictors
alternative

is the alternative a one.sided or two.sided test? default is two.sided
omega

standadized effect size. For the regression test, this is also known as Cohen's f^@ (can be a single entry or a vector of values)
omega_sequence

sequence of standardized effect sizes. If no omega is provided, omega_sequence is set to be seq(0.01, 1, by = 0.01)
r

variable controlling dispersion of non-local priors. Default is 1.

Value

Returns an S3 object of class 'BFF' (see 'BFF.object' for details).

Examples

regBFF = regression_test_BFF(t_stat = 1.5, n = 50, k = 3)
regBFF
plot(regBFF)

Summarize BFF object

Description

Summarize BFF object

Usage

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

Arguments

object

a BFF object
...

additional arguments (unused)

Value

prints summary of a BFF object.

See Also

[z_test_BFF()], [t_test_BFF()], [chi2_test_BFF()], [f_test_BFF()]

t_test_BFF

Description

t_test_BFF constructs BFFs based on the t test. BFFs depend on hyperparameters r and tau^2 which determine the shape and scale of the prior distributions which define the alternative hypotheses. By setting r > 1, we use higher-order moments for replicated studies. Fractional moments are set with r > 1 and r not an integer. All results are on the log scale.

Usage

t_test_BFF(
  t_stat,
  n = NULL,
  n1 = NULL,
  n2 = NULL,
  one_sample = FALSE,
  alternative = "two.sided",
  omega = NULL,
  omega_sequence = if (is.null(omega)) seq(0.01, 1, by = 0.01),
  r = 1
)

Arguments

t_stat

T statistic
n

sample size (if one sample test)
n1

sample size of group one for two sample test. Must be provided if one_sample = FALSE
n2

sample size of group two for two sample test. Must be provided if one_sample = FALSE
one_sample

is test one sided? Default is FALSE
alternative

the alternative. options are "two.sided" or "less" or "greater"
omega

standardized effect size. For the t-test, this is often called Cohen's d (can be a single entry or a vector of values)
omega_sequence

sequence of standardized effect sizes. If no omega is provided, omega_sequence is set to be seq(0.01, 1, by = 0.01)
r

variable controlling dispersion of non-local priors. Default is 1.

Value

Returns an S3 object of class 'BFF' (see 'BFF.object' for details).

Examples

tBFF = t_test_BFF(t_stat = 2.5, n = 50, one_sample = TRUE)
tBFF
plot(tBFF)

z_test_BFF

Description

z_test_BFF constructs BFFs based on the z test. BFFs depend on hyperparameters r and tau^2 which determine the shape and scale of the prior distributions which define the alternative hypotheses. By setting r > 1, we use higher-order moments for replicated studies. Fractional moments are set with r > 1 and r not an integer. All results are on the log scale.

Usage

z_test_BFF(
  z_stat,
  n = NULL,
  n1 = NULL,
  n2 = NULL,
  one_sample = FALSE,
  alternative = "two.sided",
  omega = NULL,
  omega_sequence = if (is.null(omega)) seq(0.01, 1, by = 0.01),
  r = 1
)

Arguments

z_stat

Z statistic
n

sample size (if one sample test)
n1

sample size of group one for two sample test. Must be provided if one_sample = FALSE
n2

sample size of group two for two sample test. Must be provided if one_sample = FALSE
one_sample

is test one sided? Default is FALSE
alternative

the alternative. options are "two.sided" or "less" or "greater"
omega

standardized effect size. For the z-test, this is often called Cohen's d (can be a single entry or a vector of values)
omega_sequence

sequence of standardized effect sizes. If no omega is provided, omega_sequence is set to be seq(0.01, 1, by = 0.01)
r

variable controlling dispersion of non-local priors. Default is 1.

Value

Returns an S3 object of class 'BFF' (see 'BFF.object' for details).

Examples

zBFF = z_test_BFF(z_stat = 2.5, n = 50, one_sample = TRUE)
zBFF
plot(zBFF)