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

marginal_laplace_tmb {aghq}

R Documentation

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