compare_overlap_metrics: Compare phonological category overlap metrics (deprecated)

In phontrast: Contrast and Separation Metrics for Phonological Categories

Compare phonological category overlap metrics (deprecated)

Description

compare_overlap_metrics() was renamed to phontrast() in phontrast 2.0.0 (the package formerly released as 'phonJSD'). It remains as a thin wrapper that calls phontrast() with output = "wide" for backward compatibility and will be removed in a future release. New code should call phontrast().

Usage

compare_overlap_metrics(
  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,
  eps = 1e-06,
  output = c("wide", "long"),
  do_boot = FALSE,
  n_boot = 1000,
  conf_level = 0.95,
  progress = TRUE,
  method = c("mc", "legacy"),
  density = c("kde", "mvnorm"),
  mc_n = 10000L,
  bw_scale = 1
)

Arguments

data	Data frame containing category labels and acoustic features.
features	Character vector of numeric feature columns.
category_col	String; column giving the two categories to compare.
group_col	Optional character vector of one or more grouping columns. If NULL, metrics are computed globally. Multiple grouping columns are combined into a labeled group value such as "Sex=F | Style=read".
min_tokens	Minimum tokens required globally or per group.
bw	Bandwidth selection method passed to jsd_kde_nd() and percent_overlap_kde().
eval_on	KDE evaluation points passed to jsd_kde_nd() and percent_overlap_kde().
eval_n	Optional maximum number of KDE evaluation points passed to jsd_kde_nd() and percent_overlap_kde().
eval_seed	Optional integer seed for KDE evaluation-point subsampling.
engine	KDE evaluation engine passed to jsd_kde_nd() and percent_overlap_kde(). "fast_diagonal" is accepted as an alias for "fast_diag".
chunk_size	Chunk size for engine = "fast_diag".
eps	Small ridge constant for covariance-based metrics.
output	Output format: "wide" returns one row per global/group comparison; "long" returns one row per metric per comparison.
do_boot	Logical; if TRUE, compute bootstrap means, standard deviations, and confidence intervals for each reported metric.
n_boot	Number of bootstrap resamples if do_boot = TRUE.
conf_level	Confidence level for bootstrap intervals.
progress	Logical; if TRUE, print progress messages while bootstrap resamples are running.
method	KDE estimator for the JSD and percent-overlap columns, passed to jsd_kde_nd()/percent_overlap_kde(): "mc" (default) for the Monte-Carlo plug-in, or "legacy" for the pre-1.2.0 self-normalized estimate. Ignored when density = "mvnorm".
density	Density model behind the two distributional metrics (Jensen-Shannon and proportional overlap): "kde" (default) estimates each category's density by kernel density estimation; "mvnorm" fits one multivariate normal per category and estimates those two metrics between the fitted Gaussians by Monte-Carlo. This lets the density estimator be matched to the same multivariate-normal assumptions the Pillai, Bhattacharyya, and Mahalanobis columns already make. The Pillai, Bhattacharyya, and Mahalanobis columns are parametric by construction and are unaffected by this argument.
mc_n	Positive integer; number of Monte-Carlo samples drawn from each fitted Gaussian for the Jensen-Shannon and overlap columns when density = "mvnorm" (default 10000). Ignored when density = "kde".
bw_scale	Positive number multiplying the selected kernel bandwidth on the standard-deviation scale for the Jensen-Shannon and overlap columns (default 1); 0.5 and 2 give the halved and doubled bandwidths of the smoothing-sensitivity check in rank_contrasts(). Ignored when density = "mvnorm".

Value

See phontrast(); wide format by default.

See Also

phontrast()

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