marginal_laplace_tmb: AGHQ-normalized marginal Laplace approximation from a TMB...

In aghq: Adaptive Gauss Hermite Quadrature for Bayesian Inference

AGHQ-normalized marginal Laplace approximation from a TMB function template

Description

Implement the algorithm from aghq::marginal_laplace(), but making use of TMB's automatic Laplace approximation. This function takes a function list from TMB::MakeADFun() with a non-empty set of random parameters, in which the fn and gr are the unnormalized marginal Laplace approximation and its gradient. It then calls aghq::aghq() and formats the resulting object so that its contents and class match the output of aghq::marginal_laplace() and are hence suitable for post-processing with summary, aghq::sample_marginal(), and so on.

Usage

marginal_laplace_tmb(
  ff,
  k,
  startingvalue,
  transformation = default_transformation(),
  optresults = NULL,
  basegrid = NULL,
  control = default_control_tmb(),
  ...
)

Arguments

ff	The output of calling TMB::MakeADFun() with random set to a non-empty subset of the parameters. VERY IMPORTANT: TMB's automatic Laplace approximation requires you to write your template implementing the negated log-posterior. Therefore, this list that you input here will contain components fn, gr and he that implement the negated log-posterior and its derivatives. This is opposite to every other comparable function in the aghq package, and is done here to emphasize compatibility with TMB.
k	Integer, the number of quadrature points to use. I suggest at least 3. k = 1 corresponds to a Laplace approximation.
startingvalue	Value to start the optimization. ff$fn(startingvalue), ff$gr(startingvalue), and ff$he(startingvalue) must all return appropriate values without error.
transformation	Optional. Do the quadrature for parameter theta, but return summaries and plots for parameter g(theta). This applies to the theta parameters only, not the W parameters. transformation is either: a) an aghqtrans object returned by aghq::make_transformation, or b) a list that will be passed to that function internally. See ?aghq::make_transformation for details.
optresults	Optional. A list of the results of the optimization of the log posterior, formatted according to the output of aghq::optimize_theta. The aghq::aghq function handles the optimization for you; passing this list overrides this, and is useful for when you know your optimization is too difficult to be handled by general-purpose software. See the software paper for several examples of this. If you're unsure whether this option is needed for your problem then it probably is not.
basegrid	Optional. Provide an object of class NIGrid from the mvQuad package, representing the base quadrature rule that will be adapted. This is only for users who want more complete control over the quadrature, and is not necessary if you are fine with the default option which basically corresponds to mvQuad::createNIGrid(length(theta),'GHe',k,'product'). Note: the mvQuad functions used within aghq operate on grids in memory, so your basegrid object will be changed after you run aghq.
control	A list of control parameters. See ?default_control for details. Valid options are: method: optimization method to use for the theta optimization: 'sparse_trust' (default): trustOptim::trust.optim 'sparse': trust::trust 'BFGS': optim(...,method = "BFGS") inner_method: optimization method to use for the W optimization; same options as for method. Default inner_method is 'sparse_trust' and default method is 'BFGS'. negate: default TRUE. See ?default_control_tmb. Assumes that your TMB function template computes the negated log-posterior, which it must if you're using TMB's automatic Laplace approximation, which you must be if you're using this function! .
...	Additional arguments to be passed to ff$fn, ff$gr, and ff$he.

Details

Because TMB does not yet have the Hessian of the log marginal Laplace approximation implemented, a numerically-differentiated jacobian of the gradient is used via numDeriv::jacobian(). You can turn this off (using ff$he() instead, which you'll have to modify yourself) using default_control_tmb(numhessian = FALSE).

Value

If k > 1, an object of class marginallaplace (and inheriting from class aghq) of the same structure as that returned by aghq::marginal_laplace(), with plot and summary methods, and suitable for input into aghq::sample_marginal() for drawing posterior samples.

See Also

Other quadrature: aghq(), get_hessian(), get_log_normconst(), get_mode(), get_nodesandweights(), get_numquadpoints(), get_opt_results(), get_param_dim(), laplace_approximation(), marginal_laplace(), nested_quadrature(), normalize_logpost(), optimize_theta(), plot.aghq(), print.aghqsummary(), print.aghq(), print.laplacesummary(), print.laplace(), print.marginallaplacesummary(), summary.aghq(), summary.laplace(), summary.marginallaplace()

aghq documentation built on June 7, 2023, 5:10 p.m.