% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/optimal_twostage_2arm.R
\name{optimal_twostage_2arm_bf}
\alias{optimal_twostage_2arm_bf}
\title{Optimal two-stage two-arm Bayes-factor design for binary endpoints}
\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{
\item{alpha}{Numeric scalar, Bayesian type-I-error target.}

\item{beta}{Numeric scalar, 1 minus the minimal Bayesian power target.}

\item{k}{Numeric scalar, efficacy threshold; evidence against the null
hypothesis is declared when the corresponding Bayes factor is smaller
than \code{k}.}

\item{k_f}{Numeric scalar, futility threshold; compelling evidence for the
null hypothesis is declared when the corresponding Bayes factor is at
least \code{k_f}.}

\item{n1_min}{Numeric vector of length 2, minimum interim sample sizes
for arms 1 and 2.}

\item{n2_max}{Numeric vector of length 2, maximum final sample sizes
for arms 1 and 2.}

\item{alloc1, alloc2}{Positive numbers, allocation probabilities to arms 1
and 2.}

\item{power_cushion}{Numeric scalar, optional extra power cushion used in
the fixed-sample search of step 1.}

\item{pceH0}{Optional numeric scalar in \code{[0,1]}. If specified,
candidate two-stage designs must satisfy corrected \code{CE_H0 >= pceH0}.}

\item{interim_fraction}{Numeric vector of length 2 giving lower and upper
bounds for the interim sample size in each arm as a fraction of the fixed
sample size.}

\item{grid_step}{Positive integer giving the spacing of the interim design
grid.}

\item{coarse_step}{Positive integer giving the spacing of the coarse
fixed-sample search grid in step 1.}

\item{progress}{Logical; if \code{TRUE}, prints progress information.}

\item{max_iter}{Integer, maximum number of total fixed-sample sizes searched
in step 1.}

\item{ncores}{Integer; number of parallel worker processes to use in the
calibration. Defaults to \code{getOption("bfbin2arm.ncores", 1L)}. In
vignettes and examples, a conservative value (e.g. 1 or 2) is recommended
for CRAN checks, whereas users can increase this to exploit all available
cores on their own machines.}

\item{compute_freq_oc}{Logical or \code{NULL}. Controls whether frequentist
operating characteristics are computed for candidate two-stage designs
during the search.}

\item{calibration_mode}{Character string specifying the calibration mode.
Must be one of \code{"Bayesian"}, \code{"frequentist"}, or
\code{"hybrid"}.}

\item{calibration_EN}{Character string or \code{NULL} specifying whether
the design is ranked by Bayesian or frequentist expected sample size
under the null hypothesis.}

\item{p1_EN_H0, p2_EN_H0}{Numeric scalars specifying the null response
probabilities in control and treatment arm used when
\code{calibration_EN = "frequentist"}.}

\item{alpha_freq}{Numeric scalar, frequentist type-I error target.}

\item{beta_freq}{Numeric scalar, 1 minus the frequentist power target.}

\item{p1_power, p2_power}{Numeric scalars specifying the success probabilities
in control and treatment arm used for the frequentist power calculation.}

\item{p_null_grid}{Optional numeric vector giving the grid of null response
probabilities used for frequentist type-I-error maximization. If
\code{NULL}, a default grid is used.}

\item{test}{Character string, one of \code{"BF01"}, \code{"BF+0"},
\code{"BF-0"}, \code{"BF+-"}.}

\item{a_0_d, b_0_d, a_0_a, b_0_a}{Shape parameters for design and analysis priors
under \eqn{H_0}.}

\item{a_1_d, b_1_d, a_2_d, b_2_d}{Shape parameters for design priors under
\eqn{H_1} or \eqn{H_+}.}

\item{a_1_a, b_1_a, a_2_a, b_2_a}{Shape parameters for analysis priors under
\eqn{H_1} or \eqn{H_+}.}

\item{a_1_d_Hminus, b_1_d_Hminus, a_2_d_Hminus, b_2_d_Hminus}{Optional design
priors under \eqn{H_-} for directional tests.}

\item{a_1_a_Hminus, b_1_a_Hminus}{Shape parameters of the analysis prior
under the directional null hypothesis H0- for arm 1.}

\item{a_2_a_Hminus, b_2_a_Hminus}{Shape parameters of the analysis prior
under the directional null hypothesis H0- for arm 2.}
}
\value{
A list with the following components:
\item{design}{Four-element integer vector containing the selected two-stage
design: interim sample sizes in arms 1 and 2 followed by final sample sizes
in arms 1 and 2.}
\item{naive_oc}{Named list of uncorrected fixed-sample operating
characteristics and fixed-sample sizes found in step 1.}
\item{occ}{Named numeric vector of corrected Bayesian operating
characteristics for the selected two-stage design.}
\item{priors}{List storing design hyperparameters and search settings.}
\item{freq_occ}{Named numeric vector with fixed-sample and two-stage
frequentist operating characteristics for the final design when frequentist
calibration or reporting is active; otherwise \code{NULL}.}
\item{conv}{Character string describing the search outcome. Typical values
include \code{"converged"}, \code{"no_feasible_fixed"},
\code{"no_interim_grid"}, and \code{"no_feasible_design"}. In frequentist
or hybrid calibration modes, additional informative status values may be
returned when the best available design is returned although all requested
constraints were not fully satisfied.}
}
\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.
}
\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

\donttest{
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
}

}
