inspect_contrast: Inspect one speaker's contrast across bandwidths

In phontrast: Contrast and Separation Metrics for Phonological Categories

Inspect one speaker's contrast across bandwidths

Description

Redraws a single speaker from a rank_contrasts() ranking with plot_contrast()'s distribution-aware layers, one panel per kernel bandwidth, so a flagged or set-aside speaker can be inspected the way the protocol asks: at half, at the selected, and at twice the diagonal Scott bandwidth (the smoothing used by the bandwidth check). Each panel is labelled with the Jensen-Shannon distance and shared mass at that bandwidth and with the speaker's Pillai trace, which takes no bandwidth; the subtitle restates the reported ranks, the rank difference, and the outcome of the bandwidth check. The tokens come from the ranking itself (attr(ranking, "protocol")$data), so no further data is needed.

Usage

inspect_contrast(
  ranking,
  group,
  features = NULL,
  bw_scales = c(0.5, 1, 2),
  levels = c(0.5, 0.8, 0.95),
  points = TRUE,
  overlap = TRUE,
  grid_n = NULL,
  point_alpha = 0.55,
  point_size = 1.6,
  reverse_x = FALSE,
  reverse_y = FALSE
)

Arguments

ranking	A phontrast_ranking object from rank_contrasts().
group	String; the speaker (a value of ranking$group) to inspect.
features	Features to display: by default the ranking's own features, which must number one or two. For a ranking in more than two dimensions, name two of its features here; the annotated metrics are still computed on all of the ranking's features.
bw_scales	Positive bandwidth multipliers, one panel each (default c(0.5, 1, 2)).
levels, points, overlap, grid_n, point_alpha, point_size, reverse_x, reverse_y	As in plot_contrast().

Value

A ggplot2 plot object. The per-panel metrics are attached as attr(p, "inspect_metrics").

See Also

rank_contrasts(), plot_rank_agreement(), plot_contrast().

Examples

set.seed(2026)
gaps <- c(30, 60, 90, 120, 150, 180, 210, 240)
cohort <- do.call(rbind, lapply(seq_along(gaps), function(i) {
  data.frame(
    speaker = sprintf("s%02d", i),
    vowel = rep(c("ih", "eh"), each = 50),
    f1 = c(rnorm(50, 500, 55), rnorm(50, 500 + gaps[i], 55)),
    f2 = c(rnorm(50, 1900, 120), rnorm(50, 1900 - gaps[i], 120))
  )
}))
ranking <- rank_contrasts(cohort, c("f1", "f2"), "vowel", "speaker",
                          bw_check = FALSE)
if (requireNamespace("ggplot2", quietly = TRUE)) {
  inspect_contrast(ranking, "s04")
}

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