Package {bfpwr}

Version:	0.3
Date:	2026-11-06
Author:	Samuel Pawel [aut, cre], František Bartoš [aut]
Maintainer:	Samuel Pawel <samuel.pawel@uzh.ch>
Title:	Power and Sample Size Calculations for Bayes Factor Analysis
Description:	Implements z-test, t-test, normal moment prior, and binomial test Bayes factors based on summary statistics, along with functionality to perform corresponding power and sample size calculations for fixed and sequential designs as described in Pawel and Held (2025) <doi:10.1080/00031305.2025.2467919>, Pawel and Held (2026) <doi:10.48550/ARXIV.2601.02851>, and Kelter and Pawel (2026) <doi:10.48550/arXiv.2502.02914>.
License:	GPL-3
Encoding:	UTF-8
Imports:	lamW, mvtnorm, withr, qrng, utils
Suggests:	roxygen2, tinytest, knitr, BayesFactor
VignetteBuilder:	knitr
NeedsCompilation:	no
URL:	https://github.com/SamCH93/bfpwr
BugReports:	https://github.com/SamCH93/bfpwr/issues
Config/roxygen2/version:	8.0.0
RoxygenNote:	7.3.3
Packaged:	2026-11-06 11:56:49 UTC; sam
Repository:	CRAN
Date/Publication:	2026-11-08 21:40:17 UTC

Point null 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,
  alternative = c("two.sided", "less", "greater")
)

Arguments

Value

Bayes factor in favor of the null hypothesis over the alternative (\text{BF}_{01} > 1 indicates evidence for the null hypothesis, whereas \text{BF}_{01} < 1 indicates evidence for the alternative)

Author(s)

Samuel Pawel

Examples

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

Numerical settings for Bayes factor designs

Description

Inspect or change the numerical settings used in subsequent calculations. Explicit function arguments override these session settings.

Usage

bfpwrOptions(...)

Arguments

Details

The settings are ngrid (sequential integration grid, default 10000), tol (sample-size and t-boundary root tolerance, 1e-8), rel.tol (t-Bayes-factor integration tolerance, 1e-8), subdivisions (integration limit, 1000), tail.eps (omitted t-predictive tail mass, 1e-6), and tail.nquad (t-tail quadrature nodes per dimension, 512). The absolute integration tolerance follows rel.tol unless abs.tol is supplied to a calculation. The internal z-boundary tolerance is fixed separately to preserve accuracy near point priors.

Values are stored in R options named bfpwr.ngrid, bfpwr.tol, and so on. Changes last for the current R session. Saved design objects retain the controls needed to reproduce their plots.

Value

A named list of effective settings. When setting values, the previous settings are returned invisibly, so they can be restored with another call.

Examples

bfpwrOptions()
old <- bfpwrOptions(ngrid = 20000, rel.tol = 1e-9)
bfpwrOptions(old)

Binomial Bayes factor

Description

This function computes the Bayes factor for testing a binomial proportion p based on x observed successes out of n trials. Two types of tests are available:

• Test of a point null hypothesis: The Bayes factor quantifies the evidence for H_0 \colon p = p_0 against H_1 \colon p \neq p_0. A beta prior is assigned to the proportion p under the alternative hypothesis H_1.

• Test of a directional null hypothesis: The Bayes factor quantifies the evidence for H_0 \colon p \leq p_0 against H_1 \colon p > p_0. A beta prior that is truncated to the range [0, p_0] under the null H_0 and to (p_0, 1] under the alternative H_1 is assigned to the proportion p under the corresponding hypothesis.

Usage

binbf01(
  x,
  n,
  p0 = 0.5,
  type = c("point", "direction"),
  a = 1,
  b = 1,
  log = FALSE
)

Arguments

Value

Bayes factor in favor of the null hypothesis over the alternative (\text{BF}_{01} > 1 indicates evidence for the null hypothesis, whereas \text{BF}_{01} < 1 indicates evidence for the alternative)

Author(s)

Samuel Pawel

See Also

pbinbf01, nbinbf01

Examples

## example on Mendelian inheritance from ?stats::binom.test
binbf01(x = 682, n = 925, p0 = 3/4, a = 1, b = 1, type = "point")
## 18.6 => strong evidence for the hypothesized p = 3/4 compared to other p

## with directional hypothesis
binbf01(x = 682, n = 925, p0 = 3/4, a = 1, b = 1, type = "direction")
## 1.5 => only anecdotal evidence for p <= 3/4 over p > 3/4

## Particle-counting experiment from Stone (1997) with point null
binbf01(x = 106298, n = 527135, p0 = 0.2, a = 1, b = 1, type = "point")
## 8.1 => moderate evidence for the alternative over the null

