Package 'bfpwr'

Title: Power and Sample Size Calculations for Bayes Factor Analysis
Description: Implements z-test, t-test, and normal moment prior Bayes factors based on summary statistics, along with functionality to perform corresponding power and sample size calculations as described in Pawel and Held (2024) <doi:10.48550/arXiv.2406.19940>.
Authors: Samuel Pawel [aut, cre]
Maintainer: Samuel Pawel <[email protected]>
License: GPL-3
Version: 0.1.3
Built: 2024-10-29 06:51:22 UTC
Source: CRAN

Help Index


z-test Bayes factor

Description

This function computes the Bayes factor that quantifies the evidence that the data (in the form of an asymptotically normally distributed parameter estimate with standard error) provide for a point null hypothesis with a normal prior assigned to the parameter under the alternative. The standard error is assumed to be known.

Usage

bf01(estimate, se, null = 0, pm, psd, log = FALSE)

Arguments

estimate

Parameter estimate

se

Standard error of the parameter estimate

null

Parameter value under the point null hypothesis. Defaults to 0

pm

Mean of the normal prior assigned to the parameter under the alternative

psd

Standard deviation of the normal prior assigned to the parameter under the alternative. Set to 0 to obtain a point prior at the prior mean

log

Logical indicating whether the natural logarithm of the Bayes factor should be returned. Defaults to FALSE

Value

Bayes factor in favor of the null hypothesis over the alternative (BF > 1 indicates evidence for the null hypothesis, whereas BF < 1 indicates evidence for the alternative)

Author(s)

Samuel Pawel

Examples

bf01(estimate = 0.2, se = 0.05, null = 0, pm = 0, psd = 2)

Sample size determination for z-test Bayes factor

Description

This function computes the required sample size to obtain a Bayes factor (bf01) more extreme than a threshold k with a specified target power.

Usage

nbf01(
  k,
  power,
  usd,
  null = 0,
  pm,
  psd,
  dpm = pm,
  dpsd = psd,
  nrange = c(1, 10^5),
  lower.tail = TRUE,
  integer = TRUE,
  analytical = TRUE,
  ...
)

Arguments

k

Bayes factor threshold

power

Target power

usd

Unit standard deviation, the standard error of the parameter estimate based on n=1\code{n}=1, see details

null

Parameter value under the point null hypothesis. Defaults to 0

pm

Mean of the normal prior assigned to the parameter under the alternative in the analysis

psd

Standard deviation of the normal prior assigned to the parameter under the alternative in the analysis. Set to 0 to obtain a point prior at the prior mean

dpm

Mean of the normal design prior assigned to the parameter. Defaults to the same value as the analysis prior pm

dpsd

Standard deviation of the normal design prior assigned to the parameter. Defaults to the same value as the analysis prior psd

nrange

Sample size search range over which numerical search is performed. Defaults to c(1, 10^5)

lower.tail

Logical indicating whether Pr(BF \leq k) (TRUE) or Pr(BF >> k) (FALSE) should be computed. Defaults to TRUE

integer

Logical indicating whether only integer valued sample sizes should be returned. If TRUE the required sample size is rounded to the next larger integer. Defaults to TRUE

analytical

Logical indicating whether analytical (if available) or numerical method should be used. Defaults to TRUE

...

Other arguments passed to stats::uniroot

Details

It is assumed that the standard error of the future parameter estimate is of the form se=usd/n\code{se} =\code{usd}/\sqrt{\code{n}}. For example, for normally distributed data with known standard deviation sd and two equally sized groups of size n, the standard error of an estimated standardized mean difference is se=sd2/n\code{se} = \code{sd}\sqrt{2/n}, so the corresponding unit standard deviation is usd=sd2\code{usd} = \code{sd}\sqrt{2}. See the vignette for more information.

Value

The required sample size to achieve the specified power

Note

A warning message will be displayed in case that the specified target power is not achievable under the specified analysis and design priors.

Author(s)

Samuel Pawel

See Also

pbf01, powerbf01, bf01

Examples

## point alternative (analytical and numerical solution available)
nbf01(k = 1/10, power = 0.9, usd = 1, null = 0, pm = 0.5, psd = 0,
      analytical = c(TRUE, FALSE), integer = FALSE)

