inla {INLA}R Documentation

Bayesian analysis of structured additive models

Description

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

Usage

 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,
    lp.scale = NULL,
    control.compute = list(),
    control.predictor = list(),
    control.family = list(),
    control.inla = list(),
    control.fixed = list(),
    control.mode = list(),
    control.expert = list(),
    control.hazard = list(),
    control.lincomb = list(),
    control.update = list(),
    control.lp.scale = list(),
    control.pardiso = 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"),
    inla.mode = c("classic", "twostage", "experimental"), 
    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),… to compute for each posterior marginal. The function returns, for each posterior marginal, the values x(0), x(1),… such that

Prob(X<x)=p

E

Known component in the mean for the Poisson likelihoods defined as

E exp(eta)

where

eta

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). WARNING: The normalizing constant for the likelihood is NOT recomputed, so ALL marginals (and the marginal likelihood) must be interpreted with great care.

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.

lp.scale

A vector with same length as the predictor going into the likelihood with either NA's or indices indexing the scaling coefficients. NA or a index less or equal to 0 means no scaling. The priors and properties of the scaling coefficients are set in control.lp.scale

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.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

control.lp.scale

See ?control.lp.scale

control.pardiso

See ?control.pardiso

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, or as 'A:B' defining the number threads in the outer (A) and inner (B) layer for nested parallelism.

blas.num.threads

The absolute value of blas.num.threads is the maximum number of threads the the openblas/mklblas will use (if available). Value is ignored if <=0 (then environment variables are used).

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.

inla.mode

Run inla in classic-mode, twostage-mode or the new experimental-mode? Not all features are available int the experimental-mode and this mode is really work-in-progress at the moment!!!! Default is to use the mode set by inla.getOption("inla.mode") which is default classic-mode.

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

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 η in the model

marginals.linear.predictor

If compute=TRUE in control.predictor, a list containing the posterior marginals of the linear predictors η in the model.

summary.fitted.values

A matrix containing the mean and sd (plus, possibly quantiles and cdf) of the fitted values g^{-1}(η) 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}(η) 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

Author(s)

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

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

See Also

f, inla.hyperpar

Examples

 ## Not run: 
 ##See the web page \url{www.r-inla.org} for a series of worked out examples
 
## End(Not run)
 

[Package INLA version 21.11.22 Index]