plot_category_pca: Plot a PCA projection of multidimensional category space

In phontrast: Contrast and Separation Metrics for Phonological Categories

Plot a PCA projection of multidimensional category space

Description

Projects an arbitrary multidimensional acoustic feature set onto two principal components and visualizes the result with ggplot2. This is a diagnostic plot for high-dimensional workflows: metric estimates should still be computed on the full feature set when that is the intended analysis.

Usage

plot_category_pca(
  data,
  features,
  category_col,
  group_col = NULL,
  components = c(1L, 2L),
  center = TRUE,
  scale. = TRUE,
  points = TRUE,
  ellipses = TRUE,
  point_alpha = 0.65,
  point_size = 1.8,
  equal_axes = TRUE,
  facet_scales = c("fixed", "free", "free_x", "free_y")
)

Arguments

data	Data frame containing category labels and acoustic features.
features	Character vector of two or more numeric feature columns used for PCA.
category_col	String; category column.
group_col	Optional grouping column used for facets.
components	Two positive integers giving principal components to plot.
center, scale.	Passed to stats::prcomp().
points	Logical; if TRUE, show projected observations.
ellipses	Logical; if TRUE, add normal ellipses when enough observations are available.
point_alpha	Point transparency.
point_size	Point size.
equal_axes	Logical; if TRUE, use a fixed coordinate ratio.
facet_scales	Scales passed to ggplot2::facet_wrap() when group_col is supplied.

Value

A ggplot2 plot object. The fitted prcomp object and variance-explained table are stored as "pca" and "variance_explained" attributes.

Examples

set.seed(2026)
features <- paste0("mfcc", 1:5)
vowels <- data.frame(
  vowel = rep(c("ih", "eh"), each = 50),
  matrix(rnorm(100 * length(features)), ncol = length(features))
)
names(vowels)[-1] <- features
vowels[vowels$vowel == "eh", features[1:2]] <- vowels[vowels$vowel == "eh", features[1:2]] + 0.8

if (requireNamespace("ggplot2", quietly = TRUE)) {
  plot_category_pca(vowels, features = features, category_col = "vowel")
}

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