## standardized mean difference (usd = sqrt(2), effective sample size = per group size)
nbf01(k = 1/10, power = 0.9, usd = sqrt(2), null = 0, pm = 0, psd = 1)
## this is the sample size per group (assuming equally sized groups)

## z-transformed correlation (usd = 1, effective sample size = n - 3)
nbf01(k = 1/10, power = 0.9, usd = 1, null = 0, pm = 0.2, psd = 0.5)
## have to add 3 to obtain the actual sample size

## log hazard/odds ratio (usd = 2, effective sample size = total number of events)
nbf01(k = 1/10, power = 0.9, usd = 2, null = 0, pm = 0, psd = sqrt(0.5))
## have to convert the number of events to a sample size

Normal moment prior Bayes factor

Description

This function computes the Bayes factor that quantifies the evidence that the data (in the form of an asymptotically normally distributed parameter estimate with standard error) provide for a point null hypothesis with a normal moment prior assigned to the parameter under the alternative.

Usage

nmbf01(estimate, se, null = 0, psd, log = FALSE)

Arguments

estimate

Parameter estimate

se

Standard error of the parameter estimate

null

Parameter value under the point null hypothesis. Defaults to 0

psd

Spread of the normal moment prior assigned to the parameter under the alternative. The modes of the prior are located at ±2psd\pm\sqrt{2}\,\code{psd}

log

Logical indicating whether the natural logarithm of the Bayes factor should be returned. Defaults to FALSE

Details

A normal moment prior has density f(xnull,psd)=N(xnull,psd2)×(xnull)/psd2f(x \mid \code{null}, \code{psd}) = N(x \mid \code{null}, \code{psd}^2) \times (x - \code{null})/ \code{psd}^2 with N(xm,v)N(x \mid m, v) the normal density with mean mm and variance vv evaluated at xx.

Value

Bayes factor in favor of the null hypothesis over the alternative (BF > 1 indicates evidence for the null hypothesis, whereas BF < 1 indicates evidence for the alternative)

Author(s)

Samuel Pawel

References

Johnson, V. E. and Rossell, D. (2010). On the use of non-local prior densities in Bayesian hypothesis tests. Journal of the Royal Statistical Society: Series B (Statistical Methodology), 72(2):143–170. doi:10.1111/j.1467-9868.2009.00730.x

Pramanik, S. and Johnson, V. E. (2024). Efficient alternatives for Bayesian hypothesis tests in psychology. Psychological Methods, 29(2):243–261. doi:10.1037/met0000482

See Also

nmbf01, pnmbf01, nnmbf01, powernmbf01

Examples

nmbf01(estimate = 0.25, se = 0.05, null = 0, psd = 0.5/sqrt(2)) # mode at 0.5

Sample size determination for normal moment prior Bayes factor

Description

This function computes the required sample size to obtain a normal moment prior Bayes factor (nbf01) more extreme than a threshold k with a specified target power.

Usage

nnmbf01(
  k,
  power,
  usd,
  null = 0,
  psd,
  dpm,
  dpsd,
  nrange = c(1, 10^5),
  lower.tail = TRUE,
  integer = TRUE,
  ...
)

Arguments

k

Bayes factor threshold

power

Target power

usd

Unit standard deviation, the standard error of the parameter estimate based on n=1\code{n}=1, see details

null

Parameter value under the point null hypothesis. Defaults to 0

psd

Spread of the normal moment prior assigned to the parameter under the alternative in the analysis. The modes of the prior are located at ±2psd\pm\sqrt{2}\,\code{psd}

dpm

Mean of the normal design prior assigned to the parameter

dpsd

Standard deviation of the normal design prior assigned to the parameter. Set to 0 to obtain a point prior at the design prior mean

nrange

Sample size search range over which numerical search is performed. Defaults to c(1, 10^5)

lower.tail

Logical indicating whether Pr(BF \leq k) (TRUE) or Pr(BF >> k) (FALSE) should be computed. Defaults to TRUE

integer

Logical indicating whether only integer valued sample sizes should be returned. If TRUE the required sample size is rounded to the next larger integer. Defaults to TRUE

...

Other arguments passed to stats::uniroot

Details

