Extract ordinal cutpoints from a fitted gllvmTMB model

For traits fitted with ordinal_probit() or ordinal_logit(), returns a tidy data frame with the K - 2 estimated cutpoints \(\tau_2, \ldots, \tau_{K-1}\) per trait, with optional standard errors from the joint sdreport.

Usage

extract_cutpoints(fit, quiet = FALSE)

Arguments

fit: A fit returned by gllvmTMB() with at least one ordinal_probit() or ordinal_logit() trait.
quiet: Suppress the note emitted when tau_se cannot be filled in because the fit has no sd_report. Internal callers that display only the cutpoint estimates (print(), tidy()) pass TRUE: a note explaining an absent standard-error column is noise when no such column is shown.

Value

A data frame with columns

trait: Trait label (factor level from data[[trait]]).
cutpoint_index: Integer index \(k \in \{2, \ldots, K-1\}\).
cutpoint_label: Character label "cutpoint_<k>".
tau_estimate: Estimated \(\tau_k\) on the trait's own latent scale (probit for an ordinal_probit() trait, logit for an ordinal_logit() trait).
tau_se: Standard error from the joint sdreport, or NA if the report is unavailable.

If the fit contains no ordinal_probit() or ordinal_logit() traits, returns a zero-row data frame with the same columns.

Details

Convention: gllvmTMB follows Hadfield (2015) — \(\tau_1 = 0\) is fixed for identifiability and the K - 2 free cutpoints are reported as cutpoint_2, cutpoint_3, etc. This differs from brms, which reports K - 1 cutpoints as Intercept[1..K-1].

This extractor includes Wald standard errors, so it refuses fits made with non-unit likelihood weights. The fitted cutpoint parameters remain point estimates, but weighted-objective uncertainty is not calibrated.

References

Hadfield, J. D. (2015). Increasing the efficiency of MCMC for hierarchical phylogenetic models of categorical traits using reduced mixed models. Methods Ecol. Evol. 6:706-714. doi:10.1111/2041-210X.12354

Examples

if (FALSE) { # \dontrun{
fit <- gllvmTMB(
  value ~ 0 + trait + phylo_indep(species, tree = tree),
  data    = ordinal_dat,
  trait   = "trait",
  unit    = "individual",
  cluster = "species",
  family  = ordinal_probit()
)
extract_cutpoints(fit)
} # }