Package {BayesPower}

Bayes Factor for a Bayesian One-Proportion Test

Description

Calculate the Bayes factor (BF10) for a one-proportion test, either against a point null or an interval null hypothesis.

Usage

BF10.bin.test(
  n,
  x,
  h0,
  alternative,
  ROPE = NULL,
  prior_analysis,
  alpha,
  beta,
  scale
)

Arguments

Value

An object of class BFvalue containing:

• type: Character. Test type (always "One-proportion").

• bf10: Numeric scalar. The computed Bayes factor in favor of the alternative hypothesis relative to the null hypothesis.

• h0: Numeric scalar. Null proportion value.

• x: Non-negative integer scalar. Number of successes.

• n: Positive integer scalar. Sample size.

• analysis_h1: List describing the analysis prior, containing prior (prior distribution) alpha (alpha parameter), beta (beta parameter), location (location parameter being the same as h0 for the moment-normal prior),

• alternative: Character. The direction of the alternative hypothesis ("two.sided", "greater", or "less").

• ROPE: Optional numeric vector or scalar. Interval bounds under the null, if any.

• p.value: Numeric scalar. p-value.

Examples

BF10.bin.test(
 n = 52,
 x = 42,
 h0 = 0.5,
 alternative = "greater",
 prior_analysis = "beta",
 alpha = 1,
 beta = 1)

Bayes Factor for a Bayesian Correlation Test

Description

Calculate the Bayes factor (BF10) for a correlation coefficient, either against a point null or an interval null hypothesis. Supports default beta ("d_beta"), stretched beta ("beta"), and normal-moment ("Moment") priors for the alternative hypothesis.

Usage

BF10.cor(
  r,
  n,
  h0,
  alternative,
  ROPE = NULL,
  prior_analysis,
  k,
  alpha,
  beta,
  scale
)

Arguments

Value

A list with class BFvalue containing:

• type: Character. Test type (always "Correlation").

• bf10: Numeric scalar. The computed Bayes factor in favor of the alternative hypothesis relative to the null hypothesis.

• h0: Numeric scalar. Null value of the correlation.

• r: Numeric scalar. Observed correlation coefficient.

• n: Positive integer scalar. Sample size.

• analysis_h1: List with the analysis prior parameters: prior, k, alpha, beta,location (being the same as h0 for the moment-normal prior, otherwise it is NULL), and scale.

• alternative: Character. The direction of the alternative hypothesis ("two.sided", "greater", or "less").

• ROPE: Optional numeric vector or scalar. Interval bounds under the null, if any.

• p.value: Numeric scalar. p-value.

Examples

BF10.cor(
  r = 0.393,
  n = 46,
  h0 = 0,
  alternative = "two.sided",
  prior_analysis = "d_beta",
  k = 1)

Bayes Factor for a Bayesian F-Test

Description

Calculate the Bayes factor (BF10) for an F-test, comparing a full model to a reduced model under either an effect-size prior or a moment prior. Optionally, an interval null hypothesis can be specified.

Usage

BF10.f.test(fval, df1, df2, ROPE = NULL, prior_analysis, rscale, f_m, dff)

Arguments

Value

A list of class BFvalue containing:

• type: Character. Test type (always "Regression/ANOVA").

• bf10: Numeric scalar. The computed Bayes factor in favor of the alternative hypothesis relative to the null hypothesis.

• fval: Numeric scalar. Input F-value.

• df1, df2: Numeric scalar. Degrees of freedom.

• analysis_h1: List containing the analysis prior specification, including the prior distribution, the scale rscale, f_m, and degrees of freedom dff.

• ROPE: Optional numeric scalar. Interval bounds under the null, if any.

• p.value: Numeric scalar. p-value.

Examples

BF10.f.test(
  fval = 4.5,
  df1 = 2,
  df2 = 12,
  dff = 12,
  prior_analysis = "effectsize",
  rscale = 0.707,
  f_m = 0.1)

Bayes Factor for Comparing Two Proportions

Description

Compute the Bayes factor (BF10) for a Bayesian test of two proportions.

Usage

BF10.props(N1, x1, N2, x2, a0, b0, a1, b1, a2, b2)

Arguments

Value

A list of class BFvalue containing:

• type: Character. Test type (always "Two-proportions").

• bf10: Numeric scalar. The computed Bayes factor in favor of the alternative hypothesis relative to the null hypothesis.

