Skip to contents

Predictor effects on latent-score means

Source: R/extractors.R
extract_lv_effects.Rd

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. The trait-scale table is the rotation-invariant induced slope surface on the trait linear-predictor scale.

Usage

extract_lv_effects(
  fit,
  level = "unit",
  type = c("axis_effect", "trait_effect"),
  conf.level = 0.95,
  method = c("wald", "profile", "bootstrap"),
  ...
)

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

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.

See also

extract_ordination()