Bayesian analysis of structured additive models

inla performs a full Bayesian analysis of additive models using Integrated Nested Laplace approximation

inla(
    formula,
    family = "gaussian", 
    contrasts = NULL,
    data,
    quantiles=c(0.025, 0.5, 0.975),
    E = NULL,
    offset=NULL,
    scale = NULL,
    weights = NULL,
    Ntrials = NULL,
    strata = NULL,
    link.covariates = NULL,
    verbose = FALSE,
    lincomb = NULL,
    selection = NULL,
    control.compute = list(),
    control.predictor = list(),
    control.family = list(),
    control.inla = list(),
    control.results = list(),
    control.fixed = list(),
    control.mode = list(),
    control.expert = list(),
    control.hazard = list(),
    control.lincomb = list(),
    control.update = list(), 
    only.hyperparam = FALSE,
    inla.call = inla.getOption("inla.call"),
    inla.arg = inla.getOption("inla.arg"),
    num.threads = inla.getOption("num.threads"),
    blas.num.threads = inla.getOption("blas.num.threads"),
    keep = inla.getOption("keep"),
    working.directory = inla.getOption("working.directory"),
    silent = inla.getOption("silent"),
    debug = inla.getOption("debug"), 
    .parent.frame = parent.frame()
    )

Arguments

formula: A inla formula like y ~1 + z + f(ind, model="iid") + f(ind2, weights, model="ar1") This is much like the formula for a glm except that smooth or spatial terms can be added to the right hand side of the formula. See f for full details and the web site www.r-inla.org for several worked out examples. Each smooth or spatial term specified through f should correspond to separate column of the data frame data. The response variable, y can be a univariate response variable, a list or the output of the function inla.surf for survival analysis models.
family: A string indicating the likelihood family. The default is gaussian with identity link. See names(inla.models()$likelihood) for a list of possible alternatives and use inla.doc for detailed docs for individual families.
contrasts: Optional contrasts for the fixed effects; see ?lm or ?glm for details.
data: A data frame or list containing the variables in the model. The data frame MUST be provided
quantiles: A vector of quantiles, $p(0), p(1),\dots$ to compute for each posterior marginal. The function returns, for each posterior marginal, the values $x(0), x(1),\dots$ such that $$\mbox{Prob}(X<x(p))=p$$
E: Known component in the mean for the Poisson likelihoods defined as $$E_i\exp(\eta_i)$$ where $$\eta_i$$ is the linear predictor. If not provided it is set to rep(1, n.data).
offset: This argument is used to specify an a-priori known and fixed component to be included in the linear predictor during fitting. This should be NULL or a numeric vector of length either one or equal to the number of cases. One or more offset() terms can be included in the formula instead or as well, and if both are used, they are combined into a common offset. If the A-matrix is used in the linear predictor statement control.predictor, then the offset given in this argument is added to eta*, the linear predictor related to the observations, as eta* = A eta + offset, whereas an offset in the formula is added to eta, the linear predictor related to the formula, as eta = ... + offset.formula. So in this case, the offset defined here and in the formula has a different meaning and usage.
scale: Fixed (optional) scale parameters of the precision for Gaussian and Student-T response models. Default value is rep(1, n.data).
weights: Fixed (optional) weights parameters of the likelihood, so the log-likelihood[i] is changed into weights[i]*log-likelihood[i]. Default value is rep(1, n.data). Due to the danger of mis-interpreting the results (see below), this option is DISABLED by default. You can enable this option for the rest of your R session, doing inla.setOption(enable.inla.argument.weights=TRUE). WARNING: The normalizing constant for the likelihood is NOT recomputed, so ALL marginals (and the marginal likelihood) must be interpreted with great care. Possibly, you may want to set the prior for the hyperparameters to "uniform" and the integration strategy to "eb" to mimic a maximum-likelihood approach.
Ntrials: A vector containing the number of trials for the binomial likelihood and variantes, or the number of required successes for the nbinomial2 likelihood. Default value is rep(1, n.data).
strata: Fixed (optional) strata indicators for tstrata likelihood model.
link.covariates: A vector or matrix with covariates for link functions
verbose: Boolean indicating if the inla-program should run in a verbose mode (default FALSE).
lincomb: Used to define linear combination of nodes in the latent field. The posterior distribution of such linear combination is computed by the inla function. See www.r-inla.org/faq for examples of how to define such linear combinations.
selection: This is a similar argument to the one in inla.posterior.sample and follow the same format. This argument allows to define a subset of the latent field for which to compute an approximated joint distribution. It will appear in result$selection. See also ?inla.rjmarginal.
control.compute: See ?control.compute
control.predictor: See ?control.predictor
control.family: See ?control.family
control.inla: See ?control.inla
control.results: See ?control.result
control.fixed: See ?control.fixed
control.mode: See ?control.mode
control.expert: See ?control.expert
control.hazard: See ?control.hazard
control.lincomb: See ?control.lincomb
control.update: See ?control.update
only.hyperparam: A boolean variable saying if only the hyperparameters should be computed. This option is mainly used internally. (TODO: This option should not be located here, change it!)
inla.call: The path to, or the name of, the inla-program. This is program is installed together with the R-package, but, for example, a native compiled version can be used instead to improve the performance.
inla.arg: A string indicating ALL arguments to the 'inla' program and do not include default arguments. (OOPS: This is an expert option!)
num.threads: Maximum number of threads the inla-program will use
blas.num.threads: The absolute value of blas.num.threads is the maximum number of threads the the openblas/mklblas will use (if available). If blas.num.threads > 0, then the environment variables OPENBLAS_NUM_THREADS and MKL_NUM_THREADS will be assigned. If blas.num.threads < 0, then the environment variables OPENBLAS_NUM_THREADS and MKL_NUM_THREADS will be assigned unless they are already defined. If blas.num.threads = 0, then variables OPENBLAS_NUM_THREADS and MKL_NUM_THREADS will be removed.
keep: A boolean variable indicating that the working files (ini file, data files and results files) should be kept. If TRUE and no working.directory is specified the working files are stored in a directory called "inla".
working.directory: A string giving the name of an non-existing directory where to store the working files.
silent: If equal to 1L or TRUE, then the inla-program would be “silent”. If equal to 2L, then supress also error messages from the inla-program.
debug: If TRUE, then enable some debug output.
.parent.frame: Internal use only