• N1: Positive integer scalar. Sample size for group 1.

• x1: Non-negative integer scalar. Observed successes for group 1.

• N2: Positive integer scalar. Sample size for group 2.

• x2: Non-negative integer scalar. Observed successes for group 2.

• analysis_h0: list with a (alpha parameter) and b (beta parameter) for the null prior.

• analysis_h1_theta_1: list with a (alpha parameter) and b (beta parameter) for group 1 prior under H1.

• analysis_h1_theta_2: list with a (alpha parameter) and b (beta parameter) for group 2 prior under H1.

• OddsRatio: Numeric scalar. Observed odds ratio.

• p.value: Numeric scalar. p-value.

Examples

BF10.props(
N1 = 493,
x1 = 155,
N2 = 488,
x2 = 150,
a0 = 1,
b0 = 1,
a1 = 1,
b1 = 1,
a2 = 1,
b2 = 1)

Bayes Factor for a One-Sample Bayesian t-Test

Description

Calculate the Bayes factor (BF10) for a one-sample t-test, comparing an observed t-value against either a point null hypothesis or an interval null hypothesis.

Usage

BF10.ttest.OneSample(
  tval,
  df,
  alternative,
  ROPE = NULL,
  prior_analysis,
  location,
  scale,
  dff
)

Arguments

Value

A list of class BFvalue containing:

• type: Character. Test type (always "One-sample t-test").

• bf10: Numeric scalar. The computed Bayes factor in favor of the alternative hypothesis relative to the null hypothesis.

• tval: Numeric scalar. Observed t-value.

• df: Numeric scalar. Degrees of freedom.

• analysis_h1: List with the analysis prior parameters: prior (prior distribution), location, scale, and optionally dff.

• alternative: Character. the direction of the alternative hypothesis.

• ROPE: Optional numeric vector or scalar. Interval bounds under the null, if any.

• d: Numeric scalar. Observed Cohen's d.

• p.value: Numeric scalar. p-value.

Examples

BF10.ttest.OneSample(
tval = 2,
df = 50,
alternative = "two.sided",
prior_analysis = "t-distribution",
location = 0,
scale = 0.707,
dff = 1)

Bayes Factor for a Two-Sample Bayesian t-Test

Description

Calculate the Bayes factor (BF10) for a two-sample independent t-test with equal variances. Supports both point-null and interval-null hypotheses.

Usage

BF10.ttest.TwoSample(
  tval,
  N1,
  N2,
  alternative,
  ROPE = NULL,
  prior_analysis,
  location,
  scale,
  dff
)

Arguments

Value

A list of class BFvalue containing:

• type: Character. Test type (always "Independent-samples t-test (equal variance)").

• bf10: Numeric scalar. The computed Bayes factor in favor of the alternative hypothesis relative to the null hypothesis.

• tval: Numeric scalar. Observed t-value.

• df: Numeric scalar. Degrees of freedom.

• analysis_h1: List with the analysis prior parameters: prior (prior distribution), location, scale, and optionally dff.

• alternative: Character. The direction of the alternative hypothesis ("two.sided", "greater", or "less").

• ROPE: Optional numeric vector or scalar. Interval bounds under the null, if any.

• N1: Positive integer scalar. Sample size of group 1.

• N2: Positive integer scalar. Sample size of group 2.

• d: Numeric scalar. Observed Cohen's d.

• p.value: Numeric scalar. p-value.

Examples

BF10.ttest.TwoSample(
 tval = -1.148,
 N1 = 53,
 N2 = 48,
 alternative = "two.sided",
 ROPE = c(-0.36,0.36),
 prior_analysis = "t-distribution",
 location = 0,
 scale = 0.707,
 dff = 1)

Sample Size Determination for the Bayesian One-Proportion Test

Description

Perform sample size determination or power calculation of compelling and misleading evidence for a Bayesian test of a single proportion. Can handle both point-null and interval-null hypothesis, and allows specifying analysis and design priors.

Usage

BFpower.bin(
  threshold,
  type_rate = "positive",
  true_rate,
  false_rate,
  N = NULL,
  h0,
  alternative,
  ROPE = NULL,
  prior_analysis,
  alpha,
  beta,
  scale,
  prior_design = NULL,
  alpha_d,
  beta_d,
  location_d,
  scale_d
)

Arguments

Details

Sample Size Determination Mode (when N = NULL):

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

