Extract a cross-lineage Gamma block

extract_Gamma() slices the shared covariance matrix returned by extract_Sigma() to give the row-lineage by column-lineage block Gamma_shape = Lambda_row Lambda_col^T. In a fitted cross-lineage kernel model, level is the named kernel_*() tier, row_traits are the host traits, and col_traits are the partner traits. This is a point-estimate extractor for the shared covariance block of a fitted dense-kernel model, covered by the package's validation tests at the fixed-rho scale: when the fitted kernel tier was built from make_cross_kernel(), scale = "effect" returns Gamma_effect = rho * Gamma_shape using the fixed rho recorded on that kernel. Uncertainty for Gamma is not yet reported by this helper; use bootstrap workflows when interval estimates are required. Use profile_cross_rho() to compare a fixed rho grid; in-engine rho estimation and profile intervals remain planned work.

Usage

extract_Gamma(fit, level, row_traits, col_traits, scale = c("shape", "effect"))

Arguments

fit

A fitted gllvmTMB_multi object.

level

Character scalar naming the covariance tier. For kernel_*() fits this is the name argument supplied in the formula.

row_traits, col_traits

Character vectors of trait names defining the rows and columns of the returned block.

scale

Character scalar. "shape" (default) returns Gamma_shape = Lambda_row Lambda_col^T. "effect" returns rho * Gamma_shape for fixed cross-lineage kernels built by make_cross_kernel(). The current engine does not estimate rho.

Value

A numeric matrix with rows row_traits and columns col_traits.

Details

rho is part of the supplied K matrix, not a fitted parameter in the current engine. To profile it, use profile_cross_rho() to rebuild K_star over a small rho grid, refit the same formula, and compare logLik() values. scale = "effect" is therefore a fixed-kernel transformation, not an estimate of rho. Treat Gamma from a single association matrix W as data-condition sensitive: the C2 recovery test includes a sparse-versus-dense W check, and sparse or poorly replicated host-partner links should be reported as weaker evidence rather than as a precise coevolution estimate.

For fixed multi-kernel fits, extract_Gamma() also inspects the fitted kernel-similarity diagnostics. If the requested component participates in a high-overlap kernel pair, the returned block is still available, but a warning reminds the caller that component-specific separation is weak evidence.

Examples

if (FALSE) { # \dontrun{
Gamma_HP <- extract_Gamma(
  fit,
  level = "cross",
  row_traits = c("host_size", "host_defence"),
  col_traits = c("partner_size", "partner_attack")
)
} # }