## Coin flip experiment from Bartos et al. (2023) with point null
binbf01(x = 178079, n = 350757 , p0 = 0.5, a = 5100, b = 4900, type = "point")
## => 1/1.72e+17 extreme evidence in favor of the alternative over the null

Directional 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 directional null hypothesis that the parameter value is less than or equal to the null value against the alternative that it is greater than the null value. A marginal normal prior is assigned to the parameter and split at the null value into the corresponding lower-side null and upper-side alternative distributions. The standard error is assumed to be known.

Usage

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

Arguments

Value

Bayes factor in favor of the null hypothesis over the alternative (\text{BF}_{01} > 1 indicates evidence for the null hypothesis, whereas \text{BF}_{01} < 1 indicates evidence for the alternative)

Author(s)

Samuel Pawel

Examples

dirbf01(estimate = 0.2, se = 0.2, 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,
  alternative = c("two.sided", "less", "greater"),
  ...
)

Arguments

Details

It is assumed that the standard error of the future parameter estimate is of the form \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 \code{se} = \code{sd}\sqrt{2/n}, so the corresponding unit standard deviation is \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. The normal design prior remains untruncated for one-sided alternatives. Power need not increase with sample size; for example, the probability of misleading evidence first rises and then falls. If both endpoints of nrange are below the target, the numerical search checks the interior maximum. The returned sample size is the smallest at which power reaches the target; power may fall below the target again at larger sample sizes.

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

Maximum Sample Size Determination for Sequential z-Test Bayes Factors

Description

Computes the maximum sample size required for a sequential z-test Bayes factor design to reach a target probability of stopping for H_1 or H_0.

Usage

nbf01seq(
  k1,
  k0 = 1/k1,
  power,
  usd = sqrt(2),
  null = 0,
  pm = NULL,
  psd,
  dpm = pm,
  dpsd = psd,
  type = c("normal", "directional", "moment"),
  target = c("H1", "H0"),
  nrange = c(2, 10^5),
  looks = 1,
  timing = NULL,
  minN = NULL,
  by = NULL,
  strict = TRUE,
  integer = TRUE,
  search = c("adaptive", "exhaustive"),
  details = FALSE,
  alternative = c("two.sided", "less", "greater"),
  ...
)

Arguments

Details

The function searches over the maximum sample size of the sequential design. Candidate look schedules are rebuilt for each maximum sample size according to looks/timing or by/minN. Power need not be monotone for every design-prior and target combination, and rounded interim looks add further non-monotonicity; search selects the search rule. For by/minN schedules, scheduled maximum sample sizes are scanned in increasing order and previous look calculations are reused; search is ignored. If the target is not reached within nrange, the function returns NaN and issues a warning.

Value

The maximum sample size found to achieve the specified power. If details = TRUE, returns a list with the sample size, achieved power, generated design, and search diagnostics.

Author(s)

František Bartoš

See Also

pbf01seq, powerbf01seq, nbf01

Examples

nbf01seq(k1 = 1/5, k0 = 5, power = 0.8, usd = sqrt(2),
         pm = 0, psd = 1, dpm = 0.5, dpsd = 0,
         looks = 3, nrange = c(2, 200))

Sample size determination for binomial Bayes factor

Description

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

Usage

nbinbf01(
  k,
  power,
  p0 = 0.5,
  type = c("point", "direction"),
  a = 1,
  b = 1,
  dp = NA,
  da = a,
  db = b,
  dl = 0,
  du = 1,
  lower.tail = TRUE,
  nrange = c(1, 10^4),
  ...
)

Arguments

Value

The required sample size to achieve the specified power

Author(s)

Samuel Pawel

See Also

pbinbf01, binbf01

Examples

## sample size parameters
pow <- 0.9
p0 <- 3/4
a <- 1
b <- 1
k <- 1/10

## Not run: 
## sample sizes for directional testing
(nH1 <- nbinbf01(k = k, power = pow, p0 = p0, type = "direction", a = a,
                 b = b, da = a, db = b, dl = p0, du = 1))
(nH0 <- nbinbf01(k = 1/k, power = pow, p0 = p0, type = "direction", a = a,
                 b = b, da = a, db = b, dl = 0, du = p0, lower.tail = FALSE))
nseq <- seq(1, 1.1*max(c(nH1, nH0)), length.out = 100)
powH1 <- pbinbf01(k = k, n = nseq, p0 = p0, type = "direction", a = a,
                  b = b, da = a, db = b, dl = p0, du = 1)
powH0 <- pbinbf01(k = 1/k, n = nseq, p0 = p0, type = "direction", a = a,
                  b = b, da = a, db = b, dl = 0, du = p0, lower.tail = FALSE)
