boot_jsd: Bootstrap JSD for each group

In phontrast: Contrast and Separation Metrics for Phonological Categories

Bootstrap JSD for each group

Description

Computes bootstrap mean, SD, and confidence interval for JSD within each group (e.g., speaker), using resampling with replacement.

Usage

boot_jsd(
  data,
  group_col,
  category_col,
  features,
  n_boot = 1000,
  min_tokens = 20,
  est_distance = FALSE,
  conf_level = 0.95,
  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,
  ...
)

Arguments

data	Data frame containing acoustic measurements.
group_col	Character vector giving one or more grouping columns (e.g., "speaker" or c("Sex", "Style")).
category_col	String: name of column giving the category to compare (e.g., "vowel"). Each group must have exactly two categories.
features	Character vector of column names giving the acoustic space.
n_boot	Number of bootstrap resamples per group.
min_tokens	Minimum number of tokens per group required to compute JSD. Groups with fewer tokens are dropped.
est_distance	Logical; if TRUE, return Jensen-Shannon distance (sqrt of divergence) instead of divergence.
conf_level	Confidence level for bootstrap intervals.
bw	Bandwidth selection method passed to jsd_kde_nd().
eval_on	KDE evaluation points passed to jsd_kde_nd().
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 jsd_kde_nd(). "fast_diagonal" is accepted as an alias for "fast_diag".
chunk_size	Chunk size for engine = "fast_diag".
...	Additional arguments passed to jsd_kde_nd().

Value

A tibble with one row per group and columns: group, n_tokens, n_boot, conf_level, jsd_mean, jsd_sd, ci_lower, ci_upper, jsd_low, and jsd_high. jsd_low and jsd_high are retained as legacy aliases for ci_lower and ci_upper.

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