Predict pair-specific cross-lineage covariance

predict_cross_covariance() combines a component-specific Gamma_shape block from extract_Gamma() with entries of the fitted dense kernel matrix. For a fixed cross-lineage kernel built with make_cross_kernel(), the off-diagonal K entries already include the supplied fixed rho, so the pair-specific covariance is Gamma_shape * K[row_level, col_level]. This helper therefore uses the shape-scale Gamma and does not multiply by extract_Gamma(scale = "effect").

Fixed dense kernel_latent() tiers, covered by the package's validation tests, store their aligned K matrices on the fit, and this helper returns point estimates for named species/lineage pairs. It does not estimate rho, produce intervals, calibrate null thresholds, or combine components into a universal total Gamma.

Usage

predict_cross_covariance(
  fit,
  level,
  row_levels = NULL,
  col_levels = NULL,
  row_traits,
  col_traits
)

Arguments

fit

A fitted gllvmTMB_multi object.

level

Character scalar naming the fitted kernel_*() tier.

row_levels, col_levels

Character vectors naming row and column levels in the fitted kernel matrix. If both are omitted for a kernel built by make_cross_kernel(), host and partner levels from the kernel metadata are used.

row_traits, col_traits

Character vectors of trait names defining the rows and columns of the component-specific Gamma_shape block.

Value

A data frame with one row per level-pair and trait-pair. Columns include component, row_level, col_level, row_trait, col_trait, kernel_value, gamma_shape, covariance, rho, and kernel_includes_rho.

Examples

if (FALSE) { # \dontrun{
predict_cross_covariance(
  fit,
  level = "phy",
  row_levels = c("H1", "H2"),
  col_levels = c("P1", "P2"),
  row_traits = c("host_size", "host_defence"),
  col_traits = c("partner_size", "partner_attack")
)
} # }