matplot(nseq, cbind(powH1, powH0), type = "s", xlab = "n", ylab = "Power", lty = 1,
        ylim = c(0, 1), col = c(2, 4), las = 1)
abline(h = pow, lty = 2)
abline(v = c(nH1, nH0), col = c(2, 4), lty = 2)
legend("topleft", legend = c("H1", "H0"), lty = 1, col = c(2, 4))

## sample sizes for point null testing
(nH1 <- nbinbf01(k = k, power = pow, p0 = p0, type = "point", a = a,
                 b = b, da = a, db = b))
(nH0 <- nbinbf01(k = 1/k, power = pow, p0 = p0, type = "point", a = a,
                 b = b, dp = p0, lower.tail = FALSE, nrange = c(1, 10^5)))
nseq <- seq(1, max(c(nH1, nH0)), length.out = 100)
powH1 <- pbinbf01(k = k, n = nseq, p0 = p0, type = "point", a = a,
                  b = b, da = a, db = b, dl = 0, du = 1)
powH0 <- pbinbf01(k = 1/k, n = nseq, p0 = p0, type = "point", a = a,
                  b = b, dp = p0, lower.tail = FALSE)
matplot(nseq, cbind(powH1, powH0), type = "s", xlab = "n", ylab = "Power", lty = 1,
        ylim = c(0, 1), col = c(2, 4), las = 1)
abline(h = pow, lty = 2)
abline(v = c(nH1, nH0), col = c(2, 4), lty = 2)
legend("topleft", legend = c("H1", "H0"), lty = 1, col = c(2, 4))

## End(Not run)

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,
  alternative = c("two.sided", "less", "greater")
)

Arguments

Details

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

Value

Bayes factor in favor of the null hypothesis over the alternative (\text{BF}_{01} > 1 indicates evidence for the null hypothesis, whereas \text{BF}_{01} < 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

## positive normal moment alternative
nmbf01(estimate = 0.25, se = 0.05, psd = 0.5/sqrt(2), alternative = "greater")

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,
  ...,
  alternative = c("two.sided", "less", "greater")
)

Arguments

Details

It is assumed that the standard error of the future parameter estimate is of the form \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 \code{se} = \code{sd}\sqrt{2/n}, so the corresponding unit standard deviation is \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. The normal design prior remains untruncated for one-sided alternatives. Power need not increase with sample size; for example, the probability of misleading evidence first rises and then falls. If both endpoints of nrange are below the target, the numerical search checks the interior maximum. The returned sample size is the smallest at which power reaches the target; power may fall below the target again at larger sample sizes.

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 t-test Bayes factor

Description

This function computes the required sample size to obtain a t-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),
  ratio = 1,
  drange = "adaptive",
  tail.eps = getOption("bfpwr.tail.eps", 1e-06),
  tail.nquad = getOption("bfpwr.tail.nquad", 512),
  ...
)

Arguments

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. The normal design prior remains untruncated for one-sided alternatives. Power need not increase with sample size; for example, the probability of misleading evidence first rises and then falls. If both endpoints of nrange are below the target, the numerical search checks the interior maximum. The returned sample size is the smallest at which power reaches the target; power may fall below the target again at larger sample sizes.

Author(s)

Samuel Pawel, František Bartoš

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

Maximum Sample Size Determination for Sequential t-Test Bayes Factors

Description

Computes the maximum sample size required for a sequential t-test Bayes factor design to reach a target probability of stopping for H_1 or H_0.

Usage

ntbf01seq(
  k1,
  k0 = 1/k1,
  power,
  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"),
  target = c("H1", "H0"),
  nrange = c(2, 10^4),
  looks = 1,
  timing = NULL,
  minN = NULL,
  by = NULL,
  ratio = 1,
  strict = TRUE,
  trange = "adaptive",
  tail.eps = getOption("bfpwr.tail.eps", 1e-06),
  tail.nquad = getOption("bfpwr.tail.nquad", 512),
  integer = TRUE,
  search = c("adaptive", "exhaustive"),
  details = FALSE,
  ...
)

Arguments

Details

The function searches over the maximum group-1 sample size for two-sample designs, or the maximum sample size for one-sample and paired designs. Candidate look schedules are rebuilt for each maximum sample size according to looks/timing or by/minN. Power need not be monotone for every design-prior and target combination, and rounded interim looks add further non-monotonicity; search selects the search rule. For by/minN schedules, scheduled maximum sample sizes are scanned in increasing order and previous look calculations are reused; search is ignored. If the target is not reached within nrange, the function returns NaN and issues a warning.

