Package 'bfpwr' reference manual

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:18:17 UTC
Source:	https://github.com/cran/bfpwr

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

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,
  ...
)
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 $\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 $\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.

Author(s)

Samuel Pawel

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

## 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)
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 $\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(x \mid \code{null}, \code{psd}) = N(x \mid \code{null}, \code{psd}^2) \times (x - \code{null})/ \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 (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

Examples

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

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,
  ...
)
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 $\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 $\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

Value

The required sample size to achieve the specified power

Author(s)

Samuel Pawel

Examples

nnmbf01(k = 1/10, power = 0.9, usd = 1, null = 0, psd = 0.5/sqrt(2), dpm = 0.5, dpsd = 0)
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),
  ...
)
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`	$t$ prior location. Defaults to `0`
`pscale`	$t$ prior scale. Defaults to `1/sqrt(2)`
`pdf`	$t$ prior degrees of freedom. Defaults to `1` (a Cauchy prior)
`type`	Type of $t$ -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

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

## 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)
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 $\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

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

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

## 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, ...)
## 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

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

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

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

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)

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

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)

## 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)
)
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 $\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

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)

## 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)
)
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`	$t$ prior location. Defaults to `0`
`pscale`	$t$ prior scale. Defaults to `1/sqrt(2)`
`pdf`	$t$ prior degrees of freedom. Defaults to `1` (a Cauchy prior)
`type`	Type of $t$ -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

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

## 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"), ...)
## 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

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

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 $t$ -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",
  ...
)
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 $t$ -test with unequal group sizes)
`n2`	Sample size in group 2 (only required for two-sample $t$ -test with unequal group sizes)
`null`	Standardized mean difference under the point null hypothesis. Defaults to `0`
`plocation`	$t$ prior location. Defaults to `0`
`pscale`	$t$ prior scale. Defaults to `1/sqrt(2)`
`pdf`	$t$ 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 $t$ -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

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

## 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 $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,
  ...
)
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`	$t$ -statistic
`n`	Sample size (per group)
`n1`	Sample size in group 1 (only required for two-sample $t$ -test with unequal group sizes)
`n2`	Sample size in group 2 (only required for two-sample $t$ -test with unequal group sizes)
`plocation`	$t$ prior location. Defaults to `0`
`pscale`	$t$ prior scale. Defaults to `1/sqrt(2)`
`pdf`	$t$ prior degrees of freedom. Defaults to `1` (a Cauchy prior)
`type`	Type of $t$ -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 $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

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

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

Package 'bfpwr'

Help Index

z-test Bayes factor

Description

Usage

Arguments

Value

Author(s)

Examples

Sample size determination for z-test Bayes factor

Description

Usage

Arguments

Details

Value

Note

Author(s)

See Also

Examples

Normal moment prior Bayes factor

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Sample size determination for normal moment prior Bayes factor

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Sample size calculations for ttt-test Bayes factor

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Cumulative distribution function of the z-test Bayes factor

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Plot method for class "power.bftest"

Description

Usage

Arguments

Value

Author(s)

See Also

Examples

Cumulative distribution function of the normal moment prior Bayes factor

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

Power and sample size calculations for z-test Bayes factor

Description

Usage

Arguments

Details

Value

Note

Author(s)

Sample size calculations for $t$ -test Bayes factor

Plot method for class `"power.bftest"`

Power and sample size calculations for $t$ -test Bayes factor

Print method for class `"power.bftest"`