Skip to contents

Recomputes a backend='julia', intoverpop='laplace' fit's log marginal likelihood by adaptive Gauss-Hermite quadrature over the same random-effect integral the Laplace approximation approximates, and reports how far the estimate would move if that integral were taken exactly.

Usage

ctLaplaceCheck(
  fit,
  nodes = 5L,
  correction = TRUE,
  step = 0.001,
  refine = FALSE,
  maxiter = 50L,
  cores = getOption("mc.cores", 2L),
  verbose = 0L
)

Arguments

fit

A ctJuliaFit fitted with intoverpop='laplace'.

nodes

Quadrature nodes per random effect. Cost is nodes^k process log likelihoods per block, where k is that level's number of random effects; 5 is enough to locate the maximum in the cases tested, 9 to settle the value.

correction

Compute the first-order correction to the estimate. Costs 2 * npar quadrature evaluations, and needs the fit's Hessian, so it is skipped when uncertainty was not computed.

step

Finite-difference step for the gap gradient, on the raw scale.

refine

Continue the fit on the quadrature objective rather than correcting linearly: the refined fit intoverpop = 'quadrature' runs at fit time (see ctFit), from this fit's estimate, with the quadrature rules placed at every point. Its gradient is exact, so it costs a quadrature gradient per step rather than the 2 * npar quadrature evaluations per gradient the finite-difference refinement this replaced cost, and it reports the point it reaches in refined.

maxiter

Iteration cap for the climb of refine.

cores

Engine threads for the quadrature.

verbose

Integer; 1 or more prints progress.

Value

A list with gap (quadrature minus Laplace log marginal at the estimate), gap_per_subject, nodes, and, when correction is TRUE, a parameters data frame with one row per raw parameter giving estimate, delta, corrected, se and delta_se. With refine it also carries refined. at says whether the estimate checked was the Laplace optimum ('laplace') or already quadrature-corrected ('corrected').

dropped_directions counts the directions of the information matrix the correction does not step along, whose correction is reported as zero rather than as the arbitrarily large step an unguarded solve would produce: exactly the directions fit$identifiability names, those whose curvature is negligible or not positive and those the likelihood was measured flat along. On a model where the Laplace approximation is already exact the gap gradient is floating-point noise, and dividing that by a near-singular curvature is how a meaningless correction gets a plausible-looking number.

Details

The quadrature is adaptive in the usual sense: it is centred at each subject's inner mode and scaled by the inverse of the inner curvature there, both of which the fit has already computed. The curvature's eigenvalues are clipped from below at one, the prior's own curvature, before scaling: where the likelihood has gone convex in the random effects an unclipped rule puts its nodes far outside the prior and misses the mass it is meant to measure (1.8 nats too high on average on near-singular units in simulation, 0.06 clipped). Where every eigenvalue is at least one nothing changes.

The gap is quadrature minus the fit's own Laplace term, the quantity the fit maximised. With nodes = 1 that gap is zero wherever the curvature is at least the prior's, which is what makes the comparison meaningful – the two are integrating the same thing by different rules. On a unit with an eigenvalue below one it is not zero even at one node: the one-point clipped rule is the eigenwise-floored term, below the fit's.

The correction is a single Newton step, delta = solve(-hessian, gradient of (quadrature - laplace)), evaluated at the estimate. Read it against the standard errors: delta / se well below one says the approximation is not what limits the answer, and near or above one says the point estimate is approximation-limited and the interval will not cover whatever width it has.

A fit can be refined, with its units' random effects integrated by quadrature, when it is fitted (ctFit(intoverpop = 'quadrature')) or after (ctFitUncertainty(fit, intoverpop = 'quadrature')); by default it only runs the random-effects check, which warns where integrating would move an estimate. On a corrected fit this check is made at the corrected estimate, which is not a Laplace optimum: the correction reported is then the further Newton step on the quadrature objective from there, with the Laplace gradient included, and at on the result is 'corrected'. A small further step says the correction got there; a large one says it did not. On any other fit it is the first step.

Nested groupings are handled. A group's integral does not factor over its members, but it does factor conditionally – given the group effect the members are independent – so the rule recurses over the same block tree the fit already builds, at a cost linear in the number of groups at each level rather than exponential in the number of members.

See also

ctFitUncertainty with method = 'sample' and intoverpop = 'none' removes the approximation instead of measuring it, by sampling the joint posterior; much slower, and the right answer when delta_se says a linear correction is not credible.

Examples

if (FALSE) { # \dontrun{
data <- ctstantestdat
model <- ctModel(type = 'ct', manifestNames = 'Y1', latentNames = 'eta1',
  LAMBDA = matrix(1))
model$pars$indvarying <- model$pars$matrix %in% 'MANIFESTMEANS'
fit <- ctFit(data, model, backend = 'julia', intoverpop = 'laplace')

check <- ctLaplaceCheck(fit)
check                     # gap, and the largest corrections in standard errors
check$parameters          # the full per-parameter table
} # }