Value

The maximum sample size in group 1 found to achieve the specified power. If details = TRUE, returns a list with the sample size, achieved power, generated design, and search diagnostics.

Author(s)

František Bartoš

See Also

ptbf01seq, powertbf01seq, ntbf01

Examples

ntbf01seq(k1 = 1/2, k0 = 2, power = 0.4, dpm = 0.5, dpsd = 0,
          alternative = "greater", looks = 2, nrange = c(2, 80),
          strict = FALSE)

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,
  alternative = c("two.sided", "less", "greater")
)

Arguments

Details

It is assumed that the standard error of the future parameter estimate is of the form \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 \code{se} = \code{sd}\sqrt{2/n}, so the corresponding unit standard deviation is \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

Note

For a one-sided alternative, the normal design prior remains untruncated; truncation applies only to the analysis prior.

Author(s)

Samuel Pawel, František Bartoš

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

Sequential Bayes Factor Design

Description

Computes cumulative probabilities of observing z-test Bayes factors that provide evidence for the null hypothesis H_0, the alternative hypothesis H_1, or remain inconclusive in a sequential design. Optionally, also computes the expected sample size.

Usage

pbf01seq(
  k1,
  k0 = 1/k1,
  se,
  n = NULL,
  null = 0,
  pm = NULL,
  psd,
  dpm = pm,
  dpsd = psd,
  type = c("normal", "directional", "moment"),
  strict = TRUE,
  alternative = c("two.sided", "less", "greater"),
  ...
)

Arguments

Details

The function constructs per-stage integration regions for cumulative z-statistics based on the Bayes factor thresholds k1 and k0, then computes the probability of these regions under a predictive distribution defined by se and the normal design prior with dpm and dpsd. Integration is performed via mvtnorm::lpmvnorm. This is deterministic numerical integration; increasing ngrid can be used to check convergence. Very small stopping probabilities can be missed by the integration grid; increasing its size does not guarantee relative accuracy for rare events. The null value and the analysis and design prior means are all specified on the original parameter scale, matching the fixed-sample z-test functions. The normal design prior is not truncated, including for one-sided analysis priors. One-sided Bayes factor boundaries are found numerically using the same calculation as pbf01 or pnmbf01.

Value

An object of class "bfseqdesign", which is a list containing the input arguments, the critical z-values, the expected sample size, the cumulative probabilities of stopping for H_1 and H_0 by each stage, and the cumulative probabilities of remaining inconclusive by each stage.

Author(s)

Samuel Pawel, František Bartoš

Examples

n <- seq(50, 200, 50) # sample size per stage
se <- sqrt(2/n) # standard errors per stage
res <- pbf01seq(k1 = 1/10, k0 = 3, se = se, n = n, pm = 0, psd = 1,
                dpm = 0.5, dpsd = 0.05, type = "normal")
res # print summary
plot(res) # plot summary
res$cumpH1 # cumulative probability to stop for H1 by each stage
res$cumpH0 # cumulative probability to stop for H0 by each stage
res$EN # expected sample size

Cumulative distribution function of the binomial Bayes factor

Description

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

Usage

pbinbf01(
  k,
  n,
  p0 = 0.5,
  type = c("point", "direction"),
  a = 1,
  b = 1,
  dp = NA,
  da = a,
  db = b,
  dl = 0,
  du = 1,
  lower.tail = TRUE
)

Arguments

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

binbf01, nbinbf01

Examples

## compute probability that BF > 10 under the point null
a <- 1
b <- 1
p0 <- 3/4
k <- 10
nseq <- seq(1, 1000, length.out = 50)
powH0 <- pbinbf01(k = k, n = nseq, p0 = p0, type = "point", a = a, b = b,
                  dp = p0, lower.tail = FALSE)
plot(nseq, powH0, type = "s", xlab = "n", ylab = "Power")

## compare to normal approximation
pm <- a/(a + b) # prior mean under H1
psd <- sqrt(a*b/(a + b)^2/(a + b + 1)) # prior standard deviation under H1
pownormH0 <- pbf01(k = k, n = nseq, usd = sqrt(p0*(1 - p0)), null = p0,
                   pm = pm, psd = psd, dpm = p0, dpsd = 0, lower.tail = FALSE)
lines(nseq, pownormH0, type = "s", col = 2)
legend("right", legend = c("Exact", "Normal approximation"), lty = 1,
       col = c(1, 2))

## compute probability that BF < 1/10 under the p|H1 ~ Beta(a, b) alternative
a <- 10
b <- 5
p0 <- 3/4
k <- 1/10
powH1 <- pbinbf01(k = k, n = nseq, p0 = p0, type = "point", a = a, b = b,
                  da = a, db = b, dl = 0, du = 1)