• threshold - the Bayes factor threshold for compelling evidence (must be \ge 1).

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

The function iteratively finds the smallest sample size for which the probability of obtaining compelling evidence (i.e., true positive/negative rate) meets or exceeds true_rate, while the probability of misleading evidence (i.e., false positive/negative rate) does not exceed false_rate.

Fixed-sample Analysis Mode (when N is supplied):

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

Direction of the Alternative Hypothesis:

The argument alternative specifies the direction of the test and can be set to "two.sided", "greater", or "less".

Interval Null Hypothesis:

The interval null hypothesis can be specified using the argument ROPE, which defines a region of practical equivalence around the null value of h0. Thus, ROPE defines the interval of values considered practically equivalent to the null value by h0 + ROPE.

The required form of ROPE depends on the direction of alternative:

• For alternative = "two.sided", argument ROPE must be a numeric vector of length 2 with two distinct finite values such that the first element is negative and the second element is positive (i.e., ROPE[1] < 0 < ROPE[2]). The resulting region of practical equivalence is [h0 + ROPE[1], h0 + ROPE[2]]. Example: If h0 = 0.5, alternative = "two.sided", ROPE = c(-0.2, 0.2), then the region of practical equivalence is [0.3, 0.7].

• For alternative = "greater", argument ROPE must be a numeric scalar > 0, the interval null extends from h0 to h0 + ROPE. Example: If h0 = 0.5, alternative = "greater", ROPE = 0.2, then the region of practical equivalence is [0.5, 0.7].

• For alternative = "less", argument ROPE must be a numeric scalar < 0, the interval null extends from h0 + ROPE to h0. Example: If h0 = 0.5, alternative = "less", ROPE = -0.2, then the region of practical equivalence is [0.3, 0.5].

If ROPE = NULL, a point-null hypothesis is assumed.

Analysis Priors:

The user must specify the analysis prior under the alternative hypothesis using prior_analysis:

• beta (beta prior): alpha and beta > 0.

• Moment (normal-moment prior) : scale > 0.

Design Priors (optional):

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

• beta: requires alpha_d > 0 and beta_d > 0.

• Moment: requires scale_d > 0 and 0 < location_d < 1.

• Point: requires direction-specific constraints on location_d: for "greater", h0 < location_d < 1; for "less", 0 < location_d < h0; and for "two.sided", 0 < location_d < 1 and location_d != h0.

If prior_design is NULL, the analysis prior is used as the design prior.

Value

A list of class BFpower containing:

• type: Character. Test type (always "One-proportion").

• threshold: Numeric scalar. Compelling-evidence threshold.

• h0: Numeric scalar. Null proportion value.

• alternative: Character. The direction of the alternative hypothesis ("two.sided", "greater", or "less").

• ROPE: Optional numeric vector or scalar. Interval bounds under the null, if any.

• analysis_h1: List describing the analysis prior, containing prior (prior distribution) alpha (alpha parameter), beta (beta parameter), location (location parameter being the same as h0 for the moment-normal prior), and scale (scale parameter).

• design_h1: List describing the design prior, containing, the list contains prior (prior distribution), alpha (alpha parameter), beta (beta parameter), location (location parameter), and scale (scale parameter).

• results: Data frame of probabilities of compelling/misleading evidence and the required or supplied sample size.

• setting: List containing mode_bf, indicating whether sample size determination (1) or power calculation (0) is performed, and same.priors, indicating whether the design and analysis priors are the same (1) or not the same (0).

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

Examples

BFpower.bin(
  alternative = "greater",
  threshold = 3,
  true_rate = 0.8,
  false_rate = 0.05,
  h0 = 0.5,
  prior_analysis = "beta",
  alpha = 1,
  beta = 1)

Sample Size Determination for the Bayesian Correlation Test

Description

Perform sample size determination or power calculation of compelling and misleading evidence for a Bayesian correlation test. Can handle both point-null and interval-null hypothesis, and allows specifying analysis and design priors.

Usage

BFpower.cor(
  threshold,
  type_rate = "positive",
  true_rate,
  false_rate,
  N = NULL,
  h0,
  alternative,
  ROPE = NULL,
  prior_analysis,
  k,
  alpha,
  beta,
  scale,
  prior_design = NULL,
  k_d,
  alpha_d,
  beta_d,
  location_d,
  scale_d
)

