buildAGHQGrid {nimble}

Build Adaptive Gauss-Hermite Quadrature Grid

Description

Create quadrature grid for use in AGHQuad methods in Nimble.

Arguments

d

Dimension of quadrature grid being requested.

nQuad

Number of quadrature nodes requested on build.

Details

This function is used by used by buildOneAGHQuad1D and buildOneAGHQuad create the quadrature grid using adaptive Gauss-Hermite quadrature. Handles single or multiple dimension grids and computes both grid locations and weights. Additionally, acts as a cache system to do transformations, and return marginalized log density.

Any of the input node vectors, when provided, will be processed using nodes <- model$expandNodeNames(nodes), where nodes may be paramNodes, randomEffectsNodes, and so on. This step allows any of the inputs to include node-name-like syntax that might contain multiple nodes. For example, paramNodes = 'beta[1:10]' can be provided if there are actually 10 scalar parameters, 'beta[1]' through 'beta[10]'. The actual node names in the model will be determined by the exapndNodeNames step.

Available methods include

• buildAGHQ. Builds a adaptive Gauss-Hermite quadrature grid in d dimensions. Calls buildAGHQOne to build the one dimensional grid and then expands in each dimension. Some numerical issues occur in Eigen decomposition making the grid weights only accurate up to 35 quadrature nodes.

• Options to get internally cached values are getGridSize, getModeIndex for when there are an odd number of quadrature nodes, getLogDensity for the cached values, getAllNodes for the quadrature grids, getNodes for getting a single indexed nodes, getAllNodesTransformed for nodes transformed to the parameter scale, getNodesTransformed for a single transformed node, getAllWeights to get all quadrature weights, getWeights single indexed weight.

• transformGrid(cholNegHess, inner_mode, method) transforms the grid using either cholesky trasnformations, as default, or spectral that makes use of the Eigen decomposition. For a single dimension transformGrid1D is used.

• As the log density is evaluated externally, it is saved via saveLogDens, which then is summed via quadSum.

• buildGrid builds the grid the initial time and is only run once in code. After, the user must choose to setGridSize to update the grid size.

• check. If TRUE (default), a warning is issued if paramNodes, randomEffectsNodes and/or calcNodes are provided but seek to have missing elements or unnecessary elements based on some default inspection of the model. If unnecessary warnings are emitted, simply set check=FALSE.

• innerOptimControl. A list of control parameters for the inner optimization of Laplace approximation using optim. See 'Details' of optim for further information.

• innerOptimMethod. Optimization method to be used in optim for the inner optimization. See 'Details' of optim. Currently optim in NIMBLE supports: "Nelder-Mead", "BFGS", "CG", and "L-BFGS-B". By default, method "CG" is used when marginalizing over a single (scalar) random effect, and "BFGS" is used for multiple random effects being jointly marginalized over.

• innerOptimStart. Choice of starting values for the inner optimization. This could be "last", "last.best", or a vector of user provided values. "last" means the most recent random effects values left in the model will be used. When finding the MLE, the most recent values will be the result of the most recent inner optimization for Laplace. "last.best" means the random effects values corresponding to the largest Laplace likelihood (from any call to the calcLaplace or calcLogLik method, including during an MLE search) will be used (even if it was not the most recent Laplace likelihood). By default, the initial random effects values will be used for inner optimization.

• outOptimControl. A list of control parameters for maximizing the Laplace log-likelihood using optim. See 'Details' of optim for further information.

References

Golub, G. H. and Welsch, J. H. (1969). Calculation of Gauss Quadrature Rules. Mathematics of Computation 23 (106): 221-230.

Liu, Q. and Pierce, D. A. (1994). A Note on Gauss-Hermite Quadrature. Biometrika, 81(3) 624-629.

Jackel, P. (2005). A note on multivariate Gauss-Hermite quadrature. London: ABN-Amro. Re.