Package {bfbin2arm}

bfbin2arm: Bayesian Power for Two-Arm Binomial Bayes Factors

Description

Functions for Bayesian power and sample size calculation in two-arm binomial trials using Bayes factors for point-null and directional hypotheses.

Details

The package provides simulation-free and simulation-based methods to calibrate Bayes factor designs in two-arm phase II trials with binary endpoints, including power and type-I-error calculations and visualization tools.

Author(s)

Maintainer: Riko Kelter rkelter@uni-koeln.de

See Also

Useful links:

• https://arxiv.org/abs/2511.23144

• https://arxiv.org/abs/2603.01715

• https://arxiv.org/abs/2502.02914

Check sustained feasibility over future n

Description

Given vectors of operating characteristics over n, check whether power, type-I-error, and CE(H0) satisfy their thresholds at n and for at least sustain_n subsequent sample sizes.

Usage

.sustained_singlearm_feasibility(
  n_vec,
  power_vec,
  type1_vec,
  ce_vec,
  target_power,
  target_type1,
  target_ce,
  sustain_n
)

Arguments

Value

Logical vector of length length(n_vec): TRUE if n_i and the next sustain_n sample sizes satisfy all active constraints.

Bayes factor BF-0: H- vs H0

Description

Bayes factor BF-0: H- vs H0

Usage

BFminus0(BFminus1, BF01)

Arguments

Value

Numeric scalar, BF_{-0}.

Bayes factor BF-1: H- vs H1

Description

Bayes factor BF-1: H- vs H1

Usage

BFminus1(y1, y2, n1, n2, a_1_a = 1, b_1_a = 1, a_2_a = 1, b_2_a = 1)

Arguments

Value

Numeric scalar, BF_{-1}.

Bayes factor BF+0: H+ vs H0

Description

Bayes factor BF+0: H+ vs H0

Usage

BFplus0(BFplus1, BF01)

Arguments

Value

Numeric scalar, BF_{+0}.

Bayes factor BF+1: H+ vs H1

Description

Bayes factor BF+1: H+ vs H1

Usage

BFplus1(y1, y2, n1, n2, a_1_a = 1, b_1_a = 1, a_2_a = 1, b_2_a = 1)

Arguments

Value

Numeric scalar, BF_{+1} = posterior odds / prior odds for H+ vs H1.

Bayes factor BF+-: H+ vs H-

Description

Bayes factor BF+-: H+ vs H-

Usage

BFplusMinus(BFplus1, BFminus1)

Arguments

Value

Numeric scalar, BF_{+-}.

Convert a one-stage single-arm BF design to a data frame

Description

Convert a one-stage single-arm BF design to a data frame

Usage

## S3 method for class 'singlearm_onestage_bf_design'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

A data frame with the search results.

Exact frequentist OCs for one two-stage two-arm BF design

Description

Exact frequentist OCs for one two-stage two-arm BF design

Usage

compute_freq_twostage_oc_2arm(
  n1_1,
  n1_2,
  n2_1,
  n2_2,
  k,
  k_f,
  test,
  p1_power,
  p2_power,
  p_null_grid = NULL,
  a_0_a,
  b_0_a,
  a_1_a,
  b_1_a,
  a_2_a,
  b_2_a,
  a_1_a_Hminus,
  b_1_a_Hminus,
  a_2_a_Hminus,
  b_2_a_Hminus
)

Design or evaluate a single-arm two-stage Bayes factor trial

Description

Calibrates or evaluates a single-arm two-stage Bayes factor design for a binary endpoint with one interim analysis for futility.

Usage

design_singlearm_bf(
  n1_min,
  n2_max,
  k,
  k_f,
  p0,
  a0 = 1,
  b0 = 1,
  a1 = 1,
  b1 = 1,
  dp = NA_real_,
  da0 = 1,
  db0 = 1,
  da1 = 1,
  db1 = 1,
  type = c("point", "direction"),
  calibration = c("Bayesian", "frequentist", "hybrid", "full"),
  target_power = 0.8,
  target_type1 = 0.05,
  target_ce_h0 = 0,
  target_freq_power = 0.8,
  target_freq_type1 = 0.05,
  algorithm = c("optimal", "manual"),
  interim = NULL,
  final = NULL,
  power_cushion = 0,
  ...
)

Arguments

Details

The design uses the Bayes factor BF_{01}. Small values of BF_{01} indicate evidence against H_0, so final efficacy is concluded when BF_{01} \\le k. Large values indicate evidence in favour of H_0, so interim futility is concluded when BF_{01} \\ge k_f.