Arguments

Details

Sample Size Determination Mode (when N = NULL):

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

• threshold - the Bayes factor threshold for compelling evidence (must be \ge 1).

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

The function iteratively finds the smallest sample size for which the probability of obtaining compelling evidence (i.e., true positive/negative rate) meets or exceeds true_rate, while the probability of misleading evidence (i.e., false positive/negative rate) does not exceed false_rate.

Fixed-sample Analysis Mode (when N is supplied):

If a positive integer 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.

Direction of the Alternative Hypothesis:

The argument alternative specifies the direction of the test and can be set to "two.sided", "greater", or "less".

Interval Null Hypothesis:

The interval null hypothesis can be specified using the argument ROPE, which defines a region of practical equivalence around the null value of h0. Thus, ROPE defines the interval of values considered practically equivalent to the null value by h0 + ROPE.

The required form of ROPE depends on the direction of alternative:

• For alternative = "two.sided", argument ROPE must be a numeric vector of length 2 with two distinct finite values such that the first element is negative and the second element is positive (i.e., ROPE[1] < 0 < ROPE[2]). The resulting region of practical equivalence is [h0 + ROPE[1], h0 + ROPE[2]]. Example: If h0 = 0.1, alternative = "two.sided", ROPE = c(-0.2, 0.2), then the region of practical equivalence is [-0.1, 0.3].

• For alternative = "greater", argument ROPE must be a numeric scalar > 0, the interval null extends from h0 to h0 + ROPE. Example: If h0 = 0.1, alternative = "greater", ROPE = 0.2, then the region of practical equivalence is [0.1, 0.3].

• For alternative = "less", argument ROPE must be a numeric scalar < 0, the interval null extends from h0 + ROPE to h0. Example: If h0 = 0.1, alternative = "less", ROPE = -0.2, then the region of practical equivalence is [-0.1, 0.1].

If ROPE = NULL, a point-null hypothesis is assumed.

Analysis Priors:

The user must specify the analysis prior under the alternative hypothesis using prior_analysis:

• d_beta (default beta): k > 0.

• beta (stretched beta): alpha and beta > 0.

• Moment (normal-moment prior): scale > 0.

Design Priors (optional):

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

• d_beta (default beta): requires k_d > 0.

• beta (stretched beta): requires alpha_d > 0 and beta_d > 0.

• Moment (normal-moment prior): requires scale_d > 0 and -1 < location_d < 1.

• Point: requires direction-specific constraints on location_d: for "greater", h0 < location_d < 1; for "less", -1 < location_d < h0; and for "two.sided", -1 < location_d < 1 and location_d != h0.

If prior_design is NULL, the analysis prior is used as the design prior.

Value

A list of class BFpower containing:

• type: Character. Test type (always "Correlation").

• threshold: Numeric scalar. Threshold of compelling evidence.

• h0: Numeric scalar. the value of correlation under the null hypothesis.

• alternative: Character. The direction of the alternative hypothesis ("two.sided", "greater", or "less").

• ROPE: Optional numeric vector or scalar. Interval bounds under the null, if any.

• analysis_h1: List with the analysis prior parameters: prior, k, alpha, beta,location (being the same as h0 for the moment-normal prior, otherwise it is NULL), and scale.

• design_h1: List with the design prior parameters: prior, k, alpha, beta, location, and scale.

• results: Data frame with the probabilities of compelling/misleading evidence, and with the required sample size.

• setting: List containing mode_bf, indicating whether sample size determination (1) or power calculation (0) is performed, and same.priors, indicating whether the design and analysis priors are the same (1) or not the same (0).

Examples

BFpower.cor(
   threshold = 3,
   true_rate = 0.8,
   false_rate = 0.05,
   h0 = 0,
   alternative = "greater",
   prior_analysis = "d_beta",
   k = 1,
   prior_design = "Point",
   location_d = 0.3)

Sample Size Determination for the Bayesian F-Test

Description

Perform sample size determination or power calculation of compelling and misleading evidence for a Bayesian F-test comparing a full model to a nested reduced model. Can handle both point-null and interval-null hypothesis, and allows specifying analysis and design priors.

Usage

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

Arguments

Details

Sample Size Determination Mode (when N = NULL):

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

• threshold - the Bayes factor threshold for compelling evidence (must be \ge 1).

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

