regime_correlation_pca: Run PCA on Regime Correlation Structures

In bifrost: Branch-Level Inference Framework for Recognizing Optimal Shifts in Traits

Run PCA on Regime Correlation Structures

Description

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.

Examples

make_correlation <- function(r12, r13, r23) {
  matrix(
    c(1, r12, r13, r12, 1, r23, r13, r23, 1),
    nrow = 3,
    dimnames = list(c("bill", "wing", "tail"),
                    c("bill", "wing", "tail"))
  )
}
covariances <- list(
  r1 = make_correlation(0.1, 0.2, 0.3),
  r2 = make_correlation(0.2, 0.1, 0.4),
  r3 = make_correlation(-0.1, 0.3, 0.2),
  r4 = make_correlation(0.4, -0.2, 0.1)
)
pca <- regime_correlation_pca(covariances)
pca$variance_explained

bifrost documentation built on Nov. 5, 2026, 9:07 a.m.