Perform sample size determination or the probability of obtaining compelling or misleading evidence for a Bayesian correlation test. Can handle both point-null and interval-null hypothesis, and allows specifying analysis and design priors.
BFpower.cor(
alternative,
h0,
ROPE = NULL,
threshold,
true_rate,
false_rate,
prior_analysis,
k,
alpha,
beta,
scale,
prior_design = NULL,
alpha_d,
beta_d,
location_d,
k_d,
scale_d,
N = NULL,
type_rate = "positive",
plot_power = FALSE,
plot_rel = FALSE
)A list of class BFpower_r containing:
type: Test type (always "Correlation").
alternative: the direction of the alternative hypothesis.
h0: the value of correlation under the null hypothesis.
ROPE: Bounds for interval null (if used).
analysis_h1: List with the analysis prior parameters: prior_analysis, k, alpha, beta, and scale.
design_h1: List with the design prior parameters: prior_design, k, alpha, beta, scale, and location.
results: Data frame with the probabilities of compelling/misleading evidence, and with the required sample size.
threshold: Threshold of compelling evidence.
plot_power: Logical, whether power curves are plotted.
plot_rel: Logical, whether the relationship between the BF and the correlation is plotted.
character. The direction of the alternative hypothesis being tested: two-sided ("two.sided"), right-sided ("greater"), or left-sided ("less").
Numeric scalar. Null rho correlation value. Must be between -0.8 and 0.8.
Optional numeric vector or scalar specifying bounds for an interval null; used if interval Bayes factor is calculated.
For alternative = "two.sided", must be a numeric vector of length 2 with distinct finite values.
For alternative = "greater", must be a single numeric scalar > 0.
For alternative = "less", must be a single numeric scalar < 0.
Numeric scalar. Threshold of compelling evidence (numeric scalar > 1).
Numeric scalar. Targeted true positive rate (if positive = "positive") or true negative rate (if positive = "negative").
Numeric scalar. Targeted false positive rate (if positive = "positive") or false negative rate (if positive = "negative").
character. Analysis prior under the alternative hypothesis:
default beta ("d_beta"), beta ("beta"), or normal moment ("Moment").
Numeric scalar. Parameter for the default beta prior ("d_beta").
Numeric scalar. Parameter for the beta prior ("beta").
Numeric scalar. Parameter for the beta prior ("beta").
Numeric scalar. Scale parameter for the normal moment prior ("Moment").
character. Design prior under the alternative hypothesis: default beta ("d_beta"), beta ("beta"), normal moment ("Moment"), or point ("Point").
Numeric scalar. Parameter for the design beta prior ("beta").
Numeric scalar. Parameter for the design beta prior ("beta").
Numeric scalar. Location parameter for the design point prior ("Point").
Numeric scalar. Parameter for the design default beta prior ("d_beta").
Numeric scalar. Scale parameter for the design normal moment prior ("Moment").
Numeric integer. Sample size. Only required if the goal is not sample size determination, but rather to calculate the probability of obtaining compelling or misleading evidence for a given sample size.
character. Character indicating which rate to control: "positive" (true/false positive rates) or "negative" (true/false negative rates).
Logical; if TRUE, plots power curves.
Logical; if TRUE, plots the relationship between the BF and data.
1. Sample size determination mode (when N = NULL):
If no sample size is provided, the function determines the minimum sample size required to meet the desired requirements. In this mode, the user must supply the following arguments:
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.
Hypothesis specification:
The alternative argument defines the direction of the alternative hypothesis : "two.sided" for two-sided, "greater" for right-sided, or "less" for left-sided tests. The optional ROPE argument specifies bounds for an interval null hypothesis. If ROPE = NULL, a point-null test is assumed.
Analysis Priors:
The analysis prior specifies the prior distribution of the correlation under the alternative hypothesis. Depending on prior_analysis, the user must supply:
d_beta (default beta): k > 0.
beta (stretched beta): alpha and beta > 0.
Moment (normal-moment prior): scale > 0.
Design Priors (optional):
A design prior can be supplied to reflect uncertainty about the correlation during study planning. If provided, prior_design must be one of "d_beta", "beta", "Moment", or "Point", and the corresponding parameters must be supplied:
d_beta: k_d > 0.
beta: alpha_d and beta_d > 0.
Moment: scale_d > 0.
Point: location_d numeric scalar.
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 BF and correlation is plotted.
BFpower.cor(
alternative = "greater",
h0 = 0,
threshold = 3,
true_rate = 0.8,
false_rate = 0.05,
prior_analysis = "d_beta",
k = 1,
prior_design = "Point",
location_d = 0.3,
plot_power = TRUE,
plot_rel = TRUE
)
Run the code above in your browser using DataLab