It is assumed that the standard error of the future parameter estimate is of the form se=usd/n\code{se} =\code{usd}/\sqrt{\code{n}}. For example, for normally distributed data with known standard deviation sd and two equally sized groups of size n, the standard error of an estimated standardized mean difference is se=sd2/n\code{se} = \code{sd}\sqrt{2/n}, so the corresponding unit standard deviation is usd=sd2\code{usd} = \code{sd}\sqrt{2}. See the vignette for more information.

Value

The required sample size to achieve the specified power

Author(s)

Samuel Pawel

See Also

nmbf01, pnmbf01, powernmbf01

Examples

nnmbf01(k = 1/10, power = 0.9, usd = 1, null = 0, psd = 0.5/sqrt(2), dpm = 0.5, dpsd = 0)

Sample size calculations for tt-test Bayes factor

Description

This function computes the required sample size to obtain a tt-test Bayes factor (tbf01) more extreme than a threshold k with a specified target power.

Usage

ntbf01(
  k,
  power,
  null = 0,
  plocation = 0,
  pscale = 1/sqrt(2),
  pdf = 1,
  type = c("two.sample", "one.sample", "paired"),
  alternative = c("two.sided", "less", "greater"),
  dpm = plocation,
  dpsd = pscale,
  lower.tail = TRUE,
  integer = TRUE,
  nrange = c(2, 10^4),
  ...
)

Arguments

k

Bayes factor threshold

power

Target power

null

Standardized mean difference under the point null hypothesis. Defaults to 0

plocation

tt prior location. Defaults to 0

pscale

tt prior scale. Defaults to 1/sqrt(2)

pdf

tt prior degrees of freedom. Defaults to 1 (a Cauchy prior)

type

Type of tt-test. Can be "two.sample" (default), "one.sample", or "paired"

alternative

Direction of the test. Can be either "two.sided" (default), "less", or "greater". The latter two truncate the analysis prior to negative and positive effects, respectively. If set to "less" or "greater", the power is only computed based on data with effect estimates in the direction of the alternative

dpm

Mean of the normal design prior assigned to the standardized mean difference. Defaults to the analysis prior location

dpsd

Standard deviation of the normal design prior assigned to the standardized mean difference. Set to 0 to obtain a point prior at the design prior mean. Defaults to the analysis prior scale

lower.tail

Logical indicating whether Pr(BF \leq k) (TRUE) or Pr(BF >> k) (FALSE) should be computed. Defaults to TRUE

integer

Logical indicating whether only integer valued sample sizes should be returned. If TRUE the required sample size is rounded to the next larger integer. Defaults to TRUE

nrange

Sample size search range over which numerical search is performed. Defaults to c(2, 10^4)

...

Other arguments passed to stats::uniroot

Value

The required sample size to achieve the specified power

Author(s)

Samuel Pawel

See Also

ptbf01, powertbf01, tbf01

Examples

## example from Schönbrodt and Wagenmakers (2018, p.135)
 ntbf01(k = 1/6, power = 0.95, dpm = 0.5, dpsd = 0, alternative = "greater")
 ntbf01(k = 1/6, power = 0.95, dpm = 0.5, dpsd = 0.1, alternative = "greater")
 ntbf01(k = 6, power = 0.95, dpm = 0, dpsd = 0, alternative = "greater",
        lower.tail = FALSE, nrange = c(2, 10000))

Cumulative distribution function of the z-test Bayes factor

Description

This function computes the probability of obtaining a Bayes factor (bf01) more extreme than a threshold k with a specified sample size.

Usage

pbf01(k, n, usd, null = 0, pm, psd, dpm = pm, dpsd = psd, lower.tail = TRUE)

Arguments

k

Bayes factor threshold

n

Sample size

usd

Unit standard deviation, the standard error of the parameter estimate based on n=1\code{n}=1, see details

null

Parameter value under the point null hypothesis. Defaults to 0

pm

Mean of the normal prior assigned to the parameter under the alternative in the analysis

psd

Standard deviation of the normal prior assigned to the parameter under the alternative in the analysis. Set to 0 to obtain a point prior at the prior mean

dpm

Mean of the normal design prior assigned to the parameter. Defaults to the same value as the analysis prior pm

dpsd

Standard deviation of the normal design prior assigned to the parameter. Defaults to the same value as the analysis prior psd

lower.tail