The function iteratively finds the smallest sample size for which the probability of obtaining compelling evidence (i.e., true positive/negative rate) meets or exceeds true_rate, while the probability of misleading evidence (i.e., false positive/negative rate) does not exceed false_rate.

Fixed-sample Analysis Mode (when N is supplied):

If a positive integer sample size N is provided, the function computes the probabilities of obtaining compelling or misleading evidence for that fixed sample size. In this mode, type_rate, true_rate, and false_rate are ignored; only the Bayes factor threshold threshold is used. The supplied N must satisfy N >= k + 1.

Interval Null Hypothesis:

The interval null hypothesis can be specified using the argument ROPE, which defines the upper bound of the region of practical equivalence, whose lower bound is fixed at zero. Thus, ROPE defines the interval of values considered practically equivalent to the null value. If provided, it must be positive.

Example: If ROPE = 0.2, then the effective null interval is [0, 0.2].

If ROPE = NULL, a point-null hypothesis is assumed.

Analysis Priors:

The user must specify the analysis prior under the alternative hypothesis using prior_analysis:

• effectsize (effect size prior): rscale > 0, f_m > 0, and dff > 0.

• Moment (normal-moment prior): f_m > 0 and dff >= 3.

Design Priors (optional):

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

• effectsize (effect size prior): rscale_d > 0, f_m_d > 0, and dff_d > 0.

• Moment (normal-moment prior): f_m_d > 0 and dff_d >= 3.

• Point (point prior): f_m_d > 0.

If prior_design is NULL, the analysis prior is used as the design prior.

Value

A list of class BFpower containing:

• type: Character. Test type (always "Regression/ANOVA").

• threshold: Numeric scalar. Threshold of compelling evidence.

• p: Numeric integer. Number of predictors in the reduced model.

• k: Numeric integer. Number of predictors in the full model (must satisfy k > p).

• ROPE: Optional numeric scalar. Interval bounds under the null, if any.

• analysis_h1: List containing the analysis prior specification, including the prior distribution prior, the scale rscale, f_m, and degrees of freedom dff.

• design_h1: List containing the design prior specification, including the prior distribution prior, the scale rscale, f_m, and degrees of freedom dff.

• results: Data frame of probabilities of compelling/misleading evidence and the required or supplied sample size.

• setting: List containing mode_bf, indicating whether sample size determination (1) or power calculation (0) is performed, and same.priors, indicating whether the design and analysis priors are the same (1) or not the same (0).

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

Examples

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

Sample Size Determination for the Bayesian Test of Two Proportions

Description

Perform sample size determination or power calculation of compelling and misleading evidence for a Bayesian test of two proportions. Under the null hypothesis, \theta_1 = \theta_2 and it is assigned a shared analysis beta prior. Under the alternative hypothesis, \theta_1 and \theta_2 are treated as distinct parameters and are assigned independent beta analysis priors. The function supports the specification of beta and point design priors.

Usage

BFpower.props(
  threshold,
  type_rate = "positive",
  true_rate,
  N1 = NULL,
  N2 = NULL,
  a0,
  b0,
  a1,
  b1,
  a2,
  b2,
  prior_design_1 = "same",
  a1d,
  b1d,
  dp1,
  prior_design_2 = "same",
  a2d,
  b2d,
  dp2
)

Arguments

Details

Sample Size Determination Mode (when N1 = NULL and N2 = NULL):

If no sample sizes are provided for the two groups, the function calculates the minimum sample sizes needed to achieve the desired configuration. The user must provide:

• threshold - the Bayes factor threshold for compelling evidence (must be \ge 1).

• type_rate - either "positive" to control true positive rates or "negative" to control true negative rates.

• true_rate - the targeted true positive or true negative rate (between 0.6 and 0.999).

The function iteratively finds the smallest sample sizes for which the probability of obtaining compelling evidence (i.e., true positive/negative rate) meets or exceeds true_rate.

Fixed-sample Analysis Mode (when N1 and N2 are supplied):

If positive integer sample sizes N1 and N2 are provided, the function computes the probabilities of obtaining compelling or misleading evidence for these fixed sample sizes. In this mode, type_rate and true_rate are ignored; only the Bayes factor threshold threshold is used.

Analysis Priors:

The user must specify the analysis priors under the null and alternative hypotheses:

• Null hypothesis: Beta prior with parameters a0 and b0.

