fit.bage_mod: Fit a Model

Description

Derive the posterior distribution for a model.

Usage

# S3 method for bage_mod
fit(
  object,
  method = c("standard", "inner-outer"),
  vars_inner = NULL,
  optimizer = c("multi", "nlminb", "BFGS", "CG"),
  quiet = TRUE,
  max_jitter = 1e-04,
  start_oldpar = FALSE,
  ...
)

Value

A bage_mod object

Arguments

object: A bage_mod object, created with mod_pois(), mod_binom(), or mod_norm().
method: Estimation method. Current choices are "standard" (the default) and "inner-outer". See below for details.
vars_inner: Names of variables to use for inner model when method is "inner-outer". If NULL(the default)vars_inner` is the age, sex/gender, and time variables.
optimizer: Which optimizer to use. Current choices are "multi", "nlminb", "BFGS", and "CG". Default is "multi". See below for details.
quiet: Whether to suppress messages from optimizer. Default is TRUE.
max_jitter: Maximum quantity to add to diagonal of precision matrix, if Cholesky factorization is failing. Default is 0.0001.
start_oldpar: Whether the optimizer should start at previous estimates. Used only when fit() is being called on a fitted model. Default is FALSE.
...: Not currently used.

Estimation methods

When method is "standard" (the default), all parameters, other than the lowest-level rates, probabilities, or means are jointly estimated within TMB.

When method is "inner-outer", estimation is carried out in multiple steps, which, in large models, can sometimes reduce computation times. In Step 1, a model only using the inner variables is fitted to the data. In Step 2, a model only using the outer variables is fitted to the data. In Step 3, values for dispersion are calculated. Parameter estimates from steps 1, 2, and 3 are then combined.

Optimizer

The choices for the optimizer argument are:

"multi" Try "nlminb", and if that fails, restart from the parameter values where "nlminb" stopped, using "BFGS". The default.
"nlminb" stats::nlminb()
"BFGS" stats::optim() using method "BFGS".
"GC" stats::optim() using method "CG" (conjugate gradient).

Cholesky factorization and <code>max_jitter</code>

Sampling from the posterior distribution requires performing a Cholesky factorization of the precision matrix returned by TMB. This factorization sometimes fails because of numerical problems. Adding a small quantity to the diagonal of the precision matrix can alleviate numerical problems, while potentially reducing accuracy. If the Cholesky factorization initially fails, bage will try again with progressively larger quantities added to the diagonal, up to the maximum set by max_jitter. Increasing the value of max_jitter can help suppress numerical problems. A safer strategy, however, is to simplify the model, or to use more informative priors.

Aggregation

Up to version 0.9.8 of bage, fit() always aggregated across cells with identical values of the predictor variables in formula (ie the variables to the right of ~) before fitting. For instance, if a dataset contained deaths and population disaggregated by age and sex, but the model formula was deaths ~ age, then fit() would aggregate deaths and population within each age category before fitting the model. From version 0.9.9, fit() only aggregates across cells with identical values if no data model is used, and if the model is Poisson with dispersion set to 0 or is normal. Note that this change in behavior has no effect on most models, since most models include all variables used to classify outcomes.

Examples

Run this code

## specify model
mod <- mod_pois(injuries ~ age + sex + year,
                data = nzl_injuries,
                exposure = popn)

## examine unfitted model
mod

## fit model
mod <- fit(mod)

## examine fitted model
mod

## extract rates
aug <- augment(mod)
aug

## extract hyper-parameters
comp <- components(mod)
comp

Run the code above in your browser using DataLab