inlabru: component – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

component

Latent model component construction

Description

Similar to glm(), gam() and inla(), bru() models can be constructed via a formula-like syntax, where each latent effect is specified. However, in addition to the parts of the syntax compatible with INLA::inla, bru components offer additional functionality which facilitates modelling, and the predictor expression can be specified separately, allowing more complex and non-linear predictors to be defined. The formula syntax is just a way to allow all model components to be defined in a single line of code, but the definitions can optionally be split up into separate component definitions. See Details for more information.

The component methods all rely on the component.character() method, that defines a model component with a given label/name. The user usually doesn't need to call these methods directly, but can instead supply a formula expression that can be interpreted by the component_list.formula() method, called inside bru().

Usage

component(...)

## S3 method for class 'character'
component(
  object,
  main = NULL,
  weights = NULL,
  ...,
  model = NULL,
  mapper = NULL,
  main_layer = NULL,
  main_selector = NULL,
  n = NULL,
  values = NULL,
  season.length = NULL,
  copy = NULL,
  weights_layer = NULL,
  weights_selector = NULL,
  group = NULL,
  group_mapper = NULL,
  group_layer = NULL,
  group_selector = NULL,
  ngroup = NULL,
  control.group = NULL,
  replicate = NULL,
  replicate_mapper = NULL,
  replicate_layer = NULL,
  replicate_selector = NULL,
  nrep = NULL,
  A.msk = NULL,
  envir_extra = NULL
)

Arguments

`...`	Parameters passed on to other methods
`object`	A character label for the component
`main`	`main` takes an R expression that evaluates to where the latent variables should be evaluated (coordinates, indices, continuous scalar (for rw2 etc)). Arguments starting with weights, group, replicate behave similarly to main, but for the corresponding features of `INLA::f()`.
`weights, weights_layer, weights_selector`	Optional specification of effect scaling weights. Same syntax as for `main`.
`model`	Either one of "offset", "factor_full", "factor_contrast", "linear" or a model name or object accepted by INLA's `f` function. If set to NULL, then "linear" is used.
`mapper`	Information about how to do the mapping from the values evaluated in `main`, and to the latent variables. Auto-detects spde model objects in model and extracts the mesh object to use as the mapper, and auto-generates mappers for indexed models. (Default: NULL, for auto-determination)
`main_layer, main_selector`	The `_layer` is a numeric index or character name of which layer/variable to extract from a covariate data object given in `main` (Default: The effect component name, if it exists i the covariate object, otherwise the first column of the covariate data frame) The `_selector` is character name of a variable whose contents determines which layer to extract from a covariate for each data point. Overrides the `layer`. (Default: NULL)
`n`	The number of latent variables in the model. Should be auto-detected for most or all models (Default: NULL, for auto-detection). An error is given if it can't figure it out by itself.
`values`	Specifies for what covariate/index values INLA should build the latent model. Normally generated internally based on the mapping details. (Default: NULL, for auto-determination)
`season.length`	Passed on to `INLA::f()` for model `"seasonal"` (TODO: check if this parameter is still fully handled)
`copy`	character; label of other component that this component should be a copy of. If the `fixed = FALSE`, a scaling constant is estimated, via a hyperparameter. If `fixed = TRUE`, the component scaling is fixed, by default to 1; for fixed scaling, it's more efficient to express the scaling in the predictor expression instead of making a copy component.
`group, group_mapper, group_layer, group_selector, ngroup`	Optional specification of kronecker/group model indexing.
`control.group`	`list` of kronecker/group model parameters, currently passed directly on to `INLA::f`
`replicate, replicate_mapper, replicate_layer, replicate_selector, nrep`	Optional specification of indices for an independent replication model. Same syntax as for `main`
`A.msk`	TODO: check/fix/deprecate this parameter. Likely doesn't work at the moment, and I've found no examples that use it.
`envir_extra`	TODO: check/fix this parameter.

Details

bru() will understand formulae describing fixed effect models just like the other methods. For instance, the formula y ~ x will fit the linear combination of an effect named x and an intercept to the response y with respect to the likelihood family stated when calling bru(). Mathematically, the linear predictor η would be written down as

η = β * x + c,

where:

c is the intercept
x is a covariate
β is a random variable associated with x and
ψ = β * x is called the random effect of x

A problem that arises when using this kind of R formula is that it does not clearly relect the mathematical formula. For instance, when providing the formula to inla, the resulting object will refer to the random effect ψ = β * x as x. Hence, it is not clear if x refers to the covariate or the effect of the covariate.

The component.character method is inlabru's equivalent to INLA's f function but adds functionality that is unique to inlabru.

Deprecated parameters:

map: Use main instead.
mesh: Use mapper instead.

Naming random effects

In INLA, a simple random effect model would be expressed as

formula = y ~ f(x, model = "linear"),

where f() is the inla specific function to set up random effects of all kinds. The underlying predictor would again be η = β * x + c but the result of fitting the model would state x as the random effect's name. bru allows to rewrite this formula in order to explicitly state the name of the random effect and the name of the associated. This is achived by replacing f with an arbitrary name that we wish to assign to the effect, e.g.

components = y ~ psi(x, model = "linear").

Being able to discriminate between x and ψ is relevant because of two functionalities bru offers. The formula parameters of both, bru() and the prediction method predict.bru are interpreted in the mathematical sense. For instance, predict may be used to analyze the an analytical combination of the covariate x and the intercept using

predict(fit, data.frame(x=2)), ~ exp(psi + Intercept).

which corresponds to the mathematical expression \exp(x β + c).

On the other hand, predict may be used to only look at a transformation of the latent variable β_ψ

predict(fit, NULL, ~ exp(psi_latent)).

which corresponds to the mathematical expression \exp(β).

Author(s)

Fabian E. Bachl bachlfab@gmail.com and Finn Lindgren Finn.Lindgren@gmail.com

Examples

# As an example, let us create a linear component. Here, the component is
# called "myLinearEffectOfX" while the covariate the component acts on is
# called "x". Note that a list of components is returned because the
# formula may define multiple components

cmp <- component_list(~ myLinearEffectOfX(main = x, model = "linear"))
summary(cmp)
# Equivalent shortcuts:
cmp <- component_list(~ myLinearEffectOfX(x, model = "linear"))
cmp <- component_list(~ myLinearEffectOfX(x))
# Individual component
cmp <- component("myLinearEffectOfX", main = x, model = "linear")
summary(cmp)

if (require("INLA", quietly = TRUE)) {

  # As an example, let us create a linear component. Here ,the component is
  # called "myEffectOfX" while the covariate the component acts on is called "x":

  eff <- component("myEffectOfX", main = x, model = "linear")
  summary(eff)

  # A more complicated component:
  eff <- component("myEffectOfX",
    main = x,
    model = inla.spde2.matern(inla.mesh.1d(1:10))
  )
}

inlabru

Bayesian Latent Gaussian Modelling using INLA and Extensions

v2.3.1

GPL (>= 2)

Authors

Finn Lindgren [aut, cre, cph] (<https://orcid.org/0000-0002-5833-2011>, Finn Lindgren continued development of the main code), Fabian E. Bachl [aut, cph] (Fabian Bachl wrote the main code), David L. Borchers [ctb, dtc, cph] (David Borchers wrote code for Gorilla data import and sampling, multiplot tool), Daniel Simpson [ctb, cph] (Daniel Simpson wrote the basic LGCP sampling method), Lindesay Scott-Howard [ctb, dtc, cph] (Lindesay Scott-Howard provided MRSea data import code), Seaton Andy [ctb] (Andy Seaton provided testing and bugfixes)

Initial release