Logical indicating whether Pr(BF \leq k) (TRUE) or Pr(BF >> k) (FALSE) should be computed. Defaults to TRUE

Details

It is assumed that the standard error of the future parameter estimate is of the form se=usd/n\code{se} =\code{usd}/\sqrt{\code{n}}. For example, for normally distributed data with known standard deviation sd and two equally sized groups of size n, the standard error of an estimated standardized mean difference is se=sd2/n\code{se} = \code{sd}\sqrt{2/n}, so the corresponding unit standard deviation is usd=sd2\code{usd} = \code{sd}\sqrt{2}. See the vignette for more information.

Value

The probability that the Bayes factor is less or greater (depending on the specified lower.tail) than the specified threshold k

Author(s)

Samuel Pawel

See Also

nbf01, powerbf01, bf01

Examples

## point alternative (psd = 0)
pbf01(k = 1/10, n = 200, usd = 2, null = 0, pm = 0.5, psd = 0)

## normal alternative (psd > 0)
pbf01(k = 1/10, n = 100, usd = 2, null = 0, pm = 0.5, psd = 2)

## design prior is the null hypothesis (dpm = 0, dpsd = 0)
pbf01(k = 10, n = 1000, usd = 2, null = 0, pm = 0.3, psd = 2, dpm = 0, dpsd = 0, lower.tail = FALSE)

## draw a power curve
nseq <- round(exp(seq(log(10), log(10000), length.out = 100)))
plot(nseq, pbf01(k = 1/10, n = nseq, usd = 2, null = 0, pm = 0.3, psd = 0), type = "l",
     xlab = "n", ylab = bquote("Pr(BF"["01"] <= 1/10 * ")"), ylim = c(0, 1),
     log = "x", las = 1)

## standardized mean difference (usd = sqrt(2), effective sample size = per group size)
n <- 30
pbf01(k = 1/10, n = n, usd = sqrt(2), null = 0, pm = 0, psd = 1)

## z-transformed correlation (usd = 1, effective sample size = n - 3)
n <- 100
pbf01(k = 1/10, n = n - 3, usd = 1, null = 0, pm = 0.2, psd = 0.5)

## log hazard/odds ratio (usd = 2, effective sample size = total number of events)
nevents <- 100
pbf01(k = 1/10, n = nevents, usd = 2, null = 0, pm = 0, psd = sqrt(0.5))

Plot method for class "power.bftest"

Description

Plot method for class "power.bftest"

Usage

## S3 method for class 'power.bftest'
plot(x, nlim = c(2, 500), ngrid = 100, plot = TRUE, nullplot = TRUE, ...)

Arguments

x

Object of class "power.bftest"

nlim

Range of sample sizes over which the power should be computed. Defaults to c(2, 500)

ngrid

Number of grid point for which power should be computed. Defaults to 100

plot

Logical indicating whether data should be plotted. If FALSE only the data used for plotting are returned.

nullplot

Logcal indicating whether a second plot with the power in favor of the null (using a Bayes factor threshold of 1/k) should be created. Defaults to TRUE

...

Other arguments (for consistency with the generic)

Value

Plots power curves (if specified) and invisibly returns a list of data frames containing the data underlying the power curves

Author(s)

Samuel Pawel

See Also

powerbf01, powertbf01, powernmbf01

Examples

ssd1 <- powerbf01(k = 1/6, power = 0.95, pm = 0, psd = 1/sqrt(2), dpm = 0.5, dpsd = 0)
plot(ssd1, nlim = c(1, 8000))

power1 <- powerbf01(k = 1/2, n = 120, pm = 0, psd = 1/sqrt(2), dpm = 0.5, dpsd = 0)
plot(power1, nlim = c(1, 1000))

Cumulative distribution function of the normal moment prior Bayes factor

Description

This function computes the probability of obtaining a normal moment prior Bayes factor (nmbf01) more extreme than a threshold k with a specified sample size.

Usage

pnmbf01(k, n, usd, null = 0, psd, dpm, dpsd, lower.tail = TRUE)

Arguments

k

Bayes factor threshold

n

Sample size

usd

Unit standard deviation, the standard error of the parameter estimate based on n=1\code{n}=1, see details

null

Parameter value under the point null hypothesis. Defaults to 0

