Package {BivKLD}

BivKLD: Bivariate Kullback-Leibler Divergence

Description

Tools for estimating and calculating directed Kullback-Leibler divergence between bivariate distributions. See biv_kld() for the two-sample kernel estimator and biv_kld_matrix() for grouped comparisons.

Author(s)

Maintainer: Saurav Singla s00singla@gmail.com

Authors:

• Saurav Singla s00singla@gmail.com

• Rafflesia Chackochan rafflesiachackochan03@gmail.com

References

Chackochan, R., Sankaran, P. G., & Unnikrishnan Nair, N. (2026). Bivariate Kullback-Leibler divergence. Communications in Statistics - Theory and Methods, 55(1), 292-312. doi:10.1080/03610926.2025.2496687

Estimate Bivariate Kullback-Leibler Divergence

Description

Estimates the directed divergence from the distribution represented by x to that represented by y. Bivariate Gaussian kernel densities are evaluated on a common rectangular grid and numerically integrated.

Usage

biv_kld(
  x,
  y,
  Hx = NULL,
  Hy = NULL,
  bandwidth = c("scv", "normal"),
  grid_size = 100L,
  range = NULL,
  standardize = c("none", "pooled", "separate"),
  details = FALSE
)

Arguments

Details

range may be a list of two increasing numeric ranges, a two-by-two matrix whose rows contain coordinate limits, or c(x_min, x_max, y_min, y_max). By default the observed pooled range is padded using the selected bandwidths.

Pooled standardization applies the same affine transformation to both samples and therefore leaves the population KL divergence unchanged. Separate standardization, used in the motivating analyses, compares the shapes after removing each sample's own location and scale; it does not estimate the divergence between the original distributions.

Value

A non-negative numeric estimate when details = FALSE. Otherwise, an object of class bivkld_estimate containing the estimate, bandwidths, evaluation grid, densities, and settings.

References

Chackochan, R., Sankaran, P. G., & Unnikrishnan Nair, N. (2026). Bivariate Kullback-Leibler divergence. Communications in Statistics - Theory and Methods, 55(1), 292-312. doi:10.1080/03610926.2025.2496687

Examples

set.seed(2026)
x <- cbind(rnorm(60), rnorm(60))
y <- cbind(rnorm(60, 0.4), rnorm(60, -0.2))
biv_kld(x, y, bandwidth = "normal", grid_size = 40)

Exact Bivariate KL Divergence for Discrete Distributions

Description

Computes the directed KL divergence between two probability tables. The inputs can be matrices, arrays, or vectors, but must have identical shapes.

Usage

biv_kld_discrete(
  p,
  q,
  normalize = FALSE,
  tolerance = sqrt(.Machine$double.eps)
)

Arguments

Value

A non-negative numeric scalar, possibly Inf when q is zero at a cell to which p assigns positive probability.

Examples

p <- matrix(c(0.2, 0.3, 0.1, 0.4), 2)
q <- matrix(c(0.1, 0.4, 0.2, 0.3), 2)
biv_kld_discrete(p, q)

Pairwise Bivariate Kullback-Leibler Divergence

Description

Computes all directed kernel KL divergences among two or more groups on one common integration grid. Each group density and bandwidth is evaluated only once.

Usage

biv_kld_matrix(
  x,
  group = NULL,
  H = NULL,
  bandwidth = c("scv", "normal"),
  grid_size = 100L,
  range = NULL,
  standardize = c("none", "pooled", "separate")
)

Arguments

Value

A numeric matrix. Row i, column j is the estimated directed divergence from group i to group j. Bandwidths, grid information, and standardization are stored as attributes.

Examples

measurements <- iris[, c("Sepal.Length", "Sepal.Width")]
kld <- biv_kld_matrix(measurements, iris$Species,
                      bandwidth = "normal", grid_size = 40)
round(kld, 3)

Exact KL Divergence Between Bivariate Normal Distributions

Description

Computes D(N(mean1, sigma1) || N(mean2, sigma2)) analytically.

Usage

biv_kld_normal(mean1, sigma1, mean2, sigma2)

Arguments

Value

A non-negative numeric scalar.

Examples

biv_kld_normal(c(-2, 2), matrix(c(1, 1, 1, 2), 2),
               c(-2, 2), matrix(c(3, 3, 3, 6), 2))

Exact KL Divergence for Two Models from the Reference Paper

Description

biv_kld_pareto2() evaluates the divergence between bivariate Pareto type II models with survival functions (1 + x1 + x2)^(-alpha) and (1 + x1 + x2)^(-beta). biv_kld_independent_weibull() evaluates the divergence between models with survival functions exp(-alpha[1] * x1 - alpha[2] * x2) and the corresponding expression in beta.

Usage

biv_kld_pareto2(alpha, beta)

biv_kld_independent_weibull(alpha, beta)

Arguments

Value

A non-negative numeric scalar.

References

Chackochan, R., Sankaran, P. G., & Unnikrishnan Nair, N. (2026). Bivariate Kullback-Leibler divergence. Communications in Statistics - Theory and Methods, 55(1), 292-312. doi:10.1080/03610926.2025.2496687

Examples

biv_kld_pareto2(1, 2)
biv_kld_independent_weibull(c(1, 2), c(2, 3))