plot(nseq, powH1, type = "s", xlab = "n", ylab = "Power")

## compare to normal approximation
pm <- a/(a + b) # prior mean under H1
psd <- sqrt(a*b/(a + b)^2/(a + b + 1)) # prior standard deviation under H1
pownormH1 <- pbf01(k = k, n = nseq, usd = sqrt(pm*(1 - pm)), null = p0,
                   pm = pm, psd = psd, dpm = pm, dpsd = psd)
lines(nseq, pownormH1, type = "s", col = 2)
legend("right", legend = c("Exact", "Normal approximation"), lty = 1,
       col = c(1, 2))

## probability that directional BF <= 1/10 under uniform [3/4, 1] design prior
pow <- pbinbf01(k = 1/10, n = nseq, p0 = 3/4, type = "direction", a = 1, b = 1,
                da = 1, db = 1, dl = 3/4, du = 1)
plot(nseq, pow, type = "s", xlab = "n", ylab = "Power")

Probability of final-stage efficacy in two-stage binomial Bayes factor designs

Description

Compute probability that binomial Bayes factor (binbf01) is equal or below a threshold at final stage, taking into account that the study can stop for futility if it is greater than a specified threshold at interim.

Usage

pbinbf01seq(
  n1,
  n2,
  k = 1/10,
  kf = 1/k,
  p0 = 0.5,
  type = c("direction"),
  a = 1,
  b = 1,
  dp = NA,
  da = a,
  db = b,
  dl = 0,
  du = 1
)

Arguments

Value

The probability of obtaining a Bayes factor equal or below k at the final stage taking into account potential futility stopping with BF01 > kf at interim

Author(s)

Samuel Pawel

See Also

binbf01, powerbinbf01seq

Examples

## probability of BF<1/10 under alternative truncated beta design prior
pbinbf01seq(n1 = 10, n2 = 20, k = 1/10, kf = 3, p0 = 0.2, a = 1, b = 1,
            dl = 0.2, du = 1, type = "direction") # with interim analysis
pbinbf01(n = 20, k = 1/10, p0 = 0.2, a = 1, b = 1, dl = 0.2, du = 1,
         type = "direction") # without interim analysis

## probability to stop at interim under null truncated beta design prior
pbinbf01(n = 10, k = 3, p0 = 0.2, a = 1, b = 1, dl = 0, du = 0.2,
         type = "direction", lower.tail = FALSE)

## probability of BF<1/10 under point null design prior
pbinbf01seq(n1 = 10, n2 = 20, k = 1/10, kf = 3, p0 = 0.2, a = 1, b = 1,
            dp = 0.2, type = "direction") # with interim analysis
pbinbf01(n = 20, k = 1/10, p0 = 0.2, a = 1, b = 1, dp = 0.2,
         type = "direction") # without interim analysis

## probability to stop at interim under point null design prior
pbinbf01(n = 10, k = 3, p0 = 0.2, a = 1, b = 1, dp = 0.2,
         type = "direction", lower.tail = FALSE)

Plot method for class "bfseqdesign"

Description

Plot method for class "bfseqdesign"

Usage

## S3 method for class 'bfseqdesign'
plot(
  x,
  plot = TRUE,
  nullplot = TRUE,
  zplot = FALSE,
  digits = max(3L, getOption("digits") - 3L),
  ...
)

Arguments

Value

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

Author(s)

Samuel Pawel, František Bartoš

See Also

pbf01seq

Examples

n <- seq(25, 150, 25) # sample size per stage
se <- sqrt(2/n) # standard errors per stage
res <- pbf01seq(k1 = 1/10, k0 = 3, se = se, n = n, pm = 0, psd = 1,
                dpm = 0.5, dpsd = 0.1, type = "moment")
plot(res, nullplot = FALSE) # only under design prior
plot(res, nullplot = TRUE) # also plot under null hypothesis
plot(res, zplot = TRUE) # show critical z-values

## case which causes trouble
pm <- 0
psd <- 5
dpm <- 24
dpsd <- 0
seseq <- c(12.030479, 8.506833, 6.945800, 6.015239, 5.380194, 4.911422, 4.547094,
           4.253417, 4.010160, 3.804371)
nseq <- seq(2, 20, 2)
pbf01seq(k1 = 1/10, k0 = 3, se = seseq, n = nseq, pm = pm, psd = psd,
         dpm = dpm, dpsd = dpsd, type = "directional")

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,
  type = "l",
  plot = TRUE,
  nullplot = TRUE,
  ...
)

