plot_contrast: Distribution-aware contrast plot for two categories

In phontrast: Contrast and Separation Metrics for Phonological Categories

Distribution-aware contrast plot for two categories

Description

The flagship visualization for a two-category contrast. Unlike a decorative scatterplot, plot_contrast() draws the same density model the distributional metrics are computed from: under density = "kde" it shows highest-density regions of each category's kernel density estimate (same bandwidth selection as jsd_kde_nd()); under density = "mvnorm" it shows coverage ellipses of the fitted multivariate normals used by the parametric backend. The pointwise minimum of the two densities – the mass that the proportional-overlap metric integrates – is shaded, so the overlap itself is visible rather than implied.

Usage

plot_contrast(
  data,
  features,
  category_col,
  group_col = NULL,
  density = c("kde", "mvnorm"),
  bw = c("Hpi", "Hscv", "Hpi.diag", "scott.diag"),
  bw_scale = 1,
  levels = c(0.5, 0.8, 0.95),
  points = TRUE,
  overlap = TRUE,
  annotate = TRUE,
  n_boot = 0,
  conf_level = 0.95,
  min_tokens = 20,
  mc_n = 10000L,
  eval_seed = NULL,
  grid_n = NULL,
  point_alpha = 0.55,
  point_size = 1.6,
  reverse_x = FALSE,
  reverse_y = FALSE,
  facet_scales = c("fixed", "free", "free_x", "free_y")
)

Arguments

data	Data frame with category labels and one or two numeric features.
features	One or two numeric feature columns. One feature gives density curves; two give a feature-space plot with density regions. For higher-dimensional spaces, plot a projection with plot_category_pca() (metrics should still be computed on the full space).
category_col	String; category column with exactly two observed categories.
group_col	Optional character vector of grouping columns; one panel per group, with per-group densities and annotations.
density	Density model to draw and to use for annotations: "kde" (default) or "mvnorm". Matches the density argument of the metric functions.
bw	Bandwidth selection method for density = "kde"; same options as jsd_kde_nd().
bw_scale	Positive multiplier on the selected kernel bandwidth for density = "kde" (default 1; see jsd_kde_nd()). The drawn regions, the shaded overlap, and the annotations all use the same scaled bandwidth, so bw_scale = 0.5 and 2 show the halved and doubled smoothing of the bandwidth check in rank_contrasts().
levels	Numeric vector of probability levels in (0, 1) for the drawn regions: highest-density regions under "kde", coverage ellipses under "mvnorm".
points	Logical; show observed tokens (2D points, 1D rug).
overlap	Logical; shade the pointwise minimum of the two category densities (a ribbon in 1D, a soft raster in 2D). Shading strength is normalized across panels, so lighter panels genuinely overlap less.
annotate	Logical; label each panel with Jensen-Shannon divergence and proportional overlap computed under the plotted density model.
n_boot	Number of bootstrap resamples for annotation confidence intervals; 0 (default) annotates point estimates only.
conf_level	Confidence level for bootstrap intervals.
min_tokens	Minimum tokens per group; smaller groups are dropped with a warning (same convention as the metric functions).
mc_n	Monte-Carlo sample size for density = "mvnorm" annotations; passed to the metric functions.
eval_seed	Optional integer seed passed to the metric functions so annotated values are reproducible.
grid_n	Grid resolution for density evaluation: points per axis. Default 512 for one feature, 151 for two.
point_alpha	Point (or rug) transparency.
point_size	Point size for two-feature plots.
reverse_x, reverse_y	Logical; reverse an axis (e.g. F2 by F1 vowel space convention).
facet_scales	Scales passed to ggplot2::facet_wrap() when group_col is supplied.

Details

With annotate = TRUE (default) the panel is labelled with the Jensen-Shannon divergence and proportional overlap computed by phontrast() under the same density, bw, mc_n, and eval_seed settings, and the caption records the estimator configuration. The full annotation table is attached to the returned plot as attr(p, "contrast_metrics").

Value

A ggplot2 plot object. When annotate = TRUE, the phontrast() table behind the labels is attached as attr(p, "contrast_metrics").

Examples

set.seed(2026)
vowels <- data.frame(
  vowel = rep(c("ih", "eh"), each = 60),
  f1 = c(rnorm(60, 500, 55), rnorm(60, 565, 60)),
  f2 = c(rnorm(60, 1980, 150), rnorm(60, 1870, 155))
)

if (requireNamespace("ggplot2", quietly = TRUE)) {
  # Two-feature contrast in vowel-space orientation, KDE regions.
  plot_contrast(vowels, c("f2", "f1"), "vowel",
                reverse_x = TRUE, reverse_y = TRUE)

  # One-feature contrast with the overlap ribbon.
  plot_contrast(vowels, "f1", "vowel")

  # The same contrast under the multivariate-normal backend.
  plot_contrast(vowels, c("f2", "f1"), "vowel", density = "mvnorm",
                eval_seed = 2026, reverse_x = TRUE, reverse_y = TRUE)
}

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