psd

Spread of the normal moment prior assigned to the parameter under the alternative in the analysis. The modes of the prior are located at ±2psd\pm\sqrt{2}\,\code{psd}

dpm

Mean of the normal design prior assigned to the parameter

dpsd

Standard deviation of the normal design prior assigned to the parameter. Set to 0 to obtain a point prior at the design prior mean

lower.tail

Logical indicating whether Pr(BF \leq k) (TRUE) or Pr(BF >> k) (FALSE) should be computed. Defaults to TRUE

Details

It is assumed that the standard error of the future parameter estimate is of the form se=usd/n\code{se} =\code{usd}/\sqrt{\code{n}}. For example, for normally distributed data with known standard deviation sd and two equally sized groups of size n, the standard error of an estimated standardized mean difference is se=sd2/n\code{se} = \code{sd}\sqrt{2/n}, so the corresponding unit standard deviation is usd=sd2\code{usd} = \code{sd}\sqrt{2}. See the vignette for more information.

Value

The probability that the Bayes factor is less or greater (depending on the specified lower.tail) than the specified threshold k

Author(s)

Samuel Pawel

See Also

nmbf01, nnmbf01, powernmbf01

Examples

## point desing prior (psd = 0)
pnmbf01(k = 1/10, n = 200, usd = 2, null = 0, psd = 0.5/sqrt(2), dpm = 0.5, dpsd = 0)

## normal design prior to incorporate parameter uncertainty (psd > 0)
pnmbf01(k = 1/10, n = 200, usd = 2, null = 0, psd = 0.5/sqrt(2), dpm = 0.5, dpsd = 0.25)

## design prior is the null hypothesis (dpm = 0, dpsd = 0)
pnmbf01(k = 10, n = 200, usd = 2, null = 0, psd = 0.5/sqrt(2), dpm = 0, dpsd = 0,
        lower.tail = FALSE)

Power and sample size calculations for z-test Bayes factor

Description

Compute probability that z-test Bayes factor is smaller than a specified threshold (the power), or determine sample size to obtain a target power.

Usage

powerbf01(
  n = NULL,
  power = NULL,
  k = 1/10,
  sd = 1,
  null = 0,
  pm,
  psd,
  type = c("two.sample", "one.sample", "paired"),
  dpm = pm,
  dpsd = psd,
  nrange = c(1, 10^5)
)

Arguments

n

Sample size (per group for two-sample tests). Has to be NULL if power is specified. Defaults to NULL

power

Target power. Has to be NULL if n is specified. Defaults to NULL

k

Bayes factor threshold. Defaults to 1/10, Jeffreys' threshold for 'strong evidence' against the null hypothesis

sd

Standard deviation of one observation (for type = "two.sample" or type = "one.sample") or of one difference within a pair of observations (type = "paired"). Is assumed to be known. Defaults to 1

null

Mean difference under the point null hypothesis. Defaults to 0

pm

Mean of the normal prior assigned to the mean difference under the alternative in the analysis

psd

Standard deviation of the normal prior assigned to the mean difference under the alternative in the analysis. Set to 0 to obtain a point prior at the prior mean

type

The type of test. One of "two.sample", "one.sample", "paired". Defaults to "two.sample"

dpm

Mean of the normal design prior assigned to the mean difference. Defaults to the same value as the analysis prior pm

dpsd

Standard deviation of the normal design prior assigned to the mean difference. Defaults to the same value as the analysis prior psd

nrange

Sample size search range over which numerical search is performed (only taken into account when n is NULL). Defaults to c(1, 10^5)

Details

This function provides a similar interface as stats::power.t.test. It also assumes that the data are continuous and that the parameter of interest is either a mean or a (standardized) mean difference. For some users, the low-level functions nbf01 (to directly compute the sample size for a fixed power) and pbf01 (to directly compute the power for a fixed sample size) may also be useful because they can be used for other data and parameter types.

Value

Object of class "power.bftest", a list of the arguments (including the computed one) augmented with method and note elements

Note

A warning message will be displayed in case that the specified target power is not achievable under the specified analysis and design priors.

Author(s)

Samuel Pawel

See Also

plot.power.bftest, nbf01, pbf01, bf01

Examples