Arguments

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, František Bartoš

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,
  alternative = c("two.sided", "less", "greater")
)

Arguments

Details

It is assumed that the standard error of the future parameter estimate is of the form \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 \code{se} = \code{sd}\sqrt{2/n}, so the corresponding unit standard deviation is \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

Note

The normal design prior is not truncated, including for one-sided analysis priors.

Author(s)

Samuel Pawel

See Also

nmbf01, nnmbf01, powernmbf01

Examples

## point design prior (dpsd = 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 (dpsd > 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),
  alternative = c("two.sided", "less", "greater"),
  tol = getOption("bfpwr.tol", 1e-08)
)

Arguments

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. The sample-size tolerance tol is used only when a numerical search is required; an analytical solution does not use it.

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. The normal design prior remains untruncated for one-sided alternatives. Power need not increase with sample size; for example, the probability of misleading evidence first rises and then falls. If both endpoints of nrange are below the target, the numerical search checks the interior maximum. The returned sample size is the smallest at which power reaches the target; power may fall below the target again at larger sample sizes.

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)

## one-sided alternative with a half-normal analysis prior
powerbf01(power = 0.8, pm = 0, psd = 1, dpm = 0.5, dpsd = 0,
          alternative = "greater")

Power and Maximum Sample Size Calculations for Sequential z-Test Bayes Factors

Description

Computes cumulative stopping probabilities for a sequential z-test Bayes factor design, or determines the maximum sample size needed to obtain a target stopping probability.

Usage

powerbf01seq(
  n = NULL,
  power = NULL,
  k1 = 1/10,
  k0 = 1/k1,
  sd = 1,
  null = 0,
  pm,
  psd,
  type = c("two.sample", "one.sample", "paired"),
  bftype = c("normal", "directional", "moment"),
  dpm = pm,
  dpsd = psd,
  target = c("H1", "H0"),
  nrange = c(2, 10^5),
  looks = 1,
  timing = NULL,
  minN = NULL,
  by = NULL,
  strict = TRUE,
  search = c("adaptive", "exhaustive"),
  alternative = c("two.sided", "less", "greater"),
  ...
)

Arguments

Details

This function provides a higher-level interface to pbf01seq and nbf01seq for continuous data. If power is supplied, the returned design is evaluated at the searched maximum sample size, and solver$reached records whether the target was achieved within nrange. If n is supplied, no search is performed and the solver element records the achieved stopping probability for the fixed schedule. For fixed-n increment schedules with missing minN, nrange[1] is used as the default first look, clamped to n when necessary.

Value

An object of class "bfseqdesign" containing the sequential design, augmented with a solver element. In fixed-n mode, solver$targetPower and solver$reached are NA.

Author(s)

František Bartoš

See Also

pbf01seq, nbf01seq, powerbf01

Examples

powerbf01seq(n = 60, k1 = 1/5, k0 = 5, pm = 0, psd = 1,
             dpm = 0.5, dpsd = 0, looks = 3)
powerbf01seq(power = 0.8, k1 = 1/5, k0 = 5, pm = 0, psd = 1,
             dpm = 0.5, dpsd = 0, looks = 3, nrange = c(2, 200))

## point null versus a positive half-normal alternative
powerbf01seq(power = 0.8, pm = 0, psd = 1, dpm = 0.5, dpsd = 0,
             alternative = "greater", looks = 3, nrange = c(2, 200))

## point null versus a positive normal moment alternative
powerbf01seq(n = 100, psd = 0.5/sqrt(2), dpm = 0.5, dpsd = 0,
             bftype = "moment", alternative = "greater", looks = 3)

Power and sample size calculations for binomial Bayes factor

Description

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

Usage

powerbinbf01(
  n = NULL,
  power = NULL,
  k = 1/10,
  p0 = 0.5,
  type = c("point", "direction"),
  a = 1,
  b = 1,
  dp = NA,
  da = a,
  db = b,
  dl = 0,
  du = 1,
  nrange = c(1, 10^4),
  tol = getOption("bfpwr.tol", 1e-08)
)

Arguments

Details