Analysis priors are specified separately under H_0 and H_1 via a0, b0, a1, b1. Design priors are specified separately under H_0 and H_1 via da0, db0, da1, db1.

Value

An object of class "singlearm_bf_design".

Design or evaluate a one-stage single-arm Bayes factor trial

Description

Calibrates or evaluates a one-stage single-arm Bayes factor design for a binary endpoint.

Usage

design_singlearm_onestage_bf(
  n_min,
  n_max,
  k,
  k_ce = NULL,
  p0,
  a0 = 1,
  b0 = 1,
  a1 = 1,
  b1 = 1,
  dp = NA_real_,
  da0 = 1,
  db0 = 1,
  da1 = 1,
  db1 = 1,
  type = c("point", "direction"),
  calibration = c("Bayesian", "frequentist", "hybrid", "full"),
  target_power = 0.8,
  target_type1 = 0.05,
  target_ce_h0 = 0,
  target_freq_power = 0.8,
  target_freq_type1 = 0.05,
  algorithm = c("optimal", "manual"),
  n = NULL,
  power_cushion = 0,
  sustain_n = 10L,
  ...
)

Arguments

Details

The design uses the Bayes factor BF_{01}. Small values of BF_{01} indicate evidence against H_0, so efficacy is concluded when BF_{01} \le k. Large values indicate evidence in favour of H_0, and the optional CE(H0) / PCE(H0) constraint is evaluated using the separate threshold k_ce.

Analysis priors are specified separately under H_0 and H_1 via a0, b0, a1, b1. Design priors are specified separately under H_0 and H_1 via da0, db0, da1, db1.

Value

An object of class "singlearm_onestage_bf_design".

Design or evaluate a one-stage two-arm Bayes factor trial

Description

Calibrates or evaluates a one-stage two-arm Bayes factor design for a binary endpoint with fixed randomisation between the two arms.

Usage

design_twoarm_onestage_bf(
  n_min,
  n_max,
  k = 1/3,
  k_f = 3,
  test = c("BF01", "BF+0", "BF-0", "BF+-"),
  a_0_d = 1,
  b_0_d = 1,
  a_0_a = 1,
  b_0_a = 1,
  a_1_d = 1,
  b_1_d = 1,
  a_2_d = 1,
  b_2_d = 1,
  a_1_a = 1,
  b_1_a = 1,
  a_2_a = 1,
  b_2_a = 1,
  a_1_d_Hminus = 1,
  b_1_d_Hminus = 1,
  a_2_d_Hminus = 1,
  b_2_d_Hminus = 1,
  a_1_a_Hminus = 1,
  b_1_a_Hminus = 1,
  a_2_a_Hminus = 1,
  b_2_a_Hminus = 1,
  alloc1 = 0.5,
  alloc2 = 0.5,
  calibration = c("Bayesian", "frequentist", "hybrid", "full"),
  target_power = 0.8,
  target_type1 = 0.05,
  target_ce_h0 = 0,
  target_freq_power = 0.8,
  target_freq_type1 = 0.05,
  p1_grid = seq(0.01, 0.99, 0.02),
  p2_grid = seq(0.01, 0.99, 0.02),
  p1_power = NULL,
  p2_power = NULL,
  power_cushion = 0,
  sustain_n = 10L,
  report_freq_type1 = FALSE,
  algorithm = c("optimal", "manual"),
  n_total = NULL,
  progress = FALSE,
  ...
)

Arguments

Details

The design uses one of the Bayes factor tests implemented in powertwoarmbinbf01(). Small values of the relevant inverted Bayes factor indicate evidence against the null, so efficacy is concluded when the Bayes factor is below k. Large values indicate evidence in favour of the null (or H_- for test = "BF+-"), and the optional CE(H0) / PCE(H0) constraint is evaluated using k_f.

Value

An object of class "twoarm_onestage_bf_design".

Design an optimal two-stage two-arm Bayes factor trial

Description

Calibrates a two-stage two-arm Bayes factor design for a binary endpoint by calling optimal_twostage_2arm_bf() and packaging the result in a user-friendly object of class "twoarm_twostage_bf_design".

Usage