• Alternative hypothesis:

  • Group 1: Beta prior with parameters a1 and b1.

  • Group 2: Beta prior with parameters a2 and b2.

Design Priors (optional):

Design priors for the alternative hypothesis can optionally be specified:

• Group 1 design prior (prior_design_1):

  • "same": uses the corresponding analysis prior (a1, b1).

  • "beta" (beta prior): requires parameters a1d and b1d.

  • "Point" (point prior): requires fixed proportion dp1.

• Group 2 design prior (prior_design_2):

  • "same": uses the corresponding analysis prior (a2, b2).

  • "beta" (beta prior): requires parameters a2d and b2d.

  • "Point" (point prior): requires fixed proportion dp2.

Value

A list of class BFpower containing:

• type: Character. Test type (always "Two-proportions").

• threshold: Numeric scalar. Threshold of compelling evidence.

• analysis_h0: List of analysis prior parameters under the null, containing a and b.

• analysis_h1_theta_1: List of analysis prior parameters for group 1 under the alternative, containing a and b.

• analysis_h1_theta_2: List of analysis prior parameters for group 2 under the alternative, containing a and b.

• design_h1_theta_1: List describing the design prior for group 1 under the alternative hypothesis. The list contains prior (prior distribution), a (alpha parameter), b (beta parameter), and p (point-prior proportion).

• design_h1_theta_2: List describing the design prior for group 2 under the alternative hypothesis. The list contains prior (prior distribution), a (alpha parameter), b (beta parameter), and p (point-prior proportion).

• results: Data frame of probabilities of compelling and misleading evidence.

• grid: Grid used internally for the computation of the results (i.e., true/false positive and negative rates) and the plot method.

• mode_bf: Numeric scalar. Indicates whether sample size determination (1) or power calculation (0) is performed. This output is only used internally in the print method.

Examples

BFpower.props(
threshold = 3,
true_rate = 0.8,
a0 = 1,
b0 = 1,
a1 = 156,
b1 = 339,
a2 = 151,
b2 = 339)

Sample Size Determination for the One-Sample Bayesian t-Test

Description

Perform sample size determination or power calculation of compelling and misleading evidence for a one-sample Bayesian t-test. Can handle both point-null and interval-null hypothesis, and allows specifying analysis and design priors.

Usage

BFpower.ttest.OneSample(
  threshold,
  type_rate = "positive",
  true_rate,
  false_rate,
  N = NULL,
  alternative,
  ROPE = NULL,
  prior_analysis,
  location,
  scale,
  dff,
  prior_design = NULL,
  location_d,
  scale_d,
  dff_d
)

Arguments

Details

Sample Size Determination Mode (when N = NULL):

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

• threshold - the Bayes factor threshold for compelling evidence (must be \ge 1).

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

The function iteratively finds the smallest sample size for which the probability of obtaining compelling evidence (i.e., true positive/negative rate) meets or exceeds true_rate, while the probability of misleading evidence (i.e., false positive/negative rate) does not exceed false_rate.

Fixed-sample Analysis Mode (when N is supplied):

If a positive integer 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.

Direction of the Alternative Hypothesis:

The argument alternative specifies the direction of the test and can be set to "two.sided", "greater", or "less".

Interval Null Hypothesis:

The interval null hypothesis can be specified using the argument ROPE, which defines a region of practical equivalence around the null value of 0.

The required form of ROPE depends on the direction of alternative:

• For alternative = "two.sided", argument ROPE must be a numeric vector of length 2 with two distinct finite values such that the first element is negative and the second element is positive (i.e., ROPE[1] < 0 < ROPE[2]). Example: If alternative = "two.sided" and ROPE = c(-0.2, 0.2), then the region of practical equivalence is [-0.2, 0.2].

• For alternative = "greater", argument ROPE must be a numeric scalar > 0. Example: If alternative = "greater" and ROPE = 0.2, then the region of practical equivalence is [0, 0.2].

• For alternative = "less", argument ROPE must be a numeric scalar < 0.Example: If alternative = "less" and ROPE = -0.2, then the region of practical equivalence is [-0.2, 0].

If ROPE = NULL, a point-null hypothesis is assumed.

Analysis Priors:

The user must specify the analysis prior under the alternative hypothesis using prior_analysis:

• Normal (normal prior): location with scale > 0.

• Moment (normal-moment prior): location with scale > 0.

• t-distribution (scaled t prior): location, scale > 0, and dff > 0.

