Run PCA on Regime Correlation Structures — regime_correlation

Convert each regime covariance matrix to a correlation matrix, vectorize the upper-triangle off-diagonal entries, and run stats::prcomp() on the resulting regime-by-correlation matrix. When use_correlation = TRUE, the function warns if all retained covariance matrices are scalar-proportional to one another. That pattern is expected for proportional search$VCVs from the scalar bifrost search model and should not be interpreted as independent post-hoc covariance reconfiguration evidence.

Usage

regime_correlation_pca(
  x,
  use_correlation = TRUE,
  center = TRUE,
  scale. = TRUE,
  tip_counts = NULL,
  regime_ages = NULL,
  trait_labels = NULL,
  min_tips = NULL,
  ...
)

Arguments

x: A regime_covariances object returned by fit_regime_covariances() or a named list of covariance/correlation matrices. Matrices must contain finite entries and strictly positive diagonal variances.
use_correlation: Logical; if TRUE, convert each matrix with stats::cov2cor() before vectorizing.
center, scale.: Passed to stats::prcomp(). Defaults match the manuscript workflow.
tip_counts: Optional named numeric vector of tip counts.
regime_ages: Optional named numeric vector of regime ages.
trait_labels: Optional labels for the matrix rows/columns. Supply a named vector to map internal trait names to display labels, or an unnamed vector in matrix order. Resolved labels must be unique and not blank.
min_tips: Optional positive whole-number minimum tip count for inclusion when tip_counts are available. Matching the manuscript min_n convention, regimes are retained only when tip_count > min_tips. At least one non-missing tip count must be available when this filter is used.
...: Reserved for future extensions.

Value

An object of class regime_correlation_pca containing the prcomp object, vectorized input matrix, scores, loadings, variance explained, regime IDs, trait labels, optional diagnostics, and a settings list that records the PCA scaling, tip-count filter, and whether retained covariance matrices were scalar-proportional.