design_twoarm_twostage_bf(
  n1_min,
  n2_max,
  alloc1 = 0.5,
  alloc2 = 0.5,
  power_cushion = 0,
  interim_fraction = c(0.25, 0.75),
  grid_step = 1L,
  coarse_step = 4L,
  max_iter = 40L,
  ncores = getOption("bfbin2arm.ncores", 1L),
  k = 1/3,
  k_f = 3,
  test = c("BF01", "BF+0", "BF-0", "BF+-"),
  a_0_d = 1,
  b_0_d = 1,
  a_0_a = 1,
  b_0_a = 1,
  a_1_d = 1,
  b_1_d = 1,
  a_2_d = 1,
  b_2_d = 1,
  a_1_a = 1,
  b_1_a = 1,
  a_2_a = 1,
  b_2_a = 1,
  a_1_d_Hminus = 1,
  b_1_d_Hminus = 1,
  a_2_d_Hminus = 1,
  b_2_d_Hminus = 1,
  a_1_a_Hminus = 1,
  b_1_a_Hminus = 1,
  a_2_a_Hminus = 1,
  b_2_a_Hminus = 1,
  calibration = c("Bayesian", "frequentist", "hybrid"),
  calibration_en = c("Bayesian", "frequentist"),
  target_power = 0.8,
  target_type1 = 0.05,
  target_ce_h0 = 0,
  target_freq_power = 0.8,
  target_freq_type1 = 0.05,
  p1_power = NULL,
  p2_power = NULL,
  p1_en_h0 = NULL,
  p2_en_h0 = NULL,
  p_null_grid = NULL,
  progress = FALSE,
  ...
)

Arguments

Details

The design uses one of the Bayes factor tests implemented in powertwoarmbinbf01(). Small values of the relevant inverted Bayes factor indicate evidence against the null, so efficacy is concluded when the Bayes factor is below k. Large values indicate evidence in favour of the null (or H_- for test = "BF+-"), and the optional CE(H0) / PCE(H0) constraint is evaluated using k_f.

Value

An object of class "twoarm_twostage_bf_design".

Exact frequentist operating characteristics for a fixed two-stage two-arm BF design

Description

Internal helper. Computes the exact frequentist rejection probability of the two-stage design with futility stopping at interim and efficacy decision at final.

Usage

freq_oc_twostage_twoarm_fixed(
  n1_1,
  n1_2,
  n2_1,
  n2_2,
  k,
  k_f,
  test,
  p1,
  p2,
  a_0_a,
  b_0_a,
  a_1_a,
  b_1_a,
  a_2_a,
  b_2_a,
  a_1_a_Hminus,
  b_1_a_Hminus,
  a_2_a_Hminus,
  b_2_a_Hminus
)

Fixed-sample frequentist type-I error supremum over a null grid

Description

Internal helper. For a given fixed-sample design (n1, n2), computes the supremum of the frequentist type-I error over a grid of null parameter configurations, using freq_oc_twoarm_fixed().

Usage

freq_t1e_sup_fixed(
  n1,
  n2,
  k,
  k_f,
  test,
  p_null_grid = NULL,
  a_0_a,
  b_0_a,
  a_1_a,
  b_1_a,
  a_2_a,
  b_2_a,
  a_1_a_Hminus,
  b_1_a_Hminus,
  a_2_a_Hminus,
  b_2_a_Hminus,
  alpha_target = NULL,
  tol_excess = 1e-04
)

Two-stage frequentist type-I error supremum over a null grid

Description

Internal helper. For a given two-stage design (n1_1, n1_2, n2_1, n2_2), computes the supremum of the two-stage frequentist type-I error over a grid of null parameter configurations, using freq_oc_twostage_twoarm_fixed().

Usage

freq_t1e_twostage_twoarm_sup(
  n1_1,
  n1_2,
  n2_1,
  n2_2,
  k,
  k_f,
  test,
  p_null_grid = NULL,
  a_0_a,
  b_0_a,
  a_1_a,
  b_1_a,
  a_2_a,
  b_2_a,
  a_1_a_Hminus,
  b_1_a_Hminus,
  a_2_a_Hminus,
  b_2_a_Hminus,
  alpha_target = NULL,
  tol_excess = 1e-04
)

Sample size calibration for two-arm binomial Bayes factor designs

Description

Searches over a grid of total sample sizes n to find the smallest n such that Bayesian power, Bayesian type-I error, and probability of compelling evidence under H0 meet specified design criteria. Optionally, frequentist type-I error and power constraints are also evaluated. Unequal fixed randomisation between the two arms is allowed via alloc1 and alloc2.

Backward-compatible wrapper around design_twoarm_onestage_bf().

Usage