Design Priors (optional):

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

• Normal (normal prior): location_d with scale_d > 0.

• Moment (normal-moment prior): location_d with scale_d > 0.

• t-distribution (scaled t prior): location_d with scale_d > 0, and dff_d > 0.

• Point (point prior): location_d.

If prior_design is NULL, the analysis prior is used as the design prior.

Value

An object of class BFpower containing:

• type: Character. Test type (always "One-sample t-test").

• threshold: Numeric scalar. threshold of compelling evidence.

• alternative: Character. The direction of the alternative hypothesis ("two.sided", "greater", or "less").

• ROPE: Optional numeric vector or scalar for interval null bounds.

• analysis_h1: List with the analysis prior parameters: prior, location, scale, and optionally dff.

• design_h1: List with the design prior parameters: prior, location, scale, and optionally dff.

• results: Data frame of probabilities: compelling/misleading evidence.

• setting: List containing mode_bf, indicating whether sample size determination (1) or power calculation (0) is performed, and same.priors, indicating whether the design and analysis priors are the same (1) or not the same (0).

Examples

BFpower.ttest.OneSample(
 threshold = 3,
 true_rate = 0.8,
 false_rate = 0.05,
 alternative = "two.sided",
 prior_analysis = "t-distribution",
 location = 0,
 scale = 0.707,
 dff = 1
)

Sample Size Determination for the Two-Sample Bayesian t-Test

Description

Perform sample size determination or power calculation of compelling and misleading evidence for a two-sample Bayesian t-test with equal variances. Can handle both point-null and interval-null hypothesis, and allows specifying analysis and design priors.

Usage

BFpower.ttest.TwoSample(
  threshold,
  type_rate = "positive",
  true_rate,
  false_rate,
  N1 = NULL,
  N2 = NULL,
  r = NULL,
  alternative,
  ROPE = NULL,
  prior_analysis,
  location,
  scale,
  dff,
  prior_design = NULL,
  location_d,
  scale_d,
  dff_d
)

Arguments

Details

Sample size determination mode (when N1 = NULL and N2 = NULL, but r is provided):

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

• threshold - the Bayes factor threshold for compelling evidence (must be at least 1).

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

• r - the allocation ratio of group 2 to group 1 sample sizes (N2/N1).

The function iteratively finds the smallest sample size N1 and N2 = r * N1 for which the probability of obtaining compelling evidence (i.e., true positive/negative rate) meets or exceeds true_rate, while the probability of misleading evidence (i.e., false positive/negative rate) does not exceed false_rate.

Fixed-sample analysis mode (when N1 and N2 are supplied):

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

Direction of the Alternative Hypothesis:

The argument alternative specifies the direction of the test and can be set to "two.sided", "greater", or "less".

Interval Null Hypothesis:

The interval null hypothesis can be specified using the argument ROPE, which defines a region of practical equivalence around the null value of 0.

The required form of ROPE depends on the direction of alternative:

• For alternative = "two.sided", argument ROPE must be a numeric vector of length 2 with two distinct finite values such that the first element is negative and the second element is positive (i.e., ROPE[1] < 0 < ROPE[2]). Example: If alternative = "two.sided" and ROPE = c(-0.2, 0.2), then the region of practical equivalence is [-0.2, 0.2].

• For alternative = "greater", argument ROPE must be a numeric scalar > 0. Example: If alternative = "greater" and ROPE = 0.2, then the region of practical equivalence is [0, 0.2].

• For alternative = "less", argument ROPE must be a numeric scalar < 0.Example: If alternative = "less" and ROPE = -0.2, then the region of practical equivalence is [-0.2, 0].

If ROPE = NULL, a point-null hypothesis is assumed.

Analysis Priors:

The user must specify the analysis prior under the alternative hypothesis using prior_analysis:

• Normal (normal prior): location with scale > 0.

• Moment (normal-moment prior): scale > 0.

• t-distribution (scaled t prior): location with scale > 0, and dff > 0.

Design Priors (optional):

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

• Normal (normal prior): location_d with scale_d > 0.

• Moment (normal-moment prior): location_d with scale_d > 0.

• t-distribution (scaled t prior): location_d with scale_d > 0, and dff_d > 0.

• Point (point prior): location_d.

If prior_design is NULL, the analysis prior is used as the design prior.

Value

An object of class BFpower containing:

