R/binom.conf.exact.R

In winratiosim: Simulate Power for Hierarchical Win Ratio Endpoints

#' Exact Binomial Confidence Interval
#'
#' Computes an exact two-sided Clopper-Pearson confidence interval for a
#' binomial proportion by inverting the binomial test.
#'
#' @param x Integer. Number of observed successes.
#' @param n Integer. Total number of trials.
#' @param alpha Numeric. Significance level for the confidence interval.
#'   The default is \code{0.05}, corresponding to a 95 percent interval.
#'
#' @return A named numeric vector with three elements:
#' \describe{
#'   \item{PointEst}{Observed proportion, \code{x / n}.}
#'   \item{Lower}{Lower confidence limit.}
#'   \item{Upper}{Upper confidence limit.}
#' }
#'
#' @examples
#' binom.conf.exact(x = 8, n = 10)
#' binom.conf.exact(x = 50, n = 100, alpha = 0.01)
#'
#' @export
binom.conf.exact <- function(x, n, alpha = 0.05) {
  if (length(x) != 1L || length(n) != 1L || length(alpha) != 1L) {
    stop("x, n, and alpha must each be length-one values.", call. = FALSE)
  }
  if (!is.finite(x) || !is.finite(n) || !is.finite(alpha)) {
    stop("x, n, and alpha must be finite.", call. = FALSE)
  }
  if (x < 0 || n <= 0 || x > n) {
    stop("Require 0 <= x <= n and n > 0.", call. = FALSE)
  }
  if (alpha <= 0 || alpha >= 1) {
    stop("alpha must be between 0 and 1.", call. = FALSE)
  }

  x <- as.integer(x)
  n <- as.integer(n)

  lower <- if (x == 0L) {
    0
  } else {
    f_quantile <- stats::qf(1 - alpha / 2, 2 * (n - x + 1), 2 * x)
    x / (x + f_quantile * (n - x + 1))
  }

  upper <- if (x == n) {
    1
  } else {
    f_quantile <- stats::qf(1 - alpha / 2, 2 * (x + 1), 2 * (n - x))
    ((x + 1) * f_quantile) / (n - x + (x + 1) * f_quantile)
  }

  res <- c(x / n, lower, upper)
  names(res) <- c("PointEst", "Lower", "Upper")
  res
}