ntwoarmbinbf01(
  k = 1/3,
  k_f = 3,
  power = 0.8,
  alpha = 0.05,
  pce_H0 = 0.9,
  test = c("BF01", "BF+0", "BF-0", "BF+-"),
  nrange = c(10, 150),
  n_step = 1,
  progress = TRUE,
  compute_freq_t1e = FALSE,
  p1_grid = seq(0.01, 0.99, 0.02),
  p2_grid = seq(0.01, 0.99, 0.02),
  p1_power = NULL,
  p2_power = NULL,
  a_0_d = 1,
  b_0_d = 1,
  a_0_a = 1,
  b_0_a = 1,
  a_1_d = 1,
  b_1_d = 1,
  a_2_d = 1,
  b_2_d = 1,
  a_1_a = 1,
  b_1_a = 1,
  a_2_a = 1,
  b_2_a = 1,
  output = c("plot", "numeric"),
  a_1_d_Hminus = 1,
  b_1_d_Hminus = 1,
  a_2_d_Hminus = 1,
  b_2_d_Hminus = 1,
  a_1_a_Hminus = 1,
  b_1_a_Hminus = 1,
  a_2_a_Hminus = 1,
  b_2_a_Hminus = 1,
  alloc1 = 0.5,
  alloc2 = 0.5,
  sustain_n = 10L
)

ntwoarmbinbf01(
  k = 1/3,
  k_f = 3,
  power = 0.8,
  alpha = 0.05,
  pce_H0 = 0.9,
  test = c("BF01", "BF+0", "BF-0", "BF+-"),
  nrange = c(10, 150),
  n_step = 1,
  progress = TRUE,
  compute_freq_t1e = FALSE,
  p1_grid = seq(0.01, 0.99, 0.02),
  p2_grid = seq(0.01, 0.99, 0.02),
  p1_power = NULL,
  p2_power = NULL,
  a_0_d = 1,
  b_0_d = 1,
  a_0_a = 1,
  b_0_a = 1,
  a_1_d = 1,
  b_1_d = 1,
  a_2_d = 1,
  b_2_d = 1,
  a_1_a = 1,
  b_1_a = 1,
  a_2_a = 1,
  b_2_a = 1,
  output = c("plot", "numeric"),
  a_1_d_Hminus = 1,
  b_1_d_Hminus = 1,
  a_2_d_Hminus = 1,
  b_2_d_Hminus = 1,
  a_1_a_Hminus = 1,
  b_1_a_Hminus = 1,
  a_2_a_Hminus = 1,
  b_2_a_Hminus = 1,
  alloc1 = 0.5,
  alloc2 = 0.5,
  sustain_n = 10L
)

Arguments

Value

If output = "plot", returns invisibly a list with recommended sample sizes and a ggplot object printed to the device. If output = "numeric", returns a list with recommended n and summary.

If output = "numeric", returns a "twoarm_onestage_bf_design" object. If output = "plot", the plot is printed and the design object is returned invisibly.

Examples

# Standard calibration with equal allocation: power 80%, type-I 5%, CE(H0) 80%

ntwoarmbinbf01(power = 0.8, alpha = 0.05, pce_H0 = 0.8, output = "numeric")


# 1:2 allocation (control:treatment) via alloc1 = 1/3, alloc2 = 2/3

ntwoarmbinbf01(power = 0.8, alpha = 0.05, pce_H0 = 0.8,
               alloc1 = 1/3, alloc2 = 2/3, output = "numeric")


# BF+0 directional test with plot

ntwoarmbinbf01(power = 0.8, alpha = 0.05, pce_H0 = 0.9,
               test = "BF+0", output = "plot")

Internal calibration routine for one-stage single-arm BF designs

Description

Internal calibration routine for one-stage single-arm BF designs

Usage

optimal_onestage_singlearm_bf(
  n_min,
  n_max,
  k,
  p0,
  a0 = 1,
  b0 = 1,
  a1 = 1,
  b1 = 1,
  dp = NA_real_,
  da0 = 1,
  db0 = 1,
  da1 = 1,
  db1 = 1,
  type = c("point", "direction"),
  calibration = c("Bayesian", "frequentist", "hybrid", "full"),
  target_power = 0.8,
  target_type1 = 0.05,
  target_ce_h0 = 0,
  target_freq_power = 0.8,
  target_freq_type1 = 0.05,
  power_cushion = 0,
  k_ce = NULL,
  sustain_n = 10L
)

Arguments

Value

A list with feasibility, selected design, operating characteristics, and full search results.

Internal calibration routine for one-stage two-arm BF designs

Description

Internal calibration routine for one-stage two-arm BF designs

Usage

