BFpower.f.test: Sample Size Determination for the Bayesian F-test

Description

This function performs sample size determination (when N = NULL) or calculates the probability of compelling/misleading evidence for a fixed sample size.

Usage

BFpower.f.test(
  threshold,
  true_rate,
  false_rate,
  p,
  k,
  prior_analysis,
  dff,
  rscale,
  f_m,
  prior_design = NULL,
  dff_d,
  rscale_d,
  f_m_d,
  N = NULL,
  type_rate = "positive",
  ROPE = NULL,
  plot_power = FALSE,
  plot_rel = FALSE
)

Value

A list of class BFpower_f containing:

type: Test type (always "Regression/ANOVA").
k, p: Number of predictors in the full and reduced models.
ROPE: Bounds for interval null (if used).
analysis_h1: List containing the analysis prior specification, including the prior distribution, the scale rscale, f f_m, and degrees of freedom dff.
design_h1: List containing the design prior specification, including the prior distribution, the scale rscale, f f_m, and degrees of freedom dff (or NULL if not specified).
results: Data frame of probabilities of compelling/misleading evidence and the required or supplied sample size.
threshold: Threshold of compelling evidence.
plot_power: Logical; whether power curves are plotted.
plot_rel: Logical; whether the relationship between the Bayes factor and data is plotted.

If sample size determination fails, the function returns NaN and prints a message.

Arguments

threshold: Numeric scalar. Threshold for compelling evidence (must be > 1).
true_rate: Numeric scalar. Targeted true positive or true negative rate (used only when sample size determination is requested; N = NULL).
false_rate: Numeric scalar. Targeted false positive or false negative rate (used only when sample size determination is requested; N = NULL).
p: Numeric integer. Number of predictors in the reduced model.
k: Numeric integer. Number of predictors in the full model (must satisfy k > p).
prior_analysis: Character. Analysis prior model under the alternative hypothesis: "effectsize" or "Moment".
dff: Numeric scalar. Degrees of freedom for the analysis prior under the alternative hypothesis. Must be a positive scalar, and must be at least 3 if prior_analysis = "Moment".
rscale: Numeric scalar. Scale parameter for the analysis effect-size prior (only used when prior_analysis = "effectsize").
f_m: Numeric scalar. Cohen's \(f\) effect-size parameter for the analysis prior (must be > 0).
prior_design: Character. Design prior model under the alternative hypothesis: "effectsize", "Moment", or "Point".
dff_d: Numeric scalar. Degrees of freedom for the design prior. Must be a positive scalar, and at least 3 if prior_design = "Moment".
rscale_d: Numeric scalar. Scale parameter for the design effect-size prior (only used when prior_design = "effectsize").
f_m_d: Numeric scalar. Cohen's \(f\) value for the design prior or the effect-size of the point design prior.
N: Numeric integer. Sample size. If NULL, sample size determination is performed.
type_rate: Character. Either "positive" (control true/false positive rates) or "negative" (control true/false negative rates).
ROPE: Numeric vector. Numeric bounds for the interval null (only used when interval Bayes factors are required).
plot_power: Logical. Whether to plot power curves when sample size determination is requested.
plot_rel: Logical. Whether to plot the relationship between the BF and data.

Details

Computes required sample size or probabilities of compelling or misleading evidence for a fixed sample size.

1. Sample size determination mode (when N = NULL):

If no sample size is provided, the function calculates the minimum sample size to achieve the desired configuration below. The user must provide:

type_rate - either "positive" to control true/false positive rates, or "negative" to control true/false negative rates.
true_rate - the targeted true positive or true negative rate (between 0.6 and 0.999).
false_rate - the acceptable false positive or false negative rate (between 0.001 and 0.1).
threshold - the Bayes factor threshold for compelling evidence (must be > 1).

The function iteratively finds the smallest sample size for which the probability of obtaining compelling evidence meets or exceeds true_rate, while the probability of misleading evidence does not exceed false_rate.

2. Fixed-sample analysis mode (when N is supplied):

If a positive numeric sample size N is provided, the function computes the probabilities of obtaining compelling or misleading evidence for that fixed sample size. In this mode, the arguments type_rate, true_rate, and false_rate are ignored; only the Bayes factor threshold threshold is used.

Model specification:

The function requires the user to specify the full model (k predictors) and the reduced model (p predictors, k > p), and the analysis prior under the alternative hypothesis. Depending on the chosen prior_analysis, different arguments are required:

prior_analysis = "effectsize": requires rscale (scale parameter) and f_m (Cohen's f effect-size), and dff (degrees of freedom).
prior_analysis = "Moment": requires f_m (Cohen's f effect-size) and dff (degrees of freedom, must be >= 3); rscale is not used.

The design prior under the alternative hypothesis can optionally be specified using prior_design, which can be:

"effectsize": requires rscale_d, f_m_d, and dff_d.
"Moment": requires f_m_d and dff_d (>=3); rscale_d is not used.
"Point": requires f_m_d only; rscale_d and dff_d are not used.

interval null Hypothesis:

If ROPE is provided, the function evaluates the Bayes factor for an interval null. Otherwise, a point-null hypothesis is assumed.

Plotting:

If plot_power = TRUE, the function plots the probability of compelling evidence as a function of sample size. If plot_rel = TRUE, the relationship between the Bayes factor and Cohen's f is plotted.

Examples

Run this code

BFpower.f.test(
 threshold = 3,
 true_rate = 0.8,
 false_rate = 0.05,
 p = 3,
 k = 4,
 prior_analysis = "effectsize",
 dff = 3,
 rscale = 0.18,
 f_m = 0.1,
 prior_design = "Point",
 f_m_d = 0.1,
 plot_power = TRUE,
 plot_rel = TRUE)

Run the code above in your browser using DataLab