regime_module_diagnostics: Diagnose PCA Axes with User-defined Trait Modules

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

Diagnose PCA Axes with User-defined Trait Modules

Description

Summarize within- and between-module correlations for each post-hoc regime and correlate those module summaries with regime correlation PCA scores.

Usage

regime_module_diagnostics(pca, modules, comparisons = NULL, pcs = NULL)

Arguments

pca	A regime_correlation_pca object from regime_correlation_pca() computed with use_correlation = TRUE.
modules	Named list of character vectors. Module names must be unique and not blank. Each element names the unique trait labels belonging to one anatomical, developmental, or functional module. Singleton modules are allowed; their within-module scores and PC correlations are NA because no pairwise correlation is defined.
comparisons	Optional named list defining module comparisons to score. Each element must be a length-two character vector naming entries in modules. When both names are the same, the score is the mean upper-triangle within-module correlation; otherwise it is the mean between-module correlation. If NULL, all within-module and pairwise between-module comparisons are generated. Missing or blank comparison names are generated from their module pairs; the resulting names must be unique and not blank.
pcs	Principal components to correlate with module summaries. Supply numeric indices or names such as "PC1". Defaults to all PCA score columns.

Value

An object of class regime_module_diagnostics, containing per-regime module scores, PC/module correlations, comparison definitions, and settings.

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)
modules <- list(flight = c("wing", "tail"), feeding = "bill")
diagnostics <- regime_module_diagnostics(pca, modules)
diagnostics$correlations

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