## determine power
powerbf01(n = 100, pm = 0, psd = 1, dpm = 0.5, dpsd = 0)

## determine sample size
powerbf01(power = 0.99, pm = 0, psd = 1, dpm = 0.5, dpsd = 0)

Power and sample size calculations for normal moment prior Bayes factor

Description

Compute probability that normal moment prior Bayes factor is smaller than a specified threshold (the power), or determine sample size to obtain a target power.

Usage

powernmbf01(
  n = NULL,
  power = NULL,
  k = 1/10,
  sd = 1,
  null = 0,
  psd,
  type = c("two.sample", "one.sample", "paired"),
  dpm,
  dpsd,
  nrange = c(1, 10^5)
)

Arguments

n

Sample size (per group for two-sample tests). Has to be NULL if power is specified. Defaults to NULL

power

Target power. Has to be NULL if n is specified. Defaults to NULL

k

Bayes factor threshold. Defaults to 1/10, Jeffreys' threshold for 'strong evidence' against the null hypothesis

sd

Standard deviation of one observation (for type = "two.sample" or type = "one.sample") or of one difference within a pair of observations (type = "paired"). Is assumed to be known. Defaults to 1

null

Parameter value under the point null hypothesis. Defaults to 0

psd

Spread of the normal moment prior assigned to the parameter under the alternative in the analysis. The modes of the prior are located at ±2psd\pm\sqrt{2}\,\code{psd}

type

The type of test. One of "two.sample", "one.sample", "paired". Defaults to "two.sample"

dpm

Mean of the normal design prior assigned to the parameter

dpsd

Standard deviation of the normal design prior assigned to the parameter. Set to 0 to obtain a point prior at the design prior mean

nrange

Sample size search range over which numerical search is performed (only taken into account when n is NULL). Defaults to c(1, 10^5)

Details

This function provides a similar interface as stats::power.t.test. It also assumes that the data are continuous and that the parameter of interest is either a mean or a (standardized) mean difference. For some users, the low-level functions nnmbf01 (to directly compute the sample size for a fixed power) and pnmbf01 (to directly compute the power for a fixed sample size) may also be useful because they can be used for other data and parameter types.

Value

Object of class "power.bftest", a list of the arguments (including the computed one) augmented with method and note elements

Author(s)

Samuel Pawel

See Also

plot.power.bftest, nnmbf01, pnmbf01, nmbf01

Examples

## determine power
powernmbf01(n = 100, psd = 1, dpm = 0.5, dpsd = 0)

## determine sample size
powernmbf01(power = 0.99, psd = 1, dpm = 0.5, dpsd = 0)

Power and sample size calculations for tt-test Bayes factor

Description

Compute probability that tt-test Bayes factor is smaller than a specified threshold (the power), or determine sample size to obtain a target power.

Usage

powertbf01(
  n = NULL,
  power = NULL,
  k = 1/10,
  null = 0,
  plocation = 0,
  pscale = 1/sqrt(2),
  pdf = 1,
  type = c("two.sample", "one.sample", "paired"),
  alternative = c("two.sided", "less", "greater"),
  dpm = plocation,
  dpsd = pscale,
  nrange = c(2, 10^4)
)

Arguments

n

Sample size (per group)

power

Target power. Has to be NULL if n is specified. Defaults to NULL

k

Bayes factor threshold. Defaults to 1/10, Jeffreys' threshold for 'strong evidence' against the null hypothesis

null

Standardized mean difference under the point null hypothesis. Defaults to 0

plocation

tt prior location. Defaults to 0

pscale

tt prior scale. Defaults to 1/sqrt(2)

pdf

tt prior degrees of freedom. Defaults to 1 (a Cauchy prior)

type

Type of tt-test. Can be "two.sample" (default), "one.sample", or "paired"

alternative

Direction of the test. Can be either "two.sided" (default), "less", or "greater". The latter two truncate the analysis prior to negative and positive effects, respectively. If set to "less" or "greater", the power is only computed based on data with effect estimates in the direction of the alternative

dpm

Mean of the normal design prior assigned to the standardized mean difference. Defaults to the analysis prior location

dpsd

Standard deviation of the normal design prior assigned to the standardized mean difference. Set to 0 to obtain a point prior at the design prior mean. Defaults to the analysis prior scale

nrange

