Skip to contents

Summarize Post-hoc Regime Covariance Matrices

Source: R/regime-integration.R
summarize_regime_covariances.Rd

Compute regime-rate, mean variance, mean absolute trait correlation, Fisher-Z transformed mean absolute correlation, tip count, and regime age from independent post-hoc covariance matrices.

Usage

summarize_regime_covariances(
  x,
  search = NULL,
  rates = NULL,
  tree = NULL,
  tip_counts = NULL,
  regime_ages = NULL,
  fisher_boundary = c("NA", "error"),
  remove_high_corr = FALSE,
  corr_threshold = 0.95
)

Arguments

x

A regime_covariances object returned by fit_regime_covariances() or a named list of covariance/correlation matrices.

Optional bifrost_search object used as a source of named regime-rate parameters and, when possible, mapped-regime tip counts/ages.

rates

Optional named numeric vector of regime rates. Names must be unique and non-empty and are matched to regime IDs; numeric equality is never used for matching.

tree

Optional SIMMAP-style tree used to compute tip counts and regime ages when they are not already supplied.

tip_counts

Optional named numeric vector of tip counts. When names are supplied, they must be unique and non-empty.

regime_ages

Optional named numeric vector of regime ages. When names are supplied, they must be unique and non-empty.

fisher_boundary

How to handle correlations with abs(r) >= 1, where Fisher-Z is undefined. "NA" returns NA for those regimes; "error" stops with an error.

remove_high_corr

Logical; if TRUE, drop rows whose mean absolute correlation exceeds corr_threshold. This reproduces the manuscript generateVarsCorsList(remove_high_corr = TRUE, corr_threshold = 0.95) filtering step.

corr_threshold

Correlation threshold used when remove_high_corr is TRUE.

Value

A data frame with one row per regime and columns regime, rate, mean_variance, mean_abs_correlation, fisher_z_mean_abs_correlation, tip_count, regime_age, status, and message.

Details

This summary is designed for independent post-hoc matrices. Do not pass proportional search$VCVs from a bifrost_search object when the question is whether regimes differ in phenotypic integration or correlation structure. If x is detectably the same object as search$VCVs, the function warns and still returns the requested descriptive summary. Raw matrix-list inputs must have unique, non-empty regime names. Their matrices must be symmetric and positive semidefinite, contain finite entries and strictly positive diagonal variances, and, when named, have unique matching row and column trait names; violations produce a regime-specific error. Invalid matrices encountered in a regime_covariances fit object are instead represented as failed rows with missing summaries and a diagnostic message. A one-trait matrix has no pairwise correlations, so its mean absolute correlation and Fisher-Z summary are returned as NA.