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_multi 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 = 2,
  parm.range = c(-Inf, Inf)
)

Arguments

fit

A gllvmTMB_multi 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

For non-linear derived quantities (ICC, communality, repeatability, correlations, phylogenetic signal H^2), see the helpers in R/profile-derived.R.

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. In that case the bound is at the natural boundary of the parameter space, not unknown. tmbprofile_wrapper() therefore 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). NA is reserved for genuine profile failure (e.g. tmbprofile() threw an error or returned too few points).