This function provides a similar interface as stats::power.prop.test. For some users, the low-level functions nbinbf01 (to directly compute the sample size for a fixed power) and pbinbf01 (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, pbinbf01, nbinbf01, binbf01

Examples

## determine sample size
(nres <- powerbinbf01(power = 0.8, p0 = 0.2, type = "direction", dl = 0.2))
## Not run: 
plot(nres, nlim = c(1, 250), ngrid = 250, type = "s")

## End(Not run)

## determine power
(powres <- powerbinbf01(n = 100, type = "point"))
## Not run: 
plot(powres)

## End(Not run)

Design characteristics of two-stage binomial Bayes factor designs

Description

Compute design characteristics of a two-stage binomial Bayes factor design (binbf01) that stops for futility at the interim stage if the Bayes factor BF01 is greater than kf, and declares efficacy at the final stage if BF01 is equal to or below k.

Usage

powerbinbf01seq(
  n1,
  n2,
  k = 1/10,
  kf = 1/k,
  p0 = 0.5,
  type = c("direction"),
  a = 1,
  b = 1,
  dp = NA,
  da = a,
  db = b,
  dl = 0,
  du = 1
)

Arguments

Details

For some users, the low-level function pbinbf01seq that is used internally may also be useful.

Value

An object of class "power.bftestseq", i.e., a list of the arguments, the probabilities of stopping for futility at the interim stage (pintfut, pintfut0) and of efficacy at the final stage (pfineff, pfineff0), and the expected sample sizes (nexp, nexp0), each under the design prior and under p = p0

Author(s)

Samuel Pawel

See Also

binbf01, pbinbf01seq

Examples

## point prior under the alternative
powerbinbf01seq(n1 = 20, n2 = 40, k = 1/10, kf = 3, p0 = 0.2, dp = 0.4)

## uniform prior [0.2, 1] under the alternative
powerbinbf01seq(n1 = 20, n2 = 40, k = 1/10, kf = 3, p0 = 0.2, dl = 0.2, du = 1)

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),
  tol = getOption("bfpwr.tol", 1e-08),
  alternative = c("two.sided", "less", "greater")
)

Arguments

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

Note

A warning message will be displayed in case that the specified target power is not achievable under the specified analysis and design priors. The normal design prior remains untruncated for one-sided alternatives. Power need not increase with sample size; for example, the probability of misleading evidence first rises and then falls. If both endpoints of nrange are below the target, the numerical search checks the interior maximum. The returned sample size is the smallest at which power reaches the target; power may fall below the target again at larger sample sizes.

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 t-test Bayes factor

Description

Compute probability that t-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),
  ratio = 1,
  drange = "adaptive",
  tail.eps = getOption("bfpwr.tail.eps", 1e-06),
  tail.nquad = getOption("bfpwr.tail.nquad", 512),
  ...
)

Arguments

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

Note

A warning message will be displayed in case that the specified target power is not achievable under the specified analysis and design priors. The normal design prior remains untruncated for one-sided alternatives. Power need not increase with sample size; for example, the probability of misleading evidence first rises and then falls. If both endpoints of nrange are below the target, the numerical search checks the interior maximum. The returned sample size is the smallest at which power reaches the target; power may fall below the target again at larger sample sizes.

Author(s)

Samuel Pawel, František Bartoš

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

Power and Maximum Sample Size Calculations for Sequential t-Test Bayes Factors

Description

Computes cumulative stopping probabilities for a sequential t-test Bayes factor design, or determines the maximum sample size needed to obtain a target stopping probability.

Usage

powertbf01seq(
  n = NULL,
  power = NULL,
  k1 = 1/10,
  k0 = 1/k1,
  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,
  target = c("H1", "H0"),
  nrange = c(2, 10^4),
  looks = 1,
  timing = NULL,
  minN = NULL,
  by = NULL,
  ratio = 1,
  strict = TRUE,
  trange = "adaptive",
  tail.eps = getOption("bfpwr.tail.eps", 1e-06),
  tail.nquad = getOption("bfpwr.tail.nquad", 512),
  search = c("adaptive", "exhaustive"),
  ...
)

Arguments

Details

This function provides a higher-level interface to ptbf01seq and ntbf01seq. If power is supplied, the returned design is evaluated at the searched maximum sample size, and solver$reached records whether the target was achieved within nrange. If n is supplied, no search is performed and the solver element records the achieved stopping probability for the fixed schedule. For fixed-n increment schedules with missing minN, nrange[1] is used as the default first look, clamped to n when necessary.

Value

An object of class "bfseqdesign" containing the sequential design, augmented with a solver element. In fixed-n mode, solver$targetPower and solver$reached are NA.

Author(s)

František Bartoš

See Also

ptbf01seq, ntbf01seq, powertbf01

Examples

powertbf01seq(n = 20, k1 = 1/2, k0 = 2, dpm = 0.5, dpsd = 0,
              alternative = "greater", looks = 2, strict = FALSE)
powertbf01seq(power = 0.4, k1 = 1/2, k0 = 2, dpm = 0.5, dpsd = 0,
              alternative = "greater", looks = 2, nrange = c(2, 80),
              strict = FALSE)

Print method for class "bfseqdesign"

Description

Print method for class "bfseqdesign"

Usage