Sample size search range over which numerical search is performed (only taken into account when n is NULL). Defaults to c(2, 10^4)

Details

This function provides a similar interface as stats::power.t.test. For some users, the low-level functions ntbf01 (to directly compute the sample size for a fixed power) and ptbf01 (to directly compute the power for a fixed sample size) may also be useful.

Value

Object of class "power.bftest", a list of the arguments (including the computed one) augmented with method and note elements

Author(s)

Samuel Pawel

See Also

plot.power.bftest, ptbf01, ntbf01, tbf01

Examples

## determine power
powertbf01(n = 146, k = 1/6, dpm = 0.5, dps = 0, alternative = "greater")

## determine sample size
powertbf01(power = 0.95, k = 1/6, dpm = 0.5, dps = 0, alternative = "greater")

Print method for class "power.bftest"

Description

Print method for class "power.bftest"

Usage

## S3 method for class 'power.bftest'
print(x, digits = getOption("digits"), ...)

Arguments

x

Object of class "power.bftest"

digits

Number of digits for formatting of numbers

...

Other arguments (for consistency with the generic)

Value

Prints text summary in the console and invisibly returns the "power.bftest" object

Note

Function adapted from stats:::print.power.htest written by Peter Dalgaard

Author(s)

Samuel Pawel

See Also

powerbf01

Examples

powerbf01(power = 0.95, pm = 0, psd = 1, dpm = 0.5, dpsd = 0)
powerbf01(power = 0.95, pm = 0, psd = 1, dpm = 0.5, dpsd = 0, type = "one.sample")
powerbf01(power = 0.95, pm = 0, psd = 1, dpm = 0.5, dpsd = 0, type = "paired")
powerbf01(power = 0.95, pm = 1, psd = 0, dpm = 0.8, dpsd = 0, type = "paired")

Cumulative distribution function of the t-test Bayes factor

Description

This function computes the probability of obtaining a tt-test Bayes factor (tbf01) more extreme than a threshold k with a specified sample size.

Usage

ptbf01(
  k,
  n,
  n1 = n,
  n2 = n,
  null = 0,
  plocation = 0,
  pscale = 1/sqrt(2),
  pdf = 1,
  dpm = plocation,
  dpsd = pscale,
  type = c("two.sample", "one.sample", "paired"),
  alternative = c("two.sided", "less", "greater"),
  lower.tail = TRUE,
  drange = "adaptive",
  ...
)

Arguments

k

Bayes factor threshold

n

Sample size (per group)

n1

Sample size in group 1 (only required for two-sample tt-test with unequal group sizes)

n2

Sample size in group 2 (only required for two-sample tt-test with unequal group sizes)

null

Standardized mean difference under the point null hypothesis. Defaults to 0

plocation

tt prior location. Defaults to 0

pscale

tt prior scale. Defaults to 1/sqrt(2)

pdf

tt prior degrees of freedom. Defaults to 1 (a Cauchy prior)

dpm

Mean of the normal design prior assigned to the standardized mean difference. Defaults to the analysis prior location

dpsd

Standard deviation of the normal design prior assigned to the standardized mean difference. Set to 0 to obtain a point prior at the design prior mean. Defaults to the analysis prior scale

type

Type of tt-test. Can be "two.sample" (default), "one.sample", or "paired"

alternative

Direction of the test. Can be either "two.sided" (default), "less", or "greater". The latter two truncate the analysis prior to negative and positive effects, respectively. If set to "less" or "greater", the power is only computed based on data with effect estimates in the direction of the alternative

lower.tail

Logical indicating whether Pr(BF \leq k) (TRUE) or Pr(BF >> k) (FALSE) should be computed. Defaults to TRUE

drange

Standardized mean difference search range over which the critical values are searched for. Can be either set to a numerical range or to "adaptive" (default) which determines the range in an adaptive way from the other input parameters

...

Other arguments passed to stats::uniroot

Value

The probability that the Bayes factor is less or greater (depending on the specified lower.tail) than the specified threshold k

Author(s)

Samuel Pawel

See Also

tbf01, ntbf01, powertbf01

Examples

## example from Schönbrodt and Wagenmakers (2018, p. 135)
ptbf01(k = 1/6, n = 146, dpm = 0.5, dpsd = 0, alternative = "greater")
ptbf01(k = 6, n = 146, dpm = 0, dpsd = 0, alternative = "greater",
       lower.tail = FALSE)