optimal_onestage_twoarm_bf(
  n_min,
  n_max,
  k = 1/3,
  k_f = 3,
  test = c("BF01", "BF+0", "BF-0", "BF+-"),
  a_0_d = 1,
  b_0_d = 1,
  a_0_a = 1,
  b_0_a = 1,
  a_1_d = 1,
  b_1_d = 1,
  a_2_d = 1,
  b_2_d = 1,
  a_1_a = 1,
  b_1_a = 1,
  a_2_a = 1,
  b_2_a = 1,
  a_1_d_Hminus = 1,
  b_1_d_Hminus = 1,
  a_2_d_Hminus = 1,
  b_2_d_Hminus = 1,
  a_1_a_Hminus = 1,
  b_1_a_Hminus = 1,
  a_2_a_Hminus = 1,
  b_2_a_Hminus = 1,
  alloc1 = 0.5,
  alloc2 = 0.5,
  calibration = c("Bayesian", "frequentist", "hybrid", "full"),
  target_power = 0.8,
  target_type1 = 0.05,
  target_ce_h0 = 0,
  target_freq_power = 0.8,
  target_freq_type1 = 0.05,
  p1_grid = seq(0.01, 0.99, 0.02),
  p2_grid = seq(0.01, 0.99, 0.02),
  p1_power = NULL,
  p2_power = NULL,
  power_cushion = 0,
  sustain_n = 10L,
  progress = FALSE
)

Arguments

Value

A list with feasibility, selected design, operating characteristics, and full search results.

Optimal two-stage two-arm Bayes-factor design for binary endpoints

Description

Computes an optimal two-stage two-arm Bayes-factor design for binary endpoints, minimizing the expected sample size under the null hypothesis while correcting the operating characteristics for the possibility of early stopping for futility.

Usage

optimal_twostage_2arm_bf(
  alpha = 0.05,
  beta = 0.2,
  k = 1/3,
  k_f = 3,
  n1_min = c(5, 5),
  n2_max = c(50, 50),
  alloc1 = 0.5,
  alloc2 = 0.5,
  power_cushion = 0,
  pceH0 = NULL,
  interim_fraction = c(0, 1),
  grid_step = 1L,
  coarse_step = 10L,
  progress = TRUE,
  max_iter = 10000L,
  ncores = getOption("bfbin2arm.ncores", 1L),
  compute_freq_oc = NULL,
  calibration_mode = c("Bayesian", "frequentist", "hybrid"),
  calibration_EN = NULL,
  p1_EN_H0 = NULL,
  p2_EN_H0 = NULL,
  alpha_freq = alpha,
  beta_freq = beta,
  p1_power = NULL,
  p2_power = NULL,
  p_null_grid = NULL,
  test = "BF01",
  a_0_d = 1,
  b_0_d = 1,
  a_0_a = 1,
  b_0_a = 1,
  a_1_d = 1,
  b_1_d = 1,
  a_2_d = 1,
  b_2_d = 1,
  a_1_a = 1,
  b_1_a = 1,
  a_2_a = 1,
  b_2_a = 1,
  a_1_d_Hminus = 1,
  b_1_d_Hminus = 1,
  a_2_d_Hminus = 1,
  b_2_d_Hminus = 1,
  a_1_a_Hminus = 1,
  b_1_a_Hminus = 1,
  a_2_a_Hminus = 1,
  b_2_a_Hminus = 1
)

Arguments

Value

A list with the following components:

Examples

## Fast Bayesian example with small search space
res <- optimal_twostage_2arm_bf(
  alpha = 0.10,
  beta = 0.20,
  k = 1 / 3,
  k_f = 3,
  n1_min = c(3, 3),
  n2_max = c(12, 12),
  alloc1 = 0.5,
  alloc2 = 0.5,
  power_cushion = 0,
  pceH0 = NULL,
  interim_fraction = c(0.25, 0.75),
  grid_step = 2L,
  coarse_step = 4L,
  progress = FALSE,
  max_iter = 24L,
  calibration_mode = "Bayesian",
  test = "BF01",
  a_0_d = 1, b_0_d = 1,
  a_0_a = 1, b_0_a = 1,
  a_1_d = 1, b_1_d = 1,
  a_2_d = 1, b_2_d = 1,
  a_1_a = 1, b_1_a = 1,
  a_2_a = 1, b_2_a = 1
)
res$design
res$occ


res2 <- optimal_twostage_2arm_bf(
  alpha = 0.05,
  beta = 0.20,
  k = 1 / 3,
  k_f = 3,
  n1_min = c(5, 5),
  n2_max = c(20, 20),
  alloc1 = 0.5,
  alloc2 = 0.5,
  power_cushion = 0.02,
  pceH0 = 0.50,
  interim_fraction = c(0.25, 0.75),
  grid_step = 1L,
  coarse_step = 4L,
  progress = FALSE,
  max_iter = 40L,
  calibration_mode = "Bayesian",
  test = "BF+0",
  a_0_d = 1, b_0_d = 1,
  a_0_a = 1, b_0_a = 1,
  a_1_d = 1, b_1_d = 2,
  a_2_d = 2, b_2_d = 1,
  a_1_a = 1, b_1_a = 1,
  a_2_a = 1, b_2_a = 1,
  a_1_d_Hminus = 1, b_1_d_Hminus = 1,
  a_2_d_Hminus = 1, b_2_d_Hminus = 1,
  a_1_a_Hminus = 1, b_1_a_Hminus = 1,
  a_2_a_Hminus = 1, b_2_a_Hminus = 1
)
res2$design
res2$occ

