List profile-ready confidence-interval targets for a fitted model

profile_targets() is an advanced inventory for users who need to diagnose or script profile confidence intervals. Most users should start with confint.gllvmTMB_multi() or a report-ready extractor such as extract_correlations(). This helper tells you which parm labels can be profiled directly.

Usage

profile_targets(object, ready_only = FALSE)

Arguments

object: A fit returned by gllvmTMB().
ready_only: If TRUE, return only rows with profile_ready = TRUE. Default FALSE returns the full inventory.

Value

A data frame with one row per target and the following columns:

parm: User-facing target label, e.g. b_fix[1], sigma_eps, or sd_B[2].
target_class: One of fixed_effect, variance, dispersion, loading_packed, threshold, or scaling.
tmb_parameter: TMB-side parameter name (matches names(fit$opt$par)).
index: 1-based index within the TMB parameter vector. NA for scalars.
estimate: Point estimate on the natural scale (e.g. sigma_eps = exp(log_sigma_eps)).
link_estimate: Point estimate on the optimisation scale (the TMB internal scale).
scale: Either "natural" (after applying the transformation) or "link" (for raw packed entries).
transformation: Currently emitted: linear_predictor, exp, logit_p_tweedie, lambda_packed, or ordinal_threshold. Reserved (allowed, not currently returned): logit.
target_type: Always "direct" for currently returned rows.
profile_ready: TRUE iff the target can be passed directly to confint(fit, parm = ..., method = "profile").
profile_note: One of ready, tmb_object_required, missing_tmb_parameter, or latent_rotation_ambiguous.

Details

The returned tidy data frame has one row per profile target and records whether the target is profile-ready and, if not, why. Direct targets correspond to a single TMB parameter element (for example b_fix[1], sigma_eps, or sd_B[2]) and can be passed to confint(fit, parm = ..., method = "profile"). Nonlinear derived targets are excluded because their former penalty-profile routes are withheld.

Scope: the controlled vocabulary and direct-profile routing is covered for fitted models with retained TMB objects. Broader target-explicit profile calibration remains future work.

The output uses a controlled vocabulary for direct target classes, transformations, and readiness notes.

Examples

set.seed(1)
# Four traits measured twice on each of 80 units (e.g. individuals),
# sharing one latent axis.
sim <- simulate_unit_trait(n_units = 80, n_obs_per_unit = 2,
                           n_traits = 4,
                           Lambda_B = matrix(c(0.9, 0.8, -0.7, 0.5)),
                           psi_B = 0.3, sigma2_eps = 0.3)
fit <- gllvmTMB(value ~ 0 + trait +
                  latent(0 + trait | unit, d = 1, unique = TRUE),
                data = sim$data, trait = "trait", unit = "unit")

# One row per parameter that can be profiled on its own: the trait
# means (b_fix), the residual SD (sigma_eps), the loadings on the
# latent axis (Lambda_B_packed) and the SD of each trait's own
# unit-level variation beyond the shared axis (sd_B).
targets <- profile_targets(fit)
head(targets)
#>                 parm   target_class tmb_parameter index   estimate
#> 1           b_fix[1]   fixed_effect         b_fix     1 -0.6065603
#> 2           b_fix[2]   fixed_effect         b_fix     2  0.2283760
#> 3           b_fix[3]   fixed_effect         b_fix     3 -0.8798730
#> 4           b_fix[4]   fixed_effect         b_fix     4  1.6578120
#> 5          sigma_eps       variance log_sigma_eps    NA  0.5827980
#> 6 Lambda_B_packed[1] loading_packed    theta_rr_B     1  0.7740654
#>   link_estimate   scale   transformation target_type profile_ready profile_note
#> 1    -0.6065603 natural linear_predictor      direct          TRUE        ready
#> 2     0.2283760 natural linear_predictor      direct          TRUE        ready
#> 3    -0.8798730 natural linear_predictor      direct          TRUE        ready
#> 4     1.6578120 natural linear_predictor      direct          TRUE        ready
#> 5    -0.5399146 natural              exp      direct          TRUE        ready
#> 6     0.7740654    link    lambda_packed      direct          TRUE        ready

# ready_only = TRUE drops targets that cannot be profiled, for example
# when the fit no longer carries its TMB object. Here all are ready.
ready <- profile_targets(fit, ready_only = TRUE)
ready$parm
#>  [1] "b_fix[1]"           "b_fix[2]"           "b_fix[3]"          
#>  [4] "b_fix[4]"           "sigma_eps"          "Lambda_B_packed[1]"
#>  [7] "Lambda_B_packed[2]" "Lambda_B_packed[3]" "Lambda_B_packed[4]"
#> [10] "sd_B[1]"            "sd_B[2]"            "sd_B[3]"           
#> [13] "sd_B[4]"           

# The residual-SD label can be passed straight to confint() for its
# profile-likelihood interval.
confint(fit, parm = "sigma_eps")
#>               2.5 %    97.5 %
#> sigma_eps 0.5404067 0.6310422