Extract cross-lineage coevolutionary modules

extract_coevolution_modules() standardizes a component-specific cross-lineage covariance block and decomposes it into coupled trait axes. For a named coevolution kernel tier, the helper computes R = Sigma_row^{-1/2} Gamma Sigma_col^{-1/2} from the shared covariance returned by extract_Sigma(), then applies a singular-value decomposition.

This is a point-estimate derived-output helper, covered by the package's validation tests, for fitted dense-kernel coevolution models whose component-specific Gamma blocks are already extractable with extract_Gamma(). It does not report uncertainty, choose the biological rank, estimate rho, or calibrate null thresholds. Use simulation, bootstrap, and kernel-separability checks before treating the returned axes as scientific evidence.

Usage

extract_coevolution_modules(
  fit,
  level,
  row_traits,
  col_traits,
  scale = c("shape", "effect"),
  n_modules = NULL,
  tol = sqrt(.Machine$double.eps)
)

Arguments

fit

A fitted gllvmTMB_multi object.

level

Character scalar naming the fitted covariance tier.

row_traits, col_traits

Character vectors naming the row-lineage and column-lineage traits.

scale

Character scalar. "shape" (default) uses Gamma_shape = Lambda_row Lambda_col^T; "effect" uses the fixed-rho Gamma_effect available for kernels built by make_cross_kernel().

n_modules

Optional positive integer limiting the number of returned singular axes. By default all axes are returned.

tol

Numerical tolerance for the generalized inverse square roots of the within-lineage shared covariance blocks.

Value

A list with R, modules, row_axes, and col_axes. R is the standardized cross-lineage correlation-like block. modules has one row per singular axis with its singular value and squared-value share. row_axes and col_axes contain trait loadings for each coupled axis.

Examples

if (FALSE) { # \dontrun{
mods <- extract_coevolution_modules(
  fit,
  level = "phy",
  row_traits = c("host_size", "host_defence"),
  col_traits = c("partner_size", "partner_attack")
)
mods$modules
mods$row_axes
mods$col_axes
} # }