Optimal two-stage single-arm Bayes factor design

Description

Searches over admissible two-stage single-arm designs with a binary endpoint and returns the feasible design with smallest expected sample size under H0.

Usage

optimal_twostage_singlearm_bf(
  n1_min,
  n2_max,
  k,
  k_f,
  p0,
  a0 = 1,
  b0 = 1,
  a1 = 1,
  b1 = 1,
  dp = NA_real_,
  da0 = 1,
  db0 = 1,
  da1 = 1,
  db1 = 1,
  type = c("point", "direction"),
  calibration = c("Bayesian", "frequentist", "hybrid", "full"),
  target_power = 0.8,
  target_type1 = 0.05,
  target_ce_h0 = 0,
  target_freq_power = 0.8,
  target_freq_type1 = 0.05,
  power_cushion = 0
)

Arguments

Details

Analysis priors are specified separately under H0 and H1 via ⁠a0, b0, a1, b1⁠. Design priors are specified separately under H0 and H1 via ⁠da0, db0, da1, db1⁠.

Value

A list describing the optimal design and search results.

Plot a single-arm Bayes factor design

Description

Produces a diagnostic plot for a fitted single-arm two-stage Bayes factor design. Depending on the available information in the object, the plot shows the interim-search results, selected operating characteristics, and the design and analysis priors under H_0 and H_1.

Usage

## S3 method for class 'singlearm_bf_design'
plot(x, ...)

Arguments

Value

The input object x, invisibly.

See Also

summary.singlearm_bf_design(), design_singlearm_bf(), optimal_twostage_singlearm_bf()

Plot a one-stage single-arm BF design

Description

Plot a one-stage single-arm BF design

Usage

## S3 method for class 'singlearm_onestage_bf_design'
plot(x, what = c("all", "oc"), legend_pos = "right", legend_inset = 0, ...)

Arguments

Value

Invisibly returns x.

Plot an optimal two-stage two-arm Bayes factor design

Description

Given the result from optimal_twostage_2arm_bf(), this function produces a six-panel base R plot showing the design schematic, operating characteristics, and the design and analysis priors under H_0 and H_1.

Usage

plot_twostage_2arm_bf(
  res,
  main = "Optimal two-stage two-arm Bayes factor design"
)

Arguments

Value

Invisibly returns NULL; called for its side effect of producing a plot.

Examples

res <- optimal_twostage_2arm_bf(
  alpha = 0.10, beta = 0.20, k = 1/3, k_f = 3,
  n1_min = c(3, 3), n2_max = c(8, 8),
  alloc1 = 0.5, alloc2 = 0.5,
  power_cushion = 0,
  interim_fraction = c(0.5, 0.5),
  grid_step = 1,
  progress = FALSE,
  max_iter = 16,
  test = "BF01",
  a_0_d = 1, b_0_d = 1,
  a_0_a = 1, b_0_a = 1,
  a_1_d = 1, b_1_d = 1,
  a_2_d = 1, b_2_d = 1,
  a_1_a = 1, b_1_a = 1,
  a_2_a = 1, b_2_a = 1
)
if (is.numeric(res$design) && length(res$design) == 4 && !anyNA(res$design)) {
  plot_twostage_2arm_bf(res)
}

Posterior probability P(p2 <= p1 | data)

Description

Posterior probability P(p2 <= p1 | data)

Usage

postProbHminus(y1, y2, n1, n2, a_1_a = 1, b_1_a = 1, a_2_a = 1, b_2_a = 1)

Arguments

Value

Numeric scalar, posterior probability P(p_2 <= p_1 | y_1, y_2).

Posterior probability P(p2 > p1 | data) under independent Beta priors

Description

Uses Beta posteriors induced by the analysis priors to compute P(p_2 > p_1 \mid y_1, y_2).

Usage

postProbHplus(y1, y2, n1, n2, a_1_a = 1, b_1_a = 1, a_2_a = 1, b_2_a = 1)

Arguments

Value

Numeric scalar, posterior probability P(p_2 > p_1 | y_1, y_2).

Bayesian and frequentist operating characteristics for a fixed-sample single-arm BF design

Description

Computes operating characteristics for a genuine fixed-sample single-arm binomial design with final efficacy decision based on BF01 <= k.

