Skip to contents

Profile-likelihood CI for one parameter or linear combination

Source: R/profile-ci.R
tmbprofile_wrapper.Rd

Wraps TMB::tmbprofile() with a chi-square root-finding step to return a 95% (or other-level) confidence interval for a single parameter (or a fixed linear combination of parameters) on a fitted gllvmTMB model. The profile is computed in TMB's C++ inner optim warm-started from the joint MLE — typically order-of-magnitude faster than refitting under a constraint in pure R.

Usage

tmbprofile_wrapper(
  fit,
  name = NULL,
  which = 1L,
  lincomb = NULL,
  level = 0.95,
  transform = identity,
  ystep = 0.5,
  ytol = NULL,
  parm.range = c(-Inf, Inf)
)

Arguments

fit

A fit returned by gllvmTMB().

name

Either:

  • A single character string giving the parameter name (matched against names(fit$opt$par); for vector parameters use which to pick the entry), OR

  • a single integer giving the index into fit$opt$par.

which

For vector-valued parameters (e.g. theta_diag_B is length T), the index within the named-block. Default 1.

lincomb

Optional numeric vector of length length(fit$opt$par) giving a linear combination of fixed-effect parameters to profile. When supplied, name is ignored. Used internally for total-variance contrasts (e.g. theta_diag_B[t] + theta_diag_W[t] for a per-trait total log-variance).

level

Confidence level in (0, 1). Default 0.95.

transform

Optional function applied to the profile-CI bounds before returning. Pass exp to convert log-SD to SD; pass \(x) exp(2 * x) for variance from log-SD. Default identity.

ystep, ytol

Passed through to TMB::tmbprofile(). The defaults give a fast, robust profile for variance components.

parm.range

Passed through to TMB::tmbprofile(). Default c(-Inf, Inf); for log-scale parameters with a hard lower bound, constrain via e.g. c(-15, Inf) so the profile does not chase variance to zero.

Value

A length-3 named numeric vector (estimate, lower, upper). lower or upper may be NA when the profile is one-sided (variance pinned at boundary).

Details

This wrapper profiles direct TMB parameters and fixed linear combinations. Structured-term source-strength intervals are not supported: requests for its raw logit parameter, by name, index, or linear combination, are rejected. Nonlinear targets such as communality, full-covariance repeatability, and correlations are not routed through this function. The phylogenetic-signal extractor documents its narrower two-component profile route; other nonlinear extractors state explicitly when only Wald, bootstrap, or point estimates are available.

Boundary behaviour

When a variance component is near zero, the profile likelihood becomes one-sided: the parameter can decrease to negative infinity in log-SD space (variance to zero) without an additional likelihood penalty. The profile deviance then flattens without ever crossing the threshold, and the bound really is at the natural boundary of the parameter space. tmbprofile_wrapper() returns the transformed boundary (e.g. lower = 0 for transform = exp, lower = 0 for transform = plogis, lower = -1 for transform = tanh, lower = -Inf for transform = identity).

A profile can also fail to cross the threshold for a quite different reason: the search stopped while the deviance was still climbing. The bound is then unknown, not infinite, and reporting a boundary would assert an unbounded parameter on the strength of having stopped looking. These two cases are separated from the trace itself – an asymptoting profile's outward slope decays toward zero, a truncated one's does not – and the truncated case returns NA.

NA therefore covers both genuine profile failure (e.g. tmbprofile() threw an error or returned too few points) and a bound that could not be determined within the search budget. .profile_bounds() reports which via its lower_status/upper_status fields ("crossed", "asymptotic", "truncated", "failed").