percent_overlap_kde: Proportional overlap between two distributions via KDE

In phontrast: Contrast and Separation Metrics for Phonological Categories

Proportional overlap between two distributions via KDE

Description

Computes the proportional overlap (shared area) between two categories in an n-dimensional acoustic space using multivariate kernel density estimation. Despite the historical function name, the return value is a 0–1 proportion: 0 = no overlap, 1 = identical.

Usage

percent_overlap_kde(
  data,
  features,
  category_col,
  bw = c("Hpi", "Hscv", "Hpi.diag", "scott.diag"),
  eval_on = c("pooled", "group1", "group2", "pooled_sample"),
  eval_n = NULL,
  eval_seed = NULL,
  engine = c("ks", "fast_diag", "fast_diagonal"),
  chunk_size = 1000L,
  method = c("mc", "legacy"),
  density = c("kde", "mvnorm"),
  mc_n = 10000L,
  bw_scale = 1,
  ...
)

Arguments

data	Data frame.
features	Character vector of numeric feature columns.
category_col	String; exactly two categories.
bw	Bandwidth selection method. Uses the same options as jsd_kde_nd(): "Hpi", "Hscv", "Hpi.diag", or "scott.diag".
eval_on	Where to evaluate the KDEs. Uses the same options as jsd_kde_nd(): "pooled", "group1", "group2", or "pooled_sample".
eval_n	Optional positive integer giving the maximum number of evaluation points to use.
eval_seed	Optional integer seed used only when eval_n causes evaluation-point subsampling.
engine	KDE evaluation engine. Uses the same options as jsd_kde_nd(): "ks", "fast_diag", or "fast_diagonal".
chunk_size	Positive integer controlling the number of evaluation points processed per chunk by engine = "fast_diag".
method	Estimator: "mc" (default) for the Monte-Carlo plug-in estimate of the overlapping coefficient, or "legacy" for the pre-1.2.0 self-normalized sample-point estimate. eval_on applies to "legacy" only. Ignored when density = "mvnorm".
density	Density model behind the estimate: "kde" (default) estimates each category's density by kernel density estimation; "mvnorm" fits one multivariate normal per category and estimates the overlapping coefficient between the two Gaussians by Monte-Carlo. Under "mvnorm" the KDE-specific arguments (bw, engine, eval_on, chunk_size, method, eval_n) do not apply; the Monte-Carlo sample size is set by mc_n and eval_seed makes the draw reproducible.
mc_n	Positive integer; number of Monte-Carlo samples drawn from each fitted Gaussian when density = "mvnorm" (default 10000). The estimator draws mc_n fresh points from each category's fitted Gaussian to estimate the overlapping coefficient between the two Gaussians. Larger values reduce Monte-Carlo variance. Ignored when density = "kde".
bw_scale	Positive number multiplying the selected kernel bandwidth on the standard-deviation scale (univariate bandwidths by bw_scale, bandwidth matrices by bw_scale^2); see jsd_kde_nd(). Ignored when density = "mvnorm".
...	Reserved for future extensions; currently unused.

Value

Numeric scalar proportion in [0, 1].

phontrast documentation built on Oct. 7, 2026, 5:06 p.m.