Usage

powerbinbf01_fixed(
  n,
  k,
  p0,
  a0 = 1,
  b0 = 1,
  a1 = 1,
  b1 = 1,
  da0 = 1,
  db0 = 1,
  da1 = 1,
  db1 = 1,
  dp = NA_real_,
  type = c("point", "direction"),
  k_ce = NULL,
  grid_size = 801L
)

Arguments

Details

Bayesian operating characteristics are computed under separate design priors:

• for type = "direction", Bayesian power averages over p > p0 under the H1 design prior truncated to ⁠(p0, 1]⁠, Bayesian type-I error averages over p <= p0 under the H0 design prior truncated to ⁠[0, p0]⁠, and CE(H0) is averaged over the same truncated H0 design prior;

• for type = "point", Bayesian power averages under the H1 design prior on ⁠(0, 1)⁠, Bayesian type-I error is evaluated at the point null p = p0, and CE(H0) is also evaluated at p = p0.

Value

A list with Bayesian and frequentist operating characteristics for the fixed-sample design.

Bayesian and frequentist operating characteristics for a single-arm two-stage BF design

Description

Computes naive fixed-sample and corrected two-stage operating characteristics for a single-arm binomial design with one interim analysis for futility. The Bayes factor is oriented as BF01, so efficacy corresponds to small values (BF01 <= k) and futility corresponds to large values (BF01 >= kf).

Usage

powerbinbf01seq(
  n1,
  n2,
  k,
  kf,
  p0,
  a0 = 1,
  b0 = 1,
  a1 = 1,
  b1 = 1,
  da0 = 1,
  db0 = 1,
  da1 = 1,
  db1 = 1,
  dp = NA_real_,
  type = c("point", "direction"),
  k_ce = NULL,
  grid_size = 801L
)

Arguments

Details

Bayesian operating characteristics are computed under separate design priors:

• for type = "direction", Bayesian power averages over p > p0 under the H1 design prior truncated to ⁠(p0, 1]⁠, and Bayesian type-I error averages over p <= p0 under the H0 design prior truncated to ⁠[0, p0]⁠;

• for type = "point", Bayesian power averages under the H1 design prior on ⁠(0, 1)⁠, and Bayesian type-I error is evaluated at the point null p = p0.

If dp is supplied, additional frequentist power under H1 is computed at the fixed point alternative p = dp. Frequentist type-I error is computed at p = p0.

Value

A list with Bayesian and frequentist operating characteristics.

Bayesian power, type-I error, and PCE(H0) for two-arm binomial Bayes factors

Description

Computes Bayesian power, Bayesian type-I error, and the probability of compelling evidence under H_0 (or H_- for BF+-), for a given sample size and Bayes factor test. Optionally, frequentist type-I error and frequentist power are computed by summing over the rejection region.

Usage

powertwoarmbinbf01(
  n1,
  n2,
  k = 1/3,
  k_f = 1/3,
  test = c("BF01", "BF+0", "BF-0", "BF+-"),
  a_0_d = 1,
  b_0_d = 1,
  a_0_a = 1,
  b_0_a = 1,
  a_1_d = 1,
  b_1_d = 1,
  a_2_d = 1,
  b_2_d = 1,
  a_1_a = 1,
  b_1_a = 1,
  a_2_a = 1,
  b_2_a = 1,
  output = c("numeric", "predDensmatrix", "t1ematrix", "ceH0matrix", "frequentist_t1e"),
  a_1_d_Hminus = 1,
  b_1_d_Hminus = 1,
  a_2_d_Hminus = 1,
  b_2_d_Hminus = 1,
  compute_freq_t1e = FALSE,
  p1_grid = seq(0.01, 0.99, 0.02),
  p2_grid = seq(0.01, 0.99, 0.02),
  p1_power = NULL,
  p2_power = NULL,
  a_1_a_Hminus = 1,
  b_1_a_Hminus = 1,
  a_2_a_Hminus = 1,
  b_2_a_Hminus = 1
)

Arguments

Value

Depending on output, either a named numeric vector with components Power, Type1_Error, CE_H0 (and optionally frequentist metrics) or matrices of predictive densities.

Examples

# Basic Bayesian power for BF01 test
powertwoarmbinbf01(n1 = 30, n2 = 30, k = 1/3, test = "BF01")

# Directional test BF+0 with frequentist type-I error
powertwoarmbinbf01(n1 = 40, n2 = 40, k = 1/3, k_f = 3,
                   test = "BF+0", compute_freq_t1e = TRUE)

# Predictive density matrices (advanced)
powertwoarmbinbf01(n1 = 25, n2 = 25, output = "predDensmatrix")