• type: Character. Test type (always "Independent-samples t-test (equal variance)").

• threshold: Numeric scalar. Threshold of compelling evidence.

• alternative: Character. The direction of the alternative hypothesis ("two.sided", "greater", or "less").

• ROPE: Optional numeric vector or scalar. Interval bounds under the null, if any.

• analysis_h1: List with the analysis prior parameters: prior, location, scale, and optionally dff.

• design_h1: List with the design prior parameters: prior, location, scale, and optionally dff.

• results: Data frame with probabilities of compelling/misleading evidence.

• setting: List containing mode_bf, indicating whether sample size determination (1) or power calculation (0) is performed, and same.priors, indicating whether the design and analysis priors are the same (1) or not the same (0).

Examples

BFpower.ttest.TwoSample(
 threshold = 3,
 type_rate = "negative",
 true_rate = 0.8,
 false_rate = 0.05,
 r = 1,
 alternative = "two.sided",
 ROPE = c(-0.36, 0.36),
 prior_analysis = "Normal",
 location = -0.23,
 scale = 0.2,
 dff = 1)

Launch the BayesPower Shiny Application

Description

This function starts the interactive Shiny application for Bayesian power analysis using Bayes factors. The app provides a graphical user interface built with shiny.

Usage

BayesPower_BayesFactor()

Details

The application includes both the UI and server components, which are defined internally in the package. When run, a browser window or RStudio viewer pane will open to display the interface.

Value

No return value, called for its side effects.

Examples

if (interactive()) {
  # Launch the Shiny application
  BayesPower_BayesFactor()
}

Plot Method for BFpower Objects

Description

Visualizes a "BFpower" object.

Usage

## S3 method for class 'BFpower'
plot(x, plot_power = FALSE, plot_rel = FALSE, ...)

Arguments

Details

This plot method can return up to three plots (or five plots for testing two-proportions) based on the information from the "BFpower" object:

• The first plot displays the analysis prior and the design prior. However, for BFpower.props, three plots are returned, corresponding to the three thetas.

• The second plot contains two panels where the left panel shows the true and false positive rates as a function of sample size, and the right panel shows the true and false negative rates.

• The third plot illustrates the relationship between the data and the Bayes factors.

The object can be generated by any of the following functions: BF10.ttest.OneSample, BF10.ttest.TwoSample, BF10.cor, BFpower.f.test, BF10.bin.test, or BF10.props.

Value

A list of up to three ggplot objects.

Examples

results <- BFpower.cor(
  alternative = "greater",
  h0 = 0,
  threshold = 3,
  true_rate = 0.8,
  false_rate = 0.05,
  prior_analysis = "beta",
  alpha = 1,
  beta = 1,
  prior_design = "Point",
  location_d = 0.3
)
print(results)
plot(results, plot_power = TRUE, plot_rel = TRUE)

Print Method for BFpower Objects

Description

Displays the results of a "BFpower" object.

Usage

## S3 method for class 'BFpower'
print(x, ...)

Arguments

Details

This method prints key information from the "BFpower" object, including the type of hypothesis specification, priors, true and false rates, and required sample. The object can be generated by any of the following functions: BFpower.ttest.OneSample, BFpower.ttest.TwoSample, BFpower.cor, BFpower.f.test, BFpower.bin, or BFpower.props.

Value

Invisibly returns the input "BFpower" object.

Examples

results <- BFpower.ttest.OneSample(
  alternative = "two.sided",
  threshold = 3,
  true_rate = 0.8,
  false_rate = 0.05,
  prior_analysis = "t-distribution",
  location = 0,
  scale = 0.707,
  dff = 1
)
print(results)

Print Method for BFvalue Objects

Description

Displays the results of a "BFvalue" object.

Usage

## S3 method for class 'BFvalue'
print(x, ...)

Arguments

Details

This method prints key results from a Bayesian test, including the Bayes factor and relevant test statistics with frequentist test result. The object can be generated by any of the following functions: BF10.ttest.OneSample, BF10.ttest.TwoSample, BF10.cor, BFpower.f.test BF10.bin.test, or BF10.props.

Value

Invisibly returns the input "BFvalue" object.

Examples

result <- BF10.ttest.OneSample(
 tval = 2,
 df = 50,
 prior_analysis = "t-distribution",
 location = 0,
 scale = 0.707,
 dff = 1,
 alternative = "two.sided")
print(result)