estimate_overlap: Estimate proportional overlap globally or by group

In phontrast: Contrast and Separation Metrics for Phonological Categories

Estimate proportional overlap globally or by group

Description

Unified front-end for KDE-based proportional overlap between two categories. The returned overlap column is a 0–1 proportion, not a 0–100 percentage.

Usage

estimate_overlap(
  data,
  features,
  category_col,
  group_col = NULL,
  min_tokens = 20,
  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 with at least category_col and features.
features	Character vector of feature column names (e.g., c("F1","F2")).
category_col	Name of the column giving the two-way category factor.
group_col	Optional character vector of one or more grouping columns. If provided, returns per-group overlap. Multiple grouping columns are combined into a labeled group value such as "Sex=F | Style=read".
min_tokens	Minimum total tokens required (globally or per group).
bw	Bandwidth selection method passed to percent_overlap_kde().
eval_on	KDE evaluation points passed to percent_overlap_kde().
eval_n	Optional maximum number of KDE evaluation points.
eval_seed	Optional integer seed for KDE evaluation-point subsampling.
engine	KDE evaluation engine passed to percent_overlap_kde(). "fast_diagonal" is accepted as an alias for "fast_diag".
chunk_size	Chunk size for engine = "fast_diag".
method	Estimator passed to percent_overlap_kde(): "mc" (default) or "legacy" (pre-1.2.0 self-normalized estimate). Ignored when density = "mvnorm".
density	Density model passed to percent_overlap_kde(): "kde" (default) or "mvnorm" (fit one multivariate normal per category and estimate the overlapping coefficient between the two Gaussians by Monte-Carlo).
mc_n	Positive integer; number of Monte-Carlo samples drawn from each fitted Gaussian when density = "mvnorm" (default 10000). Ignored when density = "kde".
bw_scale	Positive bandwidth multiplier passed to percent_overlap_kde() (default 1); see jsd_kde_nd().
...	Additional arguments passed to percent_overlap_kde().

Value

A tibble (global = one row; grouped = one per group) with overlap as a 0–1 proportion.

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