Predictive density under H0: p1 = p2 = p

Description

Beta-binomial predictive density for data (y1,y2) under H0.

Usage

predictiveDensityH0(y1, y2, n1, n2, a_0_d = 1, b_0_d = 1)

Arguments

Value

Numeric scalar, predictive density.

Predictive density under H1: p1 != p2

Description

Product of two independent Beta-binomial predictive densities.

Usage

predictiveDensityH1(y1, y2, n1, n2, a_1_d = 1, b_1_d = 1, a_2_d = 1, b_2_d = 1)

Arguments

Value

Numeric scalar, predictive density.

Predictive density under H-: p2 <= p1 (truncated prior)

Description

Predictive density under H-: p2 <= p1 (truncated prior)

Usage

predictiveDensityHminus_trunc(
  y1,
  y2,
  n1,
  n2,
  a_1_d = 1,
  b_1_d = 1,
  a_2_d = 1,
  b_2_d = 1
)

Arguments

Value

Numeric scalar, predictive density under H-.

Predictive density under H+: p2 > p1 (truncated prior)

Description

Predictive density under H+: p2 > p1 (truncated prior)

Usage

predictiveDensityHplus_trunc(
  y1,
  y2,
  n1,
  n2,
  a_1_d = 1,
  b_1_d = 1,
  a_2_d = 1,
  b_2_d = 1
)

Arguments

Value

Numeric scalar, predictive density under H+.

Print method for one-stage single-arm BF designs

Description

Print method for one-stage single-arm BF designs

Usage

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

Arguments

Value

The input object x, invisibly.

Print method for summary.singlearm_bf_design

Description

Print method for summary.singlearm_bf_design

Usage

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

Arguments

Value

The input object x, invisibly.

Print method for summaries of one-stage single-arm BF designs

Description

Print method for summaries of one-stage single-arm BF designs

Usage

## S3 method for class 'summary.singlearm_onestage_bf_design'
print(x, digits = 3, ...)

Arguments

Value

The input object x, invisibly.

Prior probability P(p2 <= p1) under independent Beta priors

Description

Prior probability P(p2 <= p1) under independent Beta priors

Usage

priorProbHminus(a_1_a, b_1_a, a_2_a, b_2_a)

Arguments

Value

Numeric scalar, prior probability P(p2 <= p1).

Prior probability P(p2 > p1) under independent Beta priors

Description

Prior probability P(p2 > p1) under independent Beta priors

Usage

priorProbHplus(a_1_a, b_1_a, a_2_a, b_2_a)

Arguments

Value

Numeric scalar, prior probability P(p2 > p1).

Summary for single-arm BF designs

Description

Summary for single-arm BF designs

Usage

## S3 method for class 'singlearm_bf_design'
summary(object, ...)

Arguments

Value

An object of class "summary.singlearm_bf_design".

Summarize a one-stage single-arm BF design

Description

Summarize a one-stage single-arm BF design

Usage

## S3 method for class 'singlearm_onestage_bf_design'
summary(object, ...)

Arguments

Value

An object of class "summary.singlearm_onestage_bf_design".

Two-arm binomial Bayes factor BF01

Description

Computes the Bayes factor BF_{01} comparing the point-null H_0: p_1 = p_2 to the alternative H_1: p_1 \neq p_2 in a two-arm binomial setting with Beta priors.

Usage

twoarmbinbf01(
  y1,
  y2,
  n1,
  n2,
  a_0_a = 1,
  b_0_a = 1,
  a_1_a = 1,
  b_1_a = 1,
  a_2_a = 1,
  b_2_a = 1
)

Arguments

Value

Numeric scalar, the Bayes factor BF_{01}.

Examples

twoarmbinbf01(10, 20, 30, 30)

Bayes factor BF+0 for the directional alternative vs point-null

Description

Computes the Bayes factor BF_{+0} comparing the directional alternative hypothesis H_+ (p_2 > p_1) against the point-null H_0 (p_1 = p_2).

Usage

twoarmbinbf_plus0_direct(
  y1,
  y2,
  n1,
  n2,
  a_0_a = 1,
  b_0_a = 1,
  a_1_a = 1,
  b_1_a = 1,
  a_2_a = 1,
  b_2_a = 1
)

Arguments

Details

Both marginal likelihoods are formed using the analysis priors, which represent inferential beliefs at the time the data are evaluated. The design priors are used only for computing Bayesian operating characteristics (predictive power / type-I error) and play no role here.

Value

Numeric scalar; the Bayes factor BF_{+0} = m_+(y_1, y_2) / m_0(y_1, y_2).