runLaplace: Combine steps of running Laplace or adaptive Gauss-Hermite quadrature approximation

Description

Use an approximation (compiled or uncompiled) returned from `buildLaplace` or `buildAGHQ` to find the maximum likelihood estimate and return it with random effects estimates and/or standard errors.

Usage

runLaplace(
  laplace,
  pStart,
  method = "BFGS",
  originalScale = TRUE,
  randomEffectsStdError = TRUE,
  jointCovariance = FALSE
)
runAGHQ(
  AGHQ,
  pStart,
  method = "BFGS",
  originalScale = TRUE,
  randomEffectsStdError = TRUE,
  jointCovariance = FALSE
)

Value

A list with elements MLE and summary.

MLE is the result of the findMLE method, which contains the parameter estimates and Hessian matrix. This is considered raw output, and one should normally use instead the contents of summary. (For example not that the Hessian matrix in MLE may not correspond to the same scale as the parameter estimates if a transformation was used to operate in an unconstrained parameter space.)

summary is the result of summaryLaplace (or equivalently summaryAGHQ), which contains parameter estimates and standard errors, and optionally other requested components. All results in this object will be on the same scale (parameterization), either original or transformed, as requested.

Arguments

laplace: A (compiled or uncompiled) nimble laplace approximation object returned from `buildLaplace` or `buildAGHQ`. These return the same type of approximation algorithm object. `buildLaplace` is simply `buildAGHQ` with `nQuad=1`.
pStart: Initial values for parameters to begin optimization search for the maximum likelihood estimates. If omitted, the values currently in the (compiled or uncompiled) model object will be used.
method: Optimization method for outer optimization. See method argument to findMLE method in buildLaplace.
originalScale: If TRUE, return all results on the original scale of the parameters and/or random effects as written in the model. Otherwise, return all results on potentially unconstrained transformed scales that are used in the actual computations. Transformed scales (parameterizations) are used if any parameter or random effect has contraint(s) on its support (range of allowed values). Default = TRUE.
randomEffectsStdError: If TRUE, include standard errors for the random effects estimates. Default = TRUE.
jointCovariance: If TRUE, return the full joint covariance matrix (inverse of the Hessian) of parameters and random effects. Default = FALSE.
AGHQ: Same as laplace.

Details

Adaptive Gauss-Hermite quadrature is a generalization of Laplace approximation. runLaplace simply calles runAGHQ and provides a convenient name.

These functions manage the steps of calling the `findMLE` method to obtain the maximum likelihood estimate of the parameters and then the `summaryLaplace` function to obtain standard errors, (optionally) random effects estimates (conditional modes), their standard errors, and the full parameter-random effects covariance matrix.

Note that for `nQuad > 1` (see buildAGHQ), i.e., AGHQ with higher order than Laplace approximation, maximum likelihood estimation is available only if all random effects integrations are univariate. With multivariate random effects integrations, one can use `nQuad > 1` only to calculate marginal log likelihoods at given parameter values. This is useful for checking the accuracy of the log likelihood at the MLE obtained for Laplace approximation (`nQuad == 1`). `nQuad` can be changed using the `updateSettings` method of the approximation object.

See summaryLaplace, which is called for the summary components.