R/jsd_ci.R

In jsdtools: Jensen-Shannon Divergence Estimation, Confidence Intervals, and Distribution Plots

#' Bootstrap confidence interval for Jensen-Shannon divergence
#'
#' Unified front-end for JSD confidence interval estimation for continuous and
#' discrete variables.
#'
#' @param x First vector.
#' @param y Second vector.
#' @param type One of `"auto"`, `"continuous"`, or `"discrete"`.
#' @param B Number of bootstrap replicates.
#' @param conf_level Confidence level. Defaults to 0.95.
#' @param base Logarithm base. Defaults to 2. Use `exp(1)` for nats.
#' @param seed Optional random seed.
#' @param ... Additional arguments passed to the type-specific bootstrap
#'   estimator.
#'
#' @return An object of class `"jsd_ci"`.
#' @export
jsd_ci <- function(x, y,
                   type = c("auto", "continuous", "discrete"),
                   B = 1000,
                   conf_level = 0.95,
                   base = 2,
                   seed = NULL,
                   ...) {
  type <- match.arg(type)

  if (type == "auto") {
    type <- detect_type(x, y)
  }

  out <- switch(
    type,
    continuous = jsd_continuous_ci(
      x, y,
      B = B,
      conf_level = conf_level,
      base = base,
      seed = seed,
      ...
    ),
    discrete = jsd_discrete_ci(
      x, y,
      B = B,
      conf_level = conf_level,
      base = base,
      seed = seed,
      ...
    ),
    stop("Unsupported type.")
  )

  out$call <- match.call()
  out
}