daniel1noble / BACE / 25341195972

91%

push

github

Add per-level multinomial Pagel-style lambda to phylo_signal_summary

For categorical traits, phylo_signal_summary() now reports both:
  - H2_*           trace-based heritability on MCMCglmm's working
                   scale (existing behaviour, unchanged)
  - lambda_nominal_* per-level Pagel-style lambda after the Amemiya
                   c² correction puts each level on the standard
                   probit scale (residual = 1 per non-baseline
                   category).

Per Ayumi (2024) multinomial GLMM tutorial,
https://ayumi-495.github.io/multinomial-GLMM-tutorial/#nominal,
the per-level lambda is:

  lambda_k = G'_kk / (G'_kk + 1),  where
  G'_kk    = G_phylo[k,k] / (1 + c² · 2/(J+1)),
  c²       = (16·sqrt(3) / (15·pi))² ≈ 0.3458,
  J        = K - 1 non-baseline categories.

The reported lambda_nominal_mean is the average across the J
non-baseline levels (each lambda_k is also kept on
attr(model, "lambda_nominal_per_level") for keep_models = TRUE
runs). Unlike H², this is on the same scale as Pagel's lambda
for continuous traits, so it can be cross-compared in a
multi-trait phylo_signal table.

H2_mean and lambda_nominal_mean typically differ by 0.1-0.2 on
the same multinomial fit (e.g., 0.93 vs 0.75 on the K=3 demo
dataset). The gap is expected, not a bug — H² is on
MCMCglmm's working scale (residual diag 2/(J+1)) while
lambda_nominal applies the Hadfield 2010 §3.7 correction to
project onto unit-residual probit. Use lambda_nominal_mean for
cross-trait comparisons; H2_mean for within-categorical
variance-decomposition reporting.

Continuous (gaussian/poisson/threshold/ordinal) and OVR-
categorical paths return NA for lambda_nominal_* columns —
the formula is defined only on the multinomial-probit G_phylo
block.

7 new unit tests (test-lambda_nominal.R) cover output structure,
[0,1] bounds, HPD ordering, per-level attribute, NA for non-
multinomial paths, and a white-box check of the c² correction.
1268 tests pass (was 1251). R CMD check... (continued)

52 of 59 new or added lines in 1 file covered. (88.14%)

3409 of 3740 relevant lines covered (91.15%)

87.3 hits per line