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,
        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),… 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). 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. 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.
`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 `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 the environment variables `OPENBLAS_NUM_THREADS` and `MKL_NUM_THREADS` will be (possibly re)-assigned. 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 η 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.
`joint.hyper` | A matrix containing the joint density of the hyperparameters (in the internal scale)
`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 18.07.12 Index]