Quick start: from vowel table to metrics and plots
In phontrast: Contrast and Separation Metrics for Phonological Categories

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Most analyses should start with a token-level table: one row per observation, one column for the category contrast, and one or more numeric acoustic features. phontrast() is the preferred entry point because it returns the main overlap and separation metrics side by side.

library(phontrast)

set.seed(2026)
vowels <- data.frame(
  speaker = rep(c("s01", "s02"), each = 60),
  vowel = rep(rep(c("ih", "eh"), each = 30), 2),
  f1 = c(
    rnorm(30, 500, 55), rnorm(30, 560, 60),
    rnorm(30, 510, 60), rnorm(30, 575, 65)
  ),
  f2 = c(
    rnorm(30, 1980, 150), rnorm(30, 1880, 155),
    rnorm(30, 1960, 160), rnorm(30, 1840, 165)
  )
)

The wide output is useful for analysis tables and joining to speaker metadata.

metrics_wide <- phontrast(
  data = vowels,
  features = c("f1", "f2"),
  category_col = "vowel",
  group_col = "speaker",
  output = "wide"
)

metrics_wide

The long output is easier to rank, filter, and plot. separation_value puts all metrics on a separation-oriented scale: larger values mean greater category separation, even for overlap metrics such as percent overlap and Bhattacharyya affinity.

metrics_long <- phontrast(
  data = vowels,
  features = c("f1", "f2"),
  category_col = "vowel",
  group_col = "speaker",
  output = "long"
)

metrics_long[, c("group", "metric", "estimate", "orientation", "separation_value")]

If ggplot2 is installed, the same objects can be visualized directly.

plot_category_space(
  data = vowels,
  features = c("f2", "f1"),
  category_col = "vowel",
  group_col = "speaker",
  reverse_x = TRUE,
  reverse_y = TRUE
)

plot_overlap_metrics(metrics_long)

For uncertainty intervals, use do_boot = TRUE. Bootstrapping recomputes every metric on every resample, so use a larger n_boot for final analyses than for interactive examples.

phontrast(
  data = vowels,
  features = c("f1", "f2"),
  category_col = "vowel",
  group_col = "speaker",
  do_boot = TRUE,
  n_boot = 1000,
  output = "long"
)