## two-sided
ptbf01(k = 1/6, n = 146, dpm = 0.5, dpsd = 0)
ptbf01(k = 6, n = 146, dpm = 0, dpsd = 0, lower.tail = FALSE)

## one-sample test
ptbf01(k = 1/6, n = 146, dpm = 0.5, dpsd = 0, alternative = "greater", type = "one.sample")

t-test Bayes factor

Description

This function computes the Bayes factor that forms the basis of the informed Bayesian tt-test from Gronau et al. (2020). The Bayes factor quantifies the evidence that the data provide for the null hypothesis that the standardized mean difference (SMD) is zero against the alternative that the SMD is non-zero. A location-scale tt-distribution is assumed for the SMD under the alternative hypothesis. The Jeffreys-Zellner-Siow (JZS) Bayes factor (Rouder et al., 2009) is obtained as a special case by setting the location of the prior to zero and the prior degrees of freedom to one, which is the default.

The data are summarized by tt-statistics and sample sizes. The following types of tt-statistics are accepted:

  • Two-sample tt-test where the SMD represents the standardized mean difference between two group means (assuming equal variances in both groups)

  • One-sample tt-test where the SMD represents the standardized mean difference to the null value

  • Paired tt-test where the SMD represents the standardized mean change score

Usage

tbf01(
  t,
  n,
  n1 = n,
  n2 = n,
  plocation = 0,
  pscale = 1/sqrt(2),
  pdf = 1,
  type = c("two.sample", "one.sample", "paired"),
  alternative = c("two.sided", "less", "greater"),
  log = FALSE,
  ...
)

Arguments

t

tt-statistic

n

Sample size (per group)

n1

Sample size in group 1 (only required for two-sample tt-test with unequal group sizes)

n2

Sample size in group 2 (only required for two-sample tt-test with unequal group sizes)

plocation

tt prior location. Defaults to 0

pscale

tt prior scale. Defaults to 1/sqrt(2)

pdf

tt prior degrees of freedom. Defaults to 1 (a Cauchy prior)

type

Type of tt-test. Can be "two.sample" (default), "one.sample", or "paired"

alternative

Direction of the test. Can be either "two.sided" (default), "less", or "greater". The latter two truncate the analysis prior to negative and positive effects, respectively.

log

Logical indicating whether the natural logarithm of the Bayes factor should be returned. Defaults to FALSE

...

Additional arguments passed to stats::integrate

Details

The Bayes factor is implemented as in equation (5) in Gronau et al. (2020), and using suitable truncation in case of one-sided alternatives. Integration is performed numerically with stats::integrate.

Value

Bayes factor in favor of the null hypothesis over the alternative (BF > 1 indicates evidence for the null hypothesis, whereas BF < 1 indicates evidence for the alternative)

Author(s)

Samuel Pawel

References

Rouder, J. N., Speckman, P. L., Sun, D., Morey, R. D., Iverson, G. (2009). Bayesian tt tests for accepting and rejecting the null hypothesis. Psychonomic Bulletin & Review, 16(2):225-237. doi:10.3758/PBR.16.2.225

Gronau, Q. F., Ly., A., Wagenmakers, E.J. (2020). Informed Bayesian tt-Tests. The American Statistician, 74(2):137-143. doi:10.1080/00031305.2018.1562983

See Also

powertbf01, ptbf01, ntbf01

Examples

## analyses from Rouder et al. (2009):
## values from Table 1
tbf01(t = c(0.69, 3.20), n = 100, pscale = 1, type = "one.sample")
## examples from p. 232
tbf01(t = c(2.24, 2.03), n = 80, pscale = 1, type = "one.sample")

## analyses from Gronau et al. (2020) section 3.2:
## informed prior
tbf01(t = -0.90, n1 = 53, n2 = 57, plocation = 0.350, pscale = 0.102, pdf = 3,
      alternative = "greater", type = "two.sample")
## default (one-sided) prior
tbf01(t = -0.90, n1 = 53, n2 = 57, plocation = 0, pscale = 1/sqrt(2), pdf = 1,
      alternative = "greater", type = "two.sample")