## S3 method for class 'bfseqdesign'
print(x, digits = max(3L, getOption("digits") - 3L), ...)

Arguments

Value

Prints text summary in the console and invisibly returns the "bfseqdesign" object

Author(s)

Samuel Pawel, František Bartoš

See Also

pbf01seq

Examples

n <- seq(50, 300, 50) # sample size per stage
se <- sqrt(2/n) # standard errors per stage
res <- pbf01seq(k1 = 1/10, k0 = 5, se = se, n = n, pm = 0, psd = 1,
                dpm = 0.5, dpsd = 0.1, type = "normal")
res

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

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, František Bartoš

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

Print method for class "power.bftestseq"

Description

Print method for class "power.bftestseq"

Usage

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

Arguments

Value

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

Author(s)

Samuel Pawel

Cumulative distribution function of the t-test Bayes factor

Description

This function computes the probability of obtaining a t-test Bayes factor (tbf01) more extreme than a threshold k with a specified sample size. The future standardized estimate is modeled with its known-variance normal distribution. Thus, although the analysis Bayes factor uses the finite-sample t distribution, the returned power is an asymptotic approximation rather than exact noncentral-t power; differences can be material at small sample sizes.

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",
  tail.eps = getOption("bfpwr.tail.eps", 1e-06),
  tail.nquad = getOption("bfpwr.tail.nquad", 512),
  ...
)

Arguments

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, František Bartoš

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

Sequential T-Test Bayes Factor Design

Description

Computes cumulative probabilities of observing t-test Bayes factors that provide evidence for the null hypothesis H_0, the alternative hypothesis H_1, or remain inconclusive in a sequential design. Also computes the expected sample size.

Usage

ptbf01seq(
  k1,
  k0 = 1/k1,
  n,
  n1 = n,
  n2 = n,
  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"),
  strict = TRUE,
  trange = "adaptive",
  tail.eps = getOption("bfpwr.tail.eps", 1e-06),
  tail.nquad = getOption("bfpwr.tail.nquad", 512),
  ...
)

Arguments

Details

The function constructs per-stage integration regions for cumulative z-statistics based on the Bayes factor thresholds k1 and k0, then computes the probability of these regions under a predictive distribution defined by the known-variance, asymptotic approximation to the variance of the t-statistic and the normal design prior with dpm and dpsd. Integration is performed via mvtnorm::lpmvnorm. This is deterministic numerical integration; increasing ngrid can be used to check convergence.

Value

An object of class "bfseqdesign", which is a list containing the input arguments, the critical z-values, the expected sample size, the cumulative probabilities of stopping for H_1 and H_0 by each stage, and the cumulative probabilities of remaining inconclusive by each stage.

Author(s)

Samuel Pawel, František Bartoš

Examples

## similar to example from Schönbrodt and Wagenmakers (2018, p. 138)
k0 <- 6
k1 <- 1/30
dpm <- 0.5
dpsd <- 0.1
plocation <- 0
pscale <- 1/sqrt(2)
pdf <- 1
type <- "two.sample"
alternative <- "greater"
n <- seq(40, 100, 10) # sample size (per group) per stage
res <- ptbf01seq(k1 = k1, k0 = k0, n = n, plocation = plocation,
                 pscale = pscale, pdf = pdf, dpm = dpm, dpsd = dpsd,
                 alternative = alternative, type = type)
res
plot(res) # show stopping probabilities
plot(res, zplot = TRUE) # show critical z-values

t-test Bayes factor

Description

This function computes the Bayes factor that forms the basis of the informed Bayesian t-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 t-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 t-statistics and sample sizes. The following types of t-statistics are accepted:

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

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

• Paired t-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,
  tail.nquad = getOption("bfpwr.tail.nquad", 512),
  ...
)

Arguments

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. Most calculations use stats::integrate. Noncentral-t densities whose t-statistic and noncentrality parameter have opposite signs, where stats::dt is unreliable, use an exact mixture representation evaluated with Gauss-Laguerre quadrature. Extreme wrong-tail one-sided calculations use fixed Gauss-Legendre quadrature to avoid noncentral-t underflow. Same-sign noncentral-t densities come from stats::dt, which can be inaccurate for extreme t-statistics (very small Bayes factors).

Value

Bayes factor in favor of the null hypothesis over the alternative (\text{BF}_{01} > 1 indicates evidence for the null hypothesis, whereas \text{BF}_{01} < 1 indicates evidence for the alternative)

Author(s)

Samuel Pawel, František Bartoš

References

Rouder, J. N., Speckman, P. L., Sun, D., Morey, R. D., Iverson, G. (2009). Bayesian t 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 t-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")