Diagnose fixed-kernel separability before fitting — diagnose_kernel

diagnose_kernel_separability() compares two or more dense fixed kernels on the same levels before they are used in a multi-kernel model. It is a pre-fit diagnostic rather than evidence that the components are separately identifiable: when candidate kernels are highly overlapping, component-specific Gamma blocks are weak evidence and should be treated as descriptive unless simulations justify the split.

Use this helper to screen candidate K_phy and K_tip definitions, including raw-network and residualized-network choices, before fitting kernel_latent(..., name = ...) tiers. Note its limits: this is a diagnostic, not recovery evidence, interval calibration, or an in-engine identifiability proof.

Usage

diagnose_kernel_separability(
  ...,
  thresholds = c(near_orthogonal = 0.25, high = 0.7)
)

Arguments

...: Two or more named numeric square kernel matrices with the same dimensions and level order.
thresholds: Named numeric vector with entries near_orthogonal and high. Similarity below near_orthogonal is labelled "near_orthogonal"; similarity below high is "moderate"; similarity at or above high is "high".

Value

A list of class gllvmTMB_kernel_separability with:

similarity: A symmetric matrix of off-diagonal Frobenius-style similarities between kernels.
pairs: A data frame with pair labels, similarity, overlap class, and a conservative recommendation.
thresholds: The thresholds used for the classes.
note: A short claim-boundary note.

Examples

A_H <- diag(2)
A_P <- diag(2)
rownames(A_H) <- colnames(A_H) <- c("H1", "H2")
rownames(A_P) <- colnames(A_P) <- c("P1", "P2")
W_phy <- matrix(c(1, 0.2, 0.2, 1), 2, 2,
  dimnames = list(rownames(A_H), rownames(A_P)))
W_tip <- matrix(c(0.2, 1, 1, 0.2), 2, 2,
  dimnames = list(rownames(A_H), rownames(A_P)))
K_phy <- make_cross_kernel(A_H, A_P, W_phy, rho = 0.5)
K_tip <- make_cross_kernel(A_H, A_P, W_tip, rho = 0.5)
diagnose_kernel_separability(phy = K_phy, tip = K_tip)
#> $similarity
#>           phy       tip
#> phy 1.0000000 0.3846154
#> tip 0.3846154 1.0000000
#> 
#> $pairs
#>   level_1 level_2 similarity overlap_class       recommendation
#> 1     phy     tip  0.3846154      moderate sensitivity_required
#> 
#> $thresholds
#> near_orthogonal            high 
#>            0.25            0.70 
#> 
#> $note
#> [1] "Off-diagonal Frobenius-style similarity between fixed kernel tiers. High overlap means component-specific Gamma_shape separation is weak evidence; report one network-conditioned covariance unless simulations justify the split."
#> 
#> attr(,"class")
#> [1] "gllvmTMB_kernel_separability"