Value

inla returns an object of class "inla". This is a list containing at least the following arguments:

summary.fixed: Matrix containing the mean and standard deviation (plus, possibly quantiles and cdf) of the the fixed effects of the model.
marginals.fixed: A list containing the posterior marginal densities of the fixed effects of the model.
summary.random: List of matrices containing the mean and standard deviation (plus, possibly quantiles and cdf) of the the smooth or spatial effects defined through f().
marginals.random: If return.marginals.random=TRUE in control.results (default), a list containing the posterior marginal densities of the random effects defined through f.
summary.hyperpar: A matrix containing the mean and sd (plus, possibly quantiles and cdf) of the hyperparameters of the model
marginals.hyperpar: A list containing the posterior marginal densities of the hyperparameters of the model.
summary.linear.predictor: A matrix containing the mean and sd (plus, possibly quantiles and cdf) of the linear predictors $\eta$ in the model
marginals.linear.predictor: If compute=TRUE in control.predictor, a list containing the posterior marginals of the linear predictors $\eta$ in the model.
summary.fitted.values: A matrix containing the mean and sd (plus, possibly quantiles and cdf) of the fitted values $g^{-1}(\eta)$ obtained by transforming the linear predictors by the inverse of the link function. This quantity is only computed if marginals.fitted.values is computed. Note that if an observation is NA then the identity link is used. You can manually transform a marginal using inla.marginal.transform() or set the argument link in the control.predictor-list; see ?control.predictor
marginals.fitted.values: If compute=TRUE in control.predictor, a list containing the posterior marginals of the fitted values $g^{-1}(\eta)$ obtained by transforming the linear predictors by the inverse of the link function. Note that if an observation is NA then the identity link is used. You can manually transform a marginal using inla.marginal.transform() or set the argument link in the control.predictor-list; see ?control.predictor
summary.lincomb: If lincomb != NULL a list of matrices containing the mean and sd (plus, possibly quantiles and cdf) of all linear combinations defined.
marginals.lincomb: If lincomb != NULL a list of posterior marginals of all linear combinations defined.
selection: Provide the approximated joint distribution for the selection
dic: If dic=TRUE in control.compute, the deviance information criteria and effective number of parameters, otherwise NULL
cpo: If cpo=TRUE in control.compute, a list of three elements: cpo$cpo are the values of the conditional predictive ordinate (CPO), cpo$pit are the values of the probability integral transform (PIT) and cpo$failure indicates whether some assumptions are violated. In short, if cpo$failure[i] > 0 then some assumption is violated, the higher the value (maximum 1) the more seriously.
po: If po=TRUE in control.compute, a list of one elements: po$po are the values of the predictive ordinate (CPO) (pi(yi|y))
waic: If waic=TRUE in control.compute, a list of two elements: waic$waic is the Watanabe-Akaike information criteria, and waic$p.eff is the estimated effective number of parameters
mlik: If mlik=TRUE in control.compute, the log marginal likelihood of the model (using two different estimates), otherwise NULL
neffp: Expected effective number of parameters in the model. The standard deviation of the expected number of parameters and the number of replicas for parameter are also returned
mode: A list of two elements: mode$theta is the computed mode of the hyperparameters and mode$x is the mode of the latent field given the modal value of the hyperparamters.
call: The matched call.
formula: The formula supplied
nhyper: The number of hyperparameters in the model
cpu.used: The cpu time used by the inla function

References

Rue, H. and Martino, S. and Chopin, N. (2009) Approximate Bayesian Inference for latent Gaussian models using Integrated Nested Laplace Approximations, JRSS-series B (with discussion), vol 71, no 2, pp 319-392. Rue, H and Held, L. (2005) Gaussian Markov Random Fields - Theory and Applications Chapman and Hall

Author

Havard Rue hrue@r-inla.org and Sara Martino

Examples