plot_category_space: Plot phonological categories in acoustic space

In phontrast: Contrast and Separation Metrics for Phonological Categories

Plot phonological categories in acoustic space

Description

Creates a ggplot2 visualization of one or two acoustic dimensions from a token-level table. One-dimensional inputs are plotted as density curves; two-dimensional inputs are plotted as category-colored scatterplots with optional normal ellipses.

Usage

plot_category_space(
  data,
  features,
  category_col,
  group_col = NULL,
  points = TRUE,
  ellipses = TRUE,
  point_alpha = 0.65,
  point_size = 1.8,
  reverse_x = FALSE,
  reverse_y = FALSE,
  equal_axes = FALSE,
  facet_scales = c("fixed", "free", "free_x", "free_y")
)

Arguments

data	Data frame containing category labels and acoustic features.
features	One or two numeric feature columns to plot.
category_col	String; category column.
group_col	Optional grouping column used for facets.
points	Logical; if TRUE, show observed tokens.
ellipses	Logical; if TRUE, add normal ellipses for two-feature plots when enough observations are available.
point_alpha	Point transparency.
point_size	Point size.
reverse_x	Logical; if TRUE, reverse the x-axis.
reverse_y	Logical; if TRUE, reverse the y-axis.
equal_axes	Logical; if TRUE, use a fixed coordinate ratio for two-feature plots.
facet_scales	Scales passed to ggplot2::facet_wrap() when group_col is supplied.

Value

A ggplot2 plot object.

Examples

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

if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot_category_space(vowels, features = "f1", category_col = "vowel")
  plot_category_space(
    vowels,
    features = c("f2", "f1"),
    category_col = "vowel",
    reverse_x = TRUE,
    reverse_y = TRUE
  )
}

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