| name | tmb-likelihood-review |
| description | Review TMB likelihoods, parameter transforms, and engine plumbing before merging changes to gllvmTMB's `src/gllvmTMB.cpp` or its R wrappers. |
TMB Likelihood Review
Use this skill for any change to the C++ template (src/gllvmTMB.cpp),
density branches, parameter transforms, or the R/fit-multi.R
parameter-pack-and-unpack code.
Review Checklist
- Are all constrained parameters represented internally on
unconstrained scales?
- Positive parameters:
log_tau, log_kappa, log_sd_*,
theta_diag_* (where the diag is exp-transformed inside the
template).
- Correlations:
tanh / atanh or another stable bounded transform.
- Reduced-rank loadings: packed lower-triangular
(
theta_rr_*).
- Are constants included consistently in likelihoods?
dpois(..., log = TRUE), dbinom(..., log = TRUE), etc.
- Are gradients finite for simulated data at the simulation truth and
at the fitted MLE?
- Does
sdreport() report interpretable transformed parameters
(Sigma_B, R_B, phylo_signal_h2, repeatability_R)?
- Does simulation recover truth under ordinary sample sizes (n_sites
= 30, n_traits >= 3)? Apply the add-simulation-test skill.
- Are boundary and weak-identification cases tested? In particular:
latent rank too high (engine should fail loud);phylo_latent with zero phylogenetic signal
(sigma2_phy -> 0);spatial_latent with degenerate mesh (single triangle).
Multi-tier covariance contract
The engine maintains the contract
$$\Sigma_{\text{tier}} = \boldsymbol\Lambda_{\text{tier}}\boldsymbol\Lambda_{\text{tier}}^\top + \mathrm{diag}(\mathbf U_{\text{tier}})$$
at every tier where the user pairs latent + unique. Any change
that touches the unpack of theta_rr_* or theta_diag_* must
preserve this. The test suite enforces it via
test_that("extract_Sigma() composes Lambda Lambda^T + diag(s)").
Cross-tier identifiability
When two tiers share the same grouping factor (e.g. both latent(0 + trait | site, d = K) and unique(0 + trait | site)), the engine
fits the decomposition $\Sigma_B = \boldsymbol\Lambda_B
\boldsymbol\Lambda_B^\top + \mathbf S_B$. When the user supplies only
one of the pair, identifiability collapses to the no-residual
(rotation-invariant) or the marginal/independent special case. The
parser must surface this distinction to the user with a cli_inform
explaining which mode the engine is in.
