For a predictor-informed ordinary latent fit, latent(..., lv = ~ x) uses
the unit-level score model
$$\mathbf u_s = \mathbf z_s + \mathbf X_s \boldsymbol\alpha,$$
where the innovation \(\mathbf z_s\) keeps the usual standard-normal prior.
extract_lv_effects() reports either the raw axis-scale
\(\boldsymbol\alpha\) coefficients or the induced trait-scale contribution
\(\mathbf B_{\mathrm{lv}} = \boldsymbol\Lambda \boldsymbol\alpha^\top\).
The axis-scale table is the default because it matches the usual constrained
latent-variable / ordination coefficient. It is conditional on the fitted
loading constraint and axis orientation: like the loadings themselves
(extract_loadings()), \(\boldsymbol\alpha\) is identified only up to
the same orthogonal (or oblique) rotation, so raw axis-scale coefficients
from two fits – even of the same model on the same data – need not sit
on a common axis and are not directly comparable without alignment. This
is intrinsic to latent-variable identifiability, not a defect. For
cross-fit comparison, prefer type = "trait_effect", the
rotation-invariant induced slope surface on the trait linear-predictor
scale, described next.
Arguments
- fit
A fit returned by
gllvmTMB().- level
Currently
"unit"only. Legacy alias"B"is accepted.- type
"axis_effect"returns raw \(\boldsymbol\alpha\) coefficients on the latent-axis scale."trait_effect"returns \(\mathbf B_{\mathrm{lv}}\) on the trait linear-predictor scale.- conf.level
Confidence level for the interval (Wald, or the confidence level passed to the profile / bootstrap CI).
- method
Interval method.
"wald"is the only current public route. The nonlinear profile and predictor-effect bootstrap prototypes are withheld until constrained-fit diagnostics, failed-refit accounting, and repeated-sampling coverage evidence are available.- ...
Reserved for future interval routes; currently unused.
Value
A data frame. For type = "axis_effect", columns are level,
axis, predictor, estimate, std.error, lower, upper,
rotation_status and uncertainty_status. For
type = "trait_effect", columns are level, trait, predictor,
estimate, std.error, lower, upper, and uncertainty_status.
The uncertainty_status field states why standard errors are unavailable
(for example, skipped sdreport(), a non-positive-definite Hessian, or
non-finite standard errors) or labels finite Wald bounds as not yet
coverage-calibrated.
Details
If the axis-scale representation is specifically required and cross-fit
alignment matters, apply the same rotation used for the loadings: the
mean latent score is \(\mathbf X_s \boldsymbol\alpha\), so it rotates
exactly as the scores in rotate_loadings() do – \(\boldsymbol\alpha
\mathbf T\) for the rotation matrix T returned by
rotate_loadings(fit, level, method)$T (verified to reconstruct the
rotated mean score to machine precision). There is no separate exported
helper that performs this composition; it must be assembled from
rotate_loadings()'s T and the estimate column here.
For native TMB fits, std.error is populated from a positive-definite
sdreport() when available. Axis-effect SEs come from the fixed-parameter
block for alpha_lv_B; trait-effect SEs come from TMB's delta-method
ADREPORT(B_lv_unit) output. lower and upper are Wald intervals using
conf.level. Broad repeated-sampling coverage has not been established, so
finite bounds remain experimental rather than nominally calibrated. For Gaussian,
Poisson, NB2, Gamma, Beta, and binomial logit/probit/cloglog
engine = "julia" bridge fits, ci_method = "none" exposes point estimates
only (std.error, lower, and upper are NA). When the bridge supplies a
retained delta-method uncertainty data, extract_lv_effects() surfaces
finite std.error, lower, and upper. Those Julia bridge values are not
coverage-calibrated intervals.