Diagnose PCA Axes with User-defined Trait Modules

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
#>    PC module_comparison correlation
#> 1 PC1     within_flight -0.59177731
#> 2 PC1    within_feeding          NA
#> 3 PC1 flight_vs_feeding -0.36281611
#> 4 PC2     within_flight -0.80598164
#> 5 PC2    within_feeding          NA
#> 6 PC2 flight_vs_feeding -0.84993457
#> 7 PC3     within_flight -0.01390018
#> 8 PC3    within_feeding          NA
#> 9 PC3 flight_vs_feeding  0.38206765