Package 'inlabru'

Description

Convenient model fitting using (iterated) INLA.

Details

inlabru facilitates Bayesian spatial modelling using integrated nested Laplace approximations. It is heavily based on R-inla (https://www.r-inla.org) but adds additional modelling abilities and simplified syntax for (in particular) spatial models. Tutorials and more information can be found at https://inlabru-org.github.io/inlabru/ and http://www.inlabru.org/. The iterative method used for non-linear predictors is documented in the method vignette.

The main function for inference using inlabru is bru(). The general model specification details is documented in bru_comp() and bru_obs(). Posterior quantities beyond the basic summaries can be calculated with a predict() method, documented in predict.bru(). For point process inference lgcp() can be used as a shortcut to bru(..., bru_obs(model="cp", ...)).

The package comes with multiple real world data sets, namely gorillas, gorillas_sf, mexdolphin_sf. Plotting these data sets is straight forward using inlabru's extensions to ggplot2, e.g. the gg() function. For educational purposes some simulated data sets are available as well, e.g. Poisson1_1D, Poisson2_1D, Poisson2_1D and toygroups.

Author(s)

Fabian E. Bachl [email protected] and Finn Lindgren [email protected]

See Also

Useful links:

• http://www.inlabru.org

• https://inlabru-org.github.io/inlabru/

• https://github.com/inlabru-org/inlabru

• Report bugs at https://github.com/inlabru-org/inlabru/issues

Description

Methods for converting to bru_comp and bru_comp_list objects.

Usage

as_bru_comp(x, ...)

as_bru_comp_list(x, ...)

## S3 method for class 'bru_comp'
as_bru_comp(x, ...)

## S3 method for class 'bru_comp_list'
as_bru_comp_list(x, ...)

## S3 method for class 'bru_comp'
as_bru_comp_list(x, ...)

## S3 method for class 'bru'
as_bru_comp_list(x, ...)

## S3 method for class 'bru_info'
as_bru_comp_list(x, ...)

## S3 method for class 'bru_model'
as_bru_comp_list(x, ...)

## S3 method for class 'list'
as_bru_comp_list(x, ...)

## S3 method for class 'formula'
as_bru_comp_list(x, ...)

Arguments

Value

An object of class bru_comp_list.

Functions

• as_bru_comp_list(bru): Extract the component list from a bru() object.

• as_bru_comp_list(bru_info): Extract the component list from a bru_info() object.

• as_bru_comp_list(bru_model): Extract the component list from a bru_model() object.

See Also

as_bru_obs(), as_bru_obs_list()

Description

Extract a mapper from another object

Usage

as_bru_mapper(x)

## S3 method for class 'bru_mapper'
as_bru_mapper(x)

## S3 method for class 'bru_comp'
as_bru_mapper(x)

## S3 method for class 'bru_subcomp'
as_bru_mapper(x)

Arguments

Value

A bru_mapper object

Examples

# Extract a mapper from a `bru_subcomp` object
as_bru_mapper(bru_comp("x", x, mapper = bm_index(4))$main)

Description

Methods for converting to bru_obs and bru_obs_list objects.

Usage

as_bru_obs(x, ...)

as_bru_obs_list(x, .tag = NULL)

## S3 method for class 'bru_obs'
as_bru_obs(x, ...)

## S3 method for class 'bru_obs'
as_bru_obs_list(x, .tag = NULL)

## S3 method for class 'list'
as_bru_obs_list(x, .tag = NULL)

## S3 method for class 'bru_obs_list'
as_bru_obs_list(x, .tag = NULL)

## S3 method for class 'bru'
as_bru_obs_list(x, .tag = NULL)

## S3 method for class 'bru_info'
as_bru_obs_list(x, .tag = NULL)

## S3 method for class 'bru_model'
as_bru_obs_list(x, .tag = NULL)

Arguments

Value

An object of class bru_obs or bru_obs_list.

See Also

as_bru_comp_list()

Description

Adds posterior mean and credible interval columns to data. The user must supply pred_formula because inlabru prediction expressions are arbitrary R and cannot be recovered from the fit object alone.

Usage

## S3 method for class 'bru'
augment(x, data, pred_formula, n_samples = 500L, seed = NULL, ...)

Arguments

Value

data with additional columns .fitted, .fitted_low, .fitted_high, .fitted_sd.

Description

A common procedure of analyzing the distribution of 1D points is to chose a binning and plot the data's histogram with respect to this binning. This function compares the counts that the histogram calculates to simulations from a 1D log Gaussian Cox process conditioned on the number of data samples. For each bin this results in a median number of counts as well as a confidence interval. If the LGCP is a plausible model for the observed points then most of the histogram counts (number of points within a bin) should be within the confidence intervals. Note that a proper comparison is a multiple testing problem which the function does not solve for you.

Usage

bincount(
  result,
  predictor,
  observations,
  breaks,
  nint = 20,
  probs = c(0.025, 0.5, 0.975),
  ...
)

Arguments

Value

An data.frame with a ggplot attribute ggp

Examples

## Not run: 
if (require(ggplot2) && require(fmesher) && bru_safe_inla()) {
  # Load a point pattern
  data(Poisson2_1D)

  # Take a look at the point (and frequency) data

  ggplot(pts2) +
    geom_histogram(
      aes(x = x),
      binwidth = 55 / 20,
      boundary = 0,
      fill = NA,
      color = "black"
    ) +
    geom_point(aes(x), y = 0, pch = "|", cex = 4) +
    coord_fixed(ratio = 1)

  # Fit an LGCP model
  x <- seq(0, 55, length.out = 50)
  mesh1D <- fmesher::fm_mesh_1d(x, boundary = "free")
  matern <- INLA::inla.spde2.pcmatern(mesh1D,
    prior.range = c(1, 0.01),
    prior.sigma = c(1, 0.01),
    constr = TRUE
  )
  mdl <- x ~ spde1D(x, model = matern) + Intercept(1)
  fit.spde <- lgcp(mdl, pts2, domain = list(x = mesh1D))

  # Calculate bin statistics
  bc <- bincount(
    result = fit.spde,
    observations = pts2,
    breaks = seq(0, max(pts2), length.out = 12),
    predictor = x ~ exp(spde1D + Intercept)
  )

  # Plot them!
  attributes(bc)$ggp
}

## End(Not run)

Description

Constructs a mapper that aggregates elements of the input state, so it can be used e.g. for weighted summation or integration over blocks of values.

Usage

bm_aggregate(rescale = FALSE, n_block = NULL, type = NULL)

bru_mapper_aggregate(...)

Arguments

Value

A bm_aggregate mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_aggregate()
ibm_eval2(m, list(block = c(1, 2, 1, 2), weights = 1:4), 11:14)
ibm_eval2(m, list(block = c(1, 2, 1, 2), weights = 1:4, n_block = 3), 11:14)

Description

Constructs a concatenated collection mapping

Usage

bm_collect(mappers, hidden = FALSE)

bru_mapper_collect(...)

## S3 method for class 'bm_collect'
x[i, drop = TRUE]

## S3 method for class 'bru_mapper_collect'
x[i, drop = TRUE]

Arguments

Value

• [-indexing a bm_collect extracts a subset bm_collect object (for drop FALSE) or an individual sub-mapper (for drop TRUE, and i identifies a single element)

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

(m <- bm_collect(list(
  a = bm_index(2),
  b = bm_index(3)
), hidden = FALSE))
ibm_eval2(m, list(a = c(1, 2), b = c(1, 3, 2)), 1:5)

Description

Create a constant mapper

Usage

bm_const()

bru_mapper_const()

Value

A bm_const mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_const()
ibm_eval2(m, input = 1:4)

Description

Create a factor mapper

Usage

bm_factor(values, factor_mapping, indexed = FALSE)

bru_mapper_factor(...)

Arguments

Value

A bm_factor mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_factor(factor(c("a", "b")), "full")
ibm_eval2(m, input = c("b", "a", "a", "b"), state = c(1, 3))

m <- bm_factor(factor(c("a", "b")), "contrast")
ibm_eval2(m, input = factor(c("b", "a", "a", "b")), state = 2)

Description

Create mapper for an fm_mesh_1d object

Usage

## S3 method for class 'fm_mesh_1d'
bru_mapper(mesh, indexed = TRUE, ...)

Arguments

Value

A bm_fm_mesh_1d or bm_fmesher object. The the general bm_fmesher() mapper handles all indexed fmesher objects.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bru_mapper(fmesher::fm_mesh_1d(c(1:3, 5, 7)))
ibm_values(m)
ibm_eval(m, 1:7, 1:5)

m <- bru_mapper(fmesher::fm_mesh_1d(c(1:3, 5, 7)), indexed = FALSE)
ibm_values(m)
ibm_eval(m, 1:7, 1:5)

m <- bru_mapper(
  fmesher::fm_mesh_1d(c(1:3, 5, 7), degree = 2, boundary = "free"),
  indexed = FALSE
)
ibm_values(m)
ibm_eval(m, 1:7, 1:6)

Description

Creates a mapper for general fmesher function space objects.

Usage

bm_fmesher(mesh)

bru_mapper_fmesher(...)

## S3 method for class 'fm_mesh_2d'
bru_mapper(mesh, ...)

Arguments

Details

Handles indexed mapping for all fmesher classes that support fm_dof() and fm_basis() methods. For non-indexed mapping of fm_mesh_1d objects, use bru_mapper(mesh, indexed = FALSE) which invokes the bru_mapper.fm_mesh_1d() method.

Value

A bm_fmesher object.

Functions

• bru_mapper(fm_mesh_2d): Equivalent to calling bm_fmesher(). Note: Prior to version ⁠2.12.0.9021⁠, this returned a bru_mapper_fm_mesh_2d object. Also see the note for bru_mapper.fm_mesh_1d().

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_fmesher(fmesher::fmexample$mesh)
ibm_n(m)
ibm_eval(m, as.matrix(expand.grid(-2:2, -2:2)), seq_len(ibm_n(m)))

Description

Constructs a mapper for cos/sin functions of orders 1 (if intercept is TRUE, otherwise 0) through order. The total number of basis functions is intercept + 2 * order.

Optionally, each order can be given a non-unit scaling, via the scaling vector, of length intercept + order. This can be used to give an effective spectral prior. For example, let

scaling = 1 / (1 + (0:4)^2)
x <- seq(0, 1, length.out = 11)
bmh1 = bm_harmonics(order = 4, interval = c(0, 1))
u1 <- ibm_eval(
  bmh1,
  input = x,
  state = rnorm(9, sd = rep(scaling, c(1, 2, 2, 2, 2)))
)

Then, with

bmh2 = bm_harmonics(order = 4, scaling = scaling)
u2 = ibm_eval(bmh2, input = x, state = rnorm(9))

the stochastic properties of u1 and u2 will be the same, with scaling^2 determining the variance for each frequency contribution.

The period for the first order harmonics is shifted and scaled to match interval.

Usage

bm_harmonics(order = 1, scaling = 1, intercept = TRUE, interval = c(0, 1))

bru_mapper_harmonics(...)

Arguments

Value

A bm_harmonics mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_harmonics(2)
ibm_eval2(m, input = c(0, pi / 4, pi / 2, 3 * pi / 4), 1:5)

Description

Create an indexing mapper

Usage

bm_index(n = 1L)

bru_mapper_index(...)

Arguments

Value

A bm_index mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_index(4)
ibm_eval(m, -2:6, 1:4)

Description

Create a mapper for linear effects

Usage

bm_linear()

bru_mapper_linear()

Value

A bm_linear mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_linear()
ibm_eval(m, input = 1:4, state = 2)

Description

bru_mapper lists can be combined into bm_list lists.

Usage

as_bm_list(x)

## S3 method for class 'list'
as_bm_list(x)

## S3 method for class 'bm_list'
as_bm_list(x)

## S3 method for class 'bru_comp_list'
as_bm_list(x)

## S3 method for class 'bru_mapper'
c(...)

## S3 method for class 'bm_list'
c(...)

## S3 method for class 'bm_list'
x[i]

Arguments

Value

A bm_list object

Methods (by generic)

• c(bm_list): The ... arguments should be bm_list objects.

• [: Extract sub-list

Functions

• c(bru_mapper): The ... arguments should be bru_mapper objects.

Examples

m <- c(A = bm_const(), B = bm_scale())
str(m)
str(m[2])

Description

Constructs a mapper that averages elements of plogis(state), with optional non-negative weighting, and then takes the qlogis(). Relies on the input handling methods for bm_aggregate. To avoid numerical issues, it uses plogis(x, log.p = TRUE), plogis(-x, log.p = TRUE), and the equivalent of two applications of bm_logsumexp() to evaluate $\log(p_k)-\log(1-p_k)$, where

$p_k=\sum_{i\in I_k} w_i / (1+e^{-\eta_i}) / \sum_{i\in I_k} w_i$

Usage

bm_logitaverage(n_block = NULL)

Arguments

Value

A bm_logitaverage/bm_aggregate mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_logitaverage()
ibm_eval2(m, list(block = c(1, 2, 1, 2), weights = 1:4), 11:14)
ibm_eval2(m, list(block = c(1, 2, 1, 2), weights = 1:4, n_block = 3), 11:14)

Description

Constructs a mapper that aggregates elements of exp(state), with optional non-negative weighting, and then takes the log(), so it can be used e.g. for $v_k=\log[\sum_{i\in I_k} w_i \exp(u_i)]$ and $v_k=\log[\sum_{i\in I_k} w_i \exp(u_i) / \sum_{i\in I_k} w_i]$ calculations. Relies on the input handling methods for bm_aggregate, but also allows the weights to be supplied on a logarithmic scale as log_weights. To avoid numerical overflow, it uses the common method of internally shifting the state blockwise; $v_k=s_k+\log[\sum_{i\in I_k} \exp(u_i + \log(w_i)- s_k)]$, where $s_k=\max_{i\in I_k} u_i + \log(w_i)$ is the shift for block $k$.

Usage

bm_logsumexp(rescale = FALSE, n_block = NULL)

bru_mapper_logsumexp(...)

Arguments

Value

A bm_logsumexp/bm_aggregate mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_logsumexp()
ibm_eval2(m, list(block = c(1, 2, 1, 2), weights = 1:4), 11:14)
ibm_eval2(m, list(block = c(1, 2, 1, 2), weights = 1:4, n_block = 3), 11:14)

Description

Constructs a mapper that transforms the marginal distribution state from $\textrm{N}(0,1)$ to the distribution of a given (continuous) quantile function. The ... arguments are used as parameter arguments to qfun, pfun, dfun, and dqfun.

Usage

bm_marginal(qfun, pfun = NULL, dfun = NULL, dqfun = NULL, ..., inverse = FALSE)

bru_mapper_marginal(...)

Arguments

Value

A bm_marginal mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_marginal(qexp, pexp, rate = 1 / 8)
(val <- ibm_eval(m, state = -5:5))
ibm_eval(m, state = val, reverse = TRUE)
m <- bm_marginal(qexp, pexp, dexp, rate = 1 / 8)
ibm_eval2(m, state = -3:3)

Description

Create a matrix mapper, for a given number of columns

Usage

bm_matrix(labels)

bru_mapper_matrix(...)

Arguments

Value

A bm_matrix mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_matrix(labels = c("a", "b"))
ibm_values(m)
ibm_eval2(m, input = matrix(1:6, 3, 2), state = 2:3)

m <- bm_matrix(labels = 2L)
ibm_values(m)
ibm_eval2(m, input = matrix(1:6, 3, 2), state = 2:3)

Description

Constructs a row-wise Kronecker product mapping of linear/affine mappers. Any offset in sub-mappers is added into a combined offset. Only linear/affine sub-mappers are allowed.

Usage

bm_multi(mappers, simplify = FALSE)

bru_mapper_multi(...)

## S3 method for class 'bm_multi'
x[i, drop = TRUE]

## S3 method for class 'bru_mapper_multi'
x[i, drop = TRUE]

Arguments

Value

A bm_multi mapper object.

• [-indexing a bm_multi extracts a subset bm_multi object (for drop FALSE) or an individual sub-mapper (for drop TRUE, and i identifies a single element)

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

(m <- bm_multi(list(a = bm_index(2), b = bm_index(3))))
ibm_eval2(m, list(a = c(1, 2, 1), b = c(1, 3, 2)), 1:6)

Description

Create a pipe mapper, where mappers is a list of mappers, and the evaluated output of each mapper is handed as the state to the next mapper. The input format for the ibm_eval and ibm_jacobian methods is a list of inputs, one for each mapper.

Usage

bm_pipe(mappers)

bru_mapper_pipe(...)

Arguments

Value

A bm_pipe mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_pipe(list(
  scale = bm_scale(),
  shift = bm_shift()
))
ibm_eval2(m, input = list(scale = 2, shift = 1:4), state = 1:4)

Description

Creates a mapper for handling basis conversions. Functionally equivalent to bm_pipe(list(bm_matrix(ncol(B)), mapper)), but with an internally stored matrix input B for efficiency, and allowing the mapper input format to be identical to that of the original mapper.

Usage

bm_reparam(mapper, B)

Arguments

Value

A bm_reparam mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

# 2->2 reparameterisation; (u1,u2) -> (u1, u1 + u2)
(m <- bm_reparam(bm_index(2), B = matrix(c(1, 1, 0, 1), 2, 2)))

# 2->3 reparameterisation; (u1,u2) -> (u1, u2, u1+u2)
# This is an example of a low-rank representation of a higher-dimensional
# state vector.
(m <- bm_reparam(bm_index(3), B = cbind(c(1, 0, 1), c(0, 1, 1))))

Description

Defines a repeated-space mapper that sums the contributions for each copy. The ibm_n() method returns ibm_n(mapper) * n_rep, and ibm_values() returns seq_len(ibm_n(mapper)).

Usage

bm_repeat(mapper, n_rep, interleaved = FALSE)

bru_mapper_repeat(...)

Arguments

Value

A bm_repeat or bm_sum object, or the original input mapper.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

(m0 <- bm_index(3))
(m <- bm_repeat(m0, 5))
ibm_n(m)
ibm_values(m)
ibm_jacobian(m, 1:3)
ibm_eval(m, 1:3, seq_len(ibm_n(m)))

# Interleaving and grouping
(m <- bm_repeat(m0, c(2, 1, 2), c(TRUE, FALSE, FALSE)))
ibm_n(m)
ibm_values(m)
ibm_jacobian(m, 1:3)
ibm_eval(m, 1:3, seq_len(ibm_n(m)))

Description

Create a standalone scaling mapper that can be used as part of a bm_pipe. If mapper is non-null, the bm_scale() constructor returns bm_pipe(list(mapper = mapper, scale = bm_scale()))

Usage

bm_scale(mapper = NULL)

bru_mapper_scale(...)

Arguments

Value

A bm_scale mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_scale()
ibm_eval2(m, c(1, 2, 1, 2), 1:4)

Description

Create a standalone shift mapper that can be used as part of a bm_pipe. If mapper is non-null, the bm_shift() constructor returns bm_pipe(list(mapper = mapper, shift = bm_shift()))

Usage

bm_shift(mapper = NULL)

bru_mapper_shift(...)

Arguments

Value

A bm_shift mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_shift()
ibm_eval2(m, c(1, 2, 1, 2), 1:4)

Description

Defines a mapper that adds the effects of each submapper. The ibm_n() method returns the sum of ibm_n(mappers[[k]]), and ibm_values() returns seq_len(ibm_n(mapper)).

Usage

bm_sum(mappers, single_input = FALSE)

bru_mapper_sum(...)

## S3 method for class 'bm_sum'
x[i, drop = TRUE]

## S3 method for class 'bru_mapper_sum'
x[i, drop = TRUE]

Arguments

Value

A bm_sum object.

• [-indexing a bm_sum extracts a subset bm_sum object (for drop FALSE) or an individual sub-mapper (for drop TRUE, and i identifies a single element)

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_taylor(), bru_get_mapper(), bru_mapper()

Examples

(m <- bm_sum(list(a = bm_index(3), b = bm_index(2))))
ibm_n(m)
ibm_values(m)
ibm_jacobian(m, list(a = 1:3, b = c(1, 1, 2)))
ibm_eval(
  m,
  list(a = 1:3, b = c(1, 1, 2)),
  seq_len(ibm_n(m))
)

Description

Provides a pre-computed affine mapping, internally used to represent and evaluate linearisation information. The state0 information indicates for which state the offset was evaluated; The affine mapper output is defined as effect(state) = offset + jacobian %*% (state - state0)

Usage

bm_taylor(offset = NULL, jacobian = NULL, state0 = NULL, values_mapper = NULL)

bru_mapper_taylor(...)

Arguments

Value

A bm_taylor mapper object.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bru_get_mapper(), bru_mapper()

Examples

m <- bm_taylor(
  offset = rep(2, 3),
  jacobian = matrix(1:6, 3, 2),
  state0 = c(1, 2)
)
ibm_eval2(m, state = 2:3)

Description

This method is a wrapper for INLA::inla and provides multiple enhancements.

• Easy usage of spatial covariates and automatic construction of inla projection matrices for (spatial) SPDE models. This feature is accessible via the components parameter. Practical examples on how to use spatial data by means of the components parameter can also be found by looking at the lgcp() function's documentation.

• Constructing multiple observation models is straightforward. See bru_obs() for more information on how to provide additional models to bru using the ... parameter list.

• Support for non-linear predictors. See example below.

• Log Gaussian Cox process (LGCP) inference is available by using the "cp" family or (even easier) by using the lgcp() function.

Usage

bru(components = ~Intercept(1), ..., options = list(), .envir = parent.frame())

bru_rerun(result, options = list())

## S3 method for class 'bru'
summary(object, verbose = FALSE, ...)

## S3 method for class 'summary_bru'
print(x, ...)

## S3 method for class 'bru'
print(x, ...)

Arguments

Value

bru returns an object of class "bru". A bru object inherits from INLA::inla (see the inla documentation for its properties) and adds additional information stored in the bru_info field.

Methods (by generic)

• summary(bru): Takes a fitted bru object produced by bru() or lgcp() and creates various summaries from it, including the summary output from the corresponding INLA::sumary() method. The ... arguments are passed on to component summary functions, see summary.bru_comp().

• print(bru): Print a summary of a bru object.

Functions

• bru_rerun(): Continue the optimisation from a previously computed estimate. The estimation options list can be given new values to override the original settings.

  To rerun with a subset of the data (e.g. for cross validation or prior sampling), use bru_set_missing() to set all or part of the response data to NA before calling bru_rerun().

Author(s)

Fabian E. Bachl [email protected]

Examples

if (bru_safe_inla()) {
  # Simulate some covariates x and observations y
  input.df <- data.frame(x = cos(1:10))
  input.df <- within(input.df, {
    y <- 5 + 2 * x + rnorm(10, mean = 0, sd = 0.1)
  })

  # Fit a Gaussian likelihood model
  fit <- bru(y ~ x + Intercept(1), family = "gaussian", data = input.df)

  # Obtain summary
  fit$summary.fixed
}


if (bru_safe_inla()) {
  # Alternatively, we can use the bru_obs() function to construct the
  # likelihood:

  lik <- bru_obs(
    family = "gaussian",
    formula = y ~ x + Intercept,
    data = input.df
  )
  fit <- bru(~ x + Intercept(1), lik)
  fit$summary.fixed
}

# An important addition to the INLA methodology is bru's ability to use
# non-linear predictors. Such a predictor can be formulated via bru_obs()'s
# \code{formula} parameter. The z(1) notation is needed to ensure that
# the z component should be interpreted as single latent variable and not
# a covariate:

if (bru_safe_inla()) {
  z <- 2
  input.df <- within(input.df, {
    y <- 5 + exp(z) * x + rnorm(10, mean = 0, sd = 0.1)
  })
  lik <- bru_obs(
    family = "gaussian", data = input.df,
    formula = y ~ exp(z) * x + Intercept
  )
  fit <- bru(~ z(1) + Intercept(1), lik)

  # Check the result (z posterior should be around 2)
  fit$summary.fixed
}

Description

After fitting a model with control.gcpo = list(enable = TRUE), this function reads the raw per-observation GCPO vector from fit$gcpo$gcpo and returns one score per block or observation group.

Two cases are handled automatically:

Block-based (lgcp / "cp" family)

When BRU_block is present in response_data (populated automatically by the "cp" family machinery from the samplers structure), INLA repeats the same GCPO value for every observation in a leave-out block. The mean within each block collapses the repeated values to one score per block.

Groups-based (all other families)

When BRU_block is absent, INLA builds groups internally (via num.level.sets or friends) or from a user-supplied groups list. One score per observation is returned directly from fit$gcpo$gcpo.

Scores are returned on the probability scale, consistent with fit$cpo$cpo. For multi-likelihood models, cumulative row offsets into the stacked INLA response vector are handled automatically.

Usage

bru_block_gcpo(fit, ...)

Arguments

Value

For a single fit, a list with two elements:

blocks

Named list with one element per likelihood, each a vector of block labels (for "cp" models: unique BRU_block values; for other models: observation indices).

gcpo

GCPO scores on the probability scale, consistent with fit$cpo$cpo. A numeric vector for single-likelihood models; a named list of numeric vectors for multi-likelihood models.

For multiple fits, a named list of such objects, one per fit.

See Also

bru(), bru_obs(), bru_obs_control_gcpo(), bru_gcpo_table()

Examples

if (bru_safe_inla()) {
  # Block-based example (lgcp)
  cvpart <- cv_hex(
    gorillas_sf$boundary,
    cellsize = 0.5,
    n_group = 3,
    resolution = c(95, 80)
  )
  cvpart$block_ID <- seq_len(nrow(cvpart))
  cvpart$group <- NULL

  nests <- gorillas_sf$nests
  a <- sf::st_intersects(nests, cvpart)
  nests$.block <- unlist(a)

  fit1 <- lgcp(
    geometry ~ Intercept(1),
    data = nests,
    samplers = cvpart,
    domain = list(geometry = gorillas_sf$mesh),
    control.gcpo = list(enable = TRUE, type.cv = "joint")
  )
  result <- bru_block_gcpo(fit1)
  result$blocks
  result$gcpo
  sum(log(result$gcpo))

  # Multiple models
  pcmatern <- INLA::inla.spde2.pcmatern(
    gorillas_sf$mesh,
    prior.sigma = c(1, 0.01),
    prior.range = c(0.1, 0.01)
  )
  fit2 <- lgcp(
    geometry ~ Intercept(1) + field(geometry, model = pcmatern),
    data = nests,
    samplers = cvpart,
    domain = list(geometry = gorillas_sf$mesh),
    control.gcpo = list(enable = TRUE, type.cv = "joint")
  )
  result <- bru_block_gcpo(list(Model1 = fit1, Model2 = fit2))
  str(result)
}

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 bru_comp methods all rely on the bru_comp.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 bru_comp_list.formula() method, called inside bru().

Usage

bru_comp(...)

bru_component(...)

## S3 method for class 'character'
bru_comp(
  object,
  main = NULL,
  weights = NULL,
  ...,
  model = NULL,
  mapper = NULL,
  main_layer = NULL,
  main_selector = NULL,
  n = NULL,
  values = NULL,
  season.length = NULL,
  nrow = NULL,
  ncol = NULL,
  copy = NULL,
  weights_layer = NULL,
  weights_selector = NULL,
  group = 1L,
  group_mapper = NULL,
  group_layer = NULL,
  group_selector = NULL,
  ngroup = NULL,
  control.group = NULL,
  replicate = 1L,
  replicate_mapper = NULL,
  replicate_layer = NULL,
  replicate_selector = NULL,
  nrep = NULL,
  marginal = NULL,
  A.msk = deprecated(),
  .envir = parent.frame(),
  envir_extra = NULL
)

Arguments

Details

As shorthand, bru() will understand basic additive formulae describing fixed effect models. For instance, the components specification y ~ x will define 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 $\eta$ would be written as

$\eta = \beta x + c,$

where:

$c$

is the intercept

$x$

is a covariate

$\beta$

is a latent variable associated with $x$ and

$\psi = \beta x$

is called the effect of $x$

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

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

The main, weights, group, replicate, and ⁠*_layer⁠ arguments support tidy evaluation expressions, with .data and .env pronouns.

Functions

• bru_component(): Backwards compatibility alias for bru_comp()

Naming random effects

In INLA, the f() notation is used to define more complex models, but a simple linear effect model can also 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 $\eta = \beta * x + c$ but the result of fitting the model would state x as the random effect's name. bru allows rewriting this formula in order to explicitly state the name of the random effect and the name of the associated covariate. This is achieved 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 $\psi$ 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 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 e ^{β + c}.

On the other hand, predict may be used to only look at a transformation of the latent variable $\beta_\psi$

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

which corresponds to the mathematical expression e ^β.

Author(s)

Fabian E. Bachl [email protected] and Finn Lindgren [email protected]

See Also

bru_input(), summary.bru_comp()

Other component constructors: bru_comp_list()

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 <- bru_comp_list(~ myLinearEffectOfX(main = x, model = "linear"))
summary(cmp)
# Equivalent shortcuts:
cmp <- bru_comp_list(~ myLinearEffectOfX(x, model = "linear"))
cmp <- bru_comp_list(~ myLinearEffectOfX(x))
# Individual component
cmp <- bru_comp("myLinearEffectOfX", main = x, model = "linear")
summary(cmp)

if (bru_safe_inla()) {
  # 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":

  cmp <- bru_comp("myEffectOfX", main = x, model = "linear")
  summary(cmp)

  # A more complicated component:
  cmp <- bru_comp("myEffectOfX",
    main = x,
    model = INLA::inla.spde2.matern(fmesher::fm_mesh_1d(1:10))
  )

  # Compound fixed effect component, where x and z are in the input data.
  # The formula will be passed on to MatrixModels::model.Matrix:
  cmp <- bru_comp("eff", ~ -1 + x:z, model = "fixed")
  summary(cmp)
}

Description

Get or set data in the component's env_extra and env environments. If name is NULL, the entire environment is returned.

Usage

bru_comp_env_extra(x, name = NULL)

bru_comp_env_extra(x, name) <- value

bru_comp_env(x, name = NULL)

bru_comp_env(x, name) <- value

Arguments

Value

For the getter, either the entire environment or the value of name in the environment. For the setters, the modified bru_comp object.

Functions

• bru_comp_env_extra(x, name) <- value: Set data in the component's env_extra environment

• bru_comp_env(): Get the component's env environment, or an element from that environment. Note that in most cases this environment is the global R environment.

• bru_comp_env(x, name) <- value: Set data in the component's env environment. Note that in most cases this environment is the global R environment, so modifying it is normally not recommended.

See Also

bru_comp

Examples

if (bru_safe_inla()) {
  cmp <- bru_comp("x", x)
  as.list(bru_comp_env_extra(cmp))

  cmp <- bru_comp("x", x, model = "fixed")
  as.list(bru_comp_env_extra(cmp))

  bru_comp_env(cmp)
}

Description

In predictor expressions, name_eval(...) can be used to evaluate the effect of a component called "name".

Usage

bru_comp_eval(
  main,
  group = NULL,
  replicate = NULL,
  weights = NULL,
  .state = NULL
)

Arguments

list(mapper = list(
       main = main,
       group = group,
       replicate = replicate),
     scale = weights)

Value

A vector of values for a component

Examples

if (bru_safe_inla() &&
  require("sf", quietly = TRUE) &&
  requireNamespace("sn", quietly = TRUE)) {
  mesh <- fmesher::fm_mesh_2d_inla(
    cbind(0, 0),
    offset = 2,
    max.edge = 2.5
  )
  spde <- INLA::inla.spde2.pcmatern(
    mesh,
    prior.range = c(1, NA),
    prior.sigma = c(0.2, NA)
  )
  set.seed(12345L)
  data <- sf::st_as_sf(
    data.frame(
      x = runif(50),
      y = runif(50),
      z = rnorm(50)
    ),
    coords = c("x", "y")
  )
  fit <- bru(
    z ~ -1 + field(geometry, model = spde),
    family = "gaussian", data = data,
    options = list(control.inla = list(int.strategy = "eb"))
  )
  pred <- generate(
    fit,
    newdata = data.frame(A = 0.5, B = 0.5),
    formula = ~ field_eval(cbind(A, B)),
    n.samples = 1L
  )
}

Description

Constructor methods for inlabru component lists. Syntax details are given in bru_comp().

Usage

bru_comp_list(object, ..., .envir = parent.frame())

## S3 method for class 'formula'
bru_comp_list(object, ..., lhoods = NULL, .envir = parent.frame())

## S3 method for class 'list'
bru_comp_list(
  object,
  ...,
  lhoods = NULL,
  .envir = parent.frame(),
  inputs = NULL
)

## S3 method for class 'bru_comp'
bru_comp_list(object, ..., .envir = parent.frame())

## S3 method for class 'bru_comp_list'
bru_comp_list(object, ..., .envir = parent.frame())

## S3 method for class 'bru_comp_list'
c(...)

## S3 method for class 'bru_comp'
c(...)

## S3 method for class 'bru_comp_list'
x[i]

Arguments

Methods (by class)

• bru_comp_list(formula): Convert a component formula into a bru_comp_list object

• bru_comp_list(list): Combine a list of components, component lists, and/or component formulas into a single bru_comp_list object

• bru_comp_list(bru_comp): Place a single bru_comp object into a bru_comp_list object.

• bru_comp_list(bru_comp_list): Make sure a bru_comp_list object is fully configured.

Methods (by generic)

• c(bru_comp_list): The ... arguments should be bru_comp_list objects. The environment from the first argument will be applied to the resulting bru_comp_list.

Functions

• c(bru_comp): The ... arguments should be component objects from bru_comp(). The environment from the first argument will be applied to the resulting bru_comp_list.

Author(s)

Fabian E. Bachl [email protected] and Finn Lindgren [email protected]

See Also

Other component constructors: bru_comp()

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

eff <- bru_comp_list(~ myLinearEffectOfX(main = x, model = "linear"))
summary(eff[[1]])
# Equivalent shortcuts:
eff <- bru_comp_list(~ myLinearEffectOfX(x, model = "linear"))
eff <- bru_comp_list(~ myLinearEffectOfX(x))
# Individual component
eff <- bru_comp("myLinearEffectOfX", main = x, model = "linear")

Description

Draws four panels of convergence diagnostics for an iterated INLA method estimation

Usage

bru_convergence_plot(x, from = 1, to = NULL, type = NULL)

Arguments

Details

Requires the "dplyr", "ggplot2", and "patchwork" packages to be installed.

Value

A ggplot object with four panels of convergence diagnostics:

• Tracks: Mode and linearisation values for each effect

• Mode - Lin: Difference between mode and linearisation values for each effect

• ⁠|Change| / sd⁠: Absolute change in mode and linearisation values divided by the standard deviation for each effect

• Change & sd: Absolute change in mode and linearisation values and standard deviation for each effect

For multidimensional components, only the overall average, maximum, and minimum values are shown.

See Also

bru()

Examples

## Not run: 
fit <- bru(...)
bru_convergence_plot(fit)

## End(Not run)

Description

Computes nearest-available-value imputation for missing values in space

Usage

bru_fill_missing(
  data,
  where,
  values,
  layer = NULL,
  selector = NULL,
  batch_size = deprecated()
)

Arguments

Value

An infilled vector of values

Examples

## Not run: 
if (require("sf", quietly = TRUE)) {
  points <-
    sf::st_as_sf(
      data.frame(
        x = 1:3,
        y = 4:6,
        val = c(NA, NA, NA)
      ),
      coords = c("x", "y")
    )
  input_coord <- expand.grid(x = 0:7, y = 0:7)
  input <-
    sf::st_as_sf(
      cbind(input_coord, val = as.vector(input_coord$y)),
      coords = c("x", "y")
    )
  points$val <- bru_fill_missing(input, points, points$val)
  print(points)

  # To fill in missing values in a grid:
  print(input$val[c(3, 30)])
  input$val[c(3, 30)] <- NA # Introduce missing values
  input$val <- bru_fill_missing(input, input, input$val)
  print(input$val[c(3, 30)])
}

## End(Not run)

Description

Calls bru_block_gcpo() on each fit and combines the results into a data.frame with one row per block and one column per model, making it straightforward to compare GCPO scores across models block by block.

Usage

bru_gcpo_table(fits = NULL, ...)

Arguments

Value

For a single-likelihood model, a data.frame with columns:

block

Block labels from response_data$BRU_block (for "cp" models) or observation indices (for other models).

one column per model

GCPO scores on the probability scale, named after the elements of fits or ⁠\dots⁠.

For multi-likelihood models, a named list of such data.frames, one per likelihood.

See Also

bru_block_gcpo()

Examples

if (bru_safe_inla()) {
  cvpart <- cv_hex(
    gorillas_sf$boundary,
    cellsize = 0.5,
    n_group = 3,
    resolution = c(95, 80)
  )
  cvpart$block_ID <- seq_len(nrow(cvpart))
  cvpart$group <- NULL

  nests <- gorillas_sf$nests
  a <- sf::st_intersects(nests, cvpart)
  nests$.block <- unlist(a)

  fit1 <- lgcp(
    geometry ~ Intercept(1),
    data = nests,
    samplers = cvpart,
    domain = list(geometry = gorillas_sf$mesh),
    control.gcpo = list(enable = TRUE, type.cv = "joint")
  )
  pcmatern <- INLA::inla.spde2.pcmatern(
    gorillas_sf$mesh,
    prior.sigma = c(1, 0.01),
    prior.range = c(0.1, 0.01)
  )
  fit2 <- lgcp(
    geometry ~ Intercept(1) + field(geometry, model = pcmatern),
    data = nests,
    samplers = cvpart,
    domain = list(geometry = gorillas_sf$mesh),
    control.gcpo = list(enable = TRUE, type.cv = "joint")
  )
  gcpo_df <- bru_gcpo_table(Model1 = fit1, Model2 = fit2)
  names(gcpo_df)
  colSums(log(gcpo_df[, -1]))
}

Description

The component definitions will automatically attempt to extract mapper information from any model object by calling the generic bru_get_mapper. Any class method implementation should return a bru_mapper object suitable for the given latent model.

Usage

bru_get_mapper(model, ...)

## S3 method for class 'inla.spde'
bru_get_mapper(model, ...)

## S3 method for class 'inla.rgeneric'
bru_get_mapper(model, ...)

## S3 method for class 'inla.cgeneric'
bru_get_mapper(model, ...)

bru_get_mapper_safely(model, ...)

## S3 method for class 'inla_model_reparam'
bru_get_mapper(model, ...)

Arguments

Details

Before implementing your own bru_get_mapper method, check if there is already a general method available that handles your model class, such as bru_get_mapper.inla.spde(), bru_get_mapper.inla.rgeneric(), and bru_get_mapper.inla.cgeneric().

Value

A bru_mapper object defined by the model component

Methods (by class)

• bru_get_mapper(inla.spde): Extract an indexed mapper for the model$mesh object contained in the model object, which is assumed to be of a class supporting relevant fmesher methods.

• bru_get_mapper(inla.rgeneric): Returns the mapper given by a pre-computed mapper, or an index mapper mapping the size of the model graph.

  The easiest method to define a mapper for an inla.rgeneric model is to store the mapper in the object. Alternatively, define your model using a subclass and define a ⁠bru_get_mapper.<subclass>⁠ method that should return the corresponding bru_mapper object.

  The order of precedence for the mapper construction when calling bru_get_mapper(model) has the following precedence:

  1. ⁠bru_get_mapper.<subclass>⁠, if model has a subclass, otherwise

  2. model[["mapper"]] if that is NULL, and otherwise

  3. bm_index() using the size of the graph returned by model[["f"]][["n"]]

• bru_get_mapper(inla.cgeneric): Works the same as the method of inla.rgeneric

• bru_get_mapper(inla_model_reparam): Reparameterised inla model mapper, see inla.spde2.pcmatern_B()

Functions

• bru_get_mapper_safely(): Tries to call the bru_get_mapper, and returns NULL if it fails (e.g. due to no available class method). If the call succeeds and returns non-NULL, it checks that the object inherits from the bru_mapper class, and gives an error if it does not.

See Also

bru_mapper for mapper constructor methods, and the individual mappers for specific implementation details.

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fm_mesh_1d, bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logitaverage(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_reparam(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_mapper()

Examples

if (bru_safe_inla()) {
  library(INLA)
  mesh <- fmesher::fm_rcdt_2d_inla(globe = 2)
  spde <- inla.spde2.pcmatern(mesh,
    prior.range = c(1, 0.5),
    prior.sigma = c(1, 0.5)
  )
  mapper <- bru_get_mapper(spde)
  ibm_n(mapper)
}

Description

Extract the index vector for a bru_obs() predictor, or the whole or a subset of a full bru() predictor.

Usage

bru_index(object, ...)

## S3 method for class 'bru_obs'
bru_index(object, what = NULL, ...)

## S3 method for class 'bru_obs_list'
bru_index(object, tag = NULL, what = NULL, ...)

## S3 method for class 'bru'
bru_index(object, tag = NULL, what = NULL, ...)

## S3 method for class 'bru_info'
bru_index(object, tag = NULL, what = NULL, ...)

## S3 method for class 'bru_comp'
bru_index(object, inla_f, ...)

## S3 method for class 'bru_comp_list'
bru_index(object, inla_f, ...)

## S3 method for class 'bru_model'
bru_index(object, used, ...)

index_eval(...)

Arguments

Value

• bru_index(bru_obs): An integer vector.

• bru_index(bru_obs_list): An integer vector.

• bru_index(bru): An integer vector.

• bru_index(bru_info): An integer vector.

• bru_index(bru_comp): A list of indices into the latent variables compatible with the component mapper.

• bru_index(bru_comp_list): A list of list of indices into the latent variables compatible with each component mapper.

• bru_index(bru_model): A named list of idx_full and idx_inla, named list of indices, and inla_subset, and inla_subset, a named list of logical subset specifications for extracting the INLA::f() compatible index subsets.

Methods (by class)

• bru_index(bru_obs): Extract the index vector for the predictor vector for a bru_obs() sub-model. The indices are relative to the sub-model, and need to be appropriately offset to be used in the full model predictor.

• bru_index(bru_obs_list): Extract the index vector for "APredictor" for one or more specified observation bru_obs() sub-models. Accepts any combination of tag and what.

• bru_index(bru): Extract the index vector for "APredictor" for one or more specified observation bru_obs() sub-models. Accepts any combination of tag and what.

• bru_index(bru_info): Extract the index vector for "APredictor" for one or more specified observation bru_obs() sub-models. Accepts any combination of tag and what.

• bru_index(bru_model): Compute all index values for a bru_model() object. Computes the index value matrices for included components according to the used argument.

Functions

• index_eval(): since "2.12.0.9023". Use bru_index() instead.

Author(s)

Fabian E. Bachl [email protected], Finn Lindgren [email protected]

Examples

fit <- bru(
  ~ 0 + x,
  bru_obs(
    y ~ .,
    data = data.frame(x = 1:3, y = 1:3 + rnorm(3)),
    tag = "A"
  ),
  bru_obs(
    y ~ .,
    data = data.frame(x = 1:4, y = c(NA, NA, 3:4) + rnorm(4)),
    tag = "B"
  ),
  options = list(bru_run = FALSE) # We only need the model structure
)
bru_index(fit)
bru_index(fit, "A")
bru_index(fit, "B")
bru_index(fit, c("B", "A"))
bru_index(fit, what = "missing")

Description

The bru_info class is used to store metadata about bru models.

Usage

bru_info(...)

## S3 method for class 'character'
bru_info(method, ..., inlabru_version = NULL, INLA_version = NULL)

## S3 method for class 'bru'
bru_info(object, ...)

as_bru_info(object, ...)

## S3 method for class 'bru_info'
as_bru_info(object, ...)

## S3 method for class 'bru'
as_bru_info(object, ...)

## S3 method for class 'bru_info'
summary(object, verbose = TRUE, ...)

## S3 method for class 'summary_bru_info'
print(x, ...)

## S3 method for class 'bru_info'
print(x, ...)

Arguments

Methods (by class)

• bru_info(character): Create a bru_info object

• bru_info(bru): Extract the bru_info object from an estimated bru() result object. The default print method shows information about model components and observation models.

Methods (by generic)

• as_bru_info(bru_info): Extract a bru_info object.

Functions

• as_bru_info(): Extract the bru_info object from an estimated bru() result object. The default print method shows information about model components and observation models.

• as_bru_info(bru): Extract the bru_info object from an estimated bru() result object.

Description

Store and evaluate component inputs, including support for non-standard-evaluation with rlang, automatic transfer to function calls, eval_spatial(), and MatrixModels::model.Matrix().

These functions are normally only called internally, but users may find it useful to call them directly to experiment, and to make advanced model definitions using ibm_input_set/ibm_input_new().

Usage

new_bru_input(input, label = NULL, layer = NULL, selector = NULL, ...)

bru_input(...)

## S3 method for class 'bru_input'
bru_input(
  x,
  data = NULL,
  mask = NULL,
  null.on.fail = FALSE,
  .envir = parent.frame(),
  ...
)

## S3 method for class 'bru_comp'
bru_input(x, ..., label = x$label)

## S3 method for class 'bru_comp_list'
bru_input(x, ...)

## S3 method for class 'bru_model'
bru_input(x, lhoods, ...)

## S3 method for class 'bru_obs'
bru_input(x, components, ...)

## S3 method for class 'bru_obs_list'
bru_input(x, components, ...)

## S3 method for class 'bru_mapper'
bru_input(x, ..., label = "<unknown>")

## S3 method for class 'bm_pipe'
bru_input(x, ..., label = "<unknown>")

## S3 method for class 'bm_multi'
bru_input(x, ..., label = "<unknown>")

## S3 method for class 'bm_collect'
bru_input(x, ..., label = "<unknown>")

## S3 method for class 'bm_repeat'
bru_input(x, ..., label = "<unknown>")

## S3 method for class 'bm_sum'
bru_input(x, ..., label = "<unknown>")

Arguments

Value

• bru_input(bru_comp): A list of mapper input values, formatted for the full component mapper (of type bm_pipe)

• bru_input(bru_comp_list): A list of mapper input values, with one entry for each component.

• bru_input(bru_model): A list of mapper input values, with one entry for each observation model, each containing a list of inputs for the components used by the corresponding observation model.

• bru_input(bru_obs): A list of mapper input values, for each of the components used by the corresponding observation model.

• bru_input(bru_obs_list): A list of mapper input values, with one entry for each observation model, each containing a list of inputs for the components used by the corresponding observation model.

Methods (by class)

• bru_input(bru_input): Attempts to evaluate a component input (e.g. main, group, replicate, or weight), and process the results:

  1. If rlang::eval_tidy() failed, return NULL or map everything to 1 (see the null.on.fail argument). This should normally not happen, unless the component use logic is incorrect, (via used) leading to missing columns for a certain likelihood in a multi-bru_obs() model.

  2. If we obtain a function, apply the function to the data object

  3. If we obtain an object supported by eval_spatial(), extract the values of that data frame at the point locations

  4. If we obtain a formula, call ModelMatrix::model.Matrix()

  5. Else we obtain a vector and return as-is. This happens when input references a column of the data points, or some other complete expression

• bru_input(bru_model): Computes the component inputs for included components for each observation model.

• bru_input(bru_mapper): Evaluate the input associated with a bru_mapper.

• bru_input(bm_pipe): Evaluate the inputs for each sub-mapper in a bm_pipe object.

• bru_input(bm_multi): Evaluate the inputs for each sub-mapper in a bm_multi object.

• bru_input(bm_collect): Evaluate the inputs for each sub-mapper in a bm_collect object.

• bru_input(bm_repeat): Evaluate the inputs for the sub-mapper in a bm_repeat object.

• bru_input(bm_sum): Evaluate the inputs for each sub-mapper in a bm_sum object.

Functions

• new_bru_input(): Create a bru_input object.

• bru_input(): Evaluate inputs

Simple covariates and the input parameters

It is not unusual for a random effect act on a transformation of a covariate. In other frameworks this would mean that the transformed covariate would have to be calculated in advance and added to the data frame that is usually provided via the data parameter. inlabru provides the option to do this transformation automatically. For instance, one might be interested in the effect of a covariate $x^2$. In inla and other frameworks this would require to add a column xsquared to the input data frame and use the formula

• formula = y ~ f(xsquared, model = "linear"),

In inlabru this can be achieved in several ways of using the main parameter (map in version 2.1.13 and earlier), which does not need to be named.

• components = y ~ psi(x^2, model = "linear")

• components = y ~ psi(main = x^2, model = "linear")

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

• components = y ~ psi(myOtherSquareFun, model = "linear"),

In the first example inlabru will interpret the map parameter as an expression to be evaluated within the data provided. Since $x$ is a known covariate it will know how to calculate it. The second example is an expression as well but it uses a function called mySquareFun. This function is defined by user but has to be accessible within the work space when setting up the components. The third example provides the function myOtherSquareFun. In this case, inlabru will call the function as myOtherSquareFun(.data.), where .data. is the data provided via the bru_obs() data parameter. The function needs to know what parts of the data to use to construct the needed output. For example,

myOtherSquareFun <- function(data) {
  data[ ,"x"]^2
}

Interactions can be handled by a formula input and model = "fixed": components = y ~ 0 + name(~ 1 + x:z, model = "fixed")

Spatial Covariates

When fitting spatial models it is common to work with covariates that depend on space, e.g. sea surface temperature or elevation. Although it is straightforward to add this data to the input data frame or write a covariate function like in the previous section there is an even more convenient way in inlabru. Spatial covariates are often stored as SpatialPixelsDataFrame, SpatialPixelsDataFrame or RasterLayer objects. These can be provided directly via the input expressions if they are supported by eval_spatial(), and the bru_obs() data is an sf or SpatialPointsDataFrame object. inlabru will then automatically evaluate and/or interpolate the covariate at your data locations when using code like

components = y ~ psi(mySpatialPixels, model = "linear")

For more precise control, use the the layer and selector arguments (see bru_comp()), or call eval_spatial() directly, e.g.:

components = y ~ psi(eval_spatial(mySpatialPixels, where = .data.),
                     model = "linear")

Coordinates

A common spatial modelling component when using inla are SPDE models. An important feature of inlabru is that it will automatically calculate the so called A-matrix (a component model matrix) which maps SPDE values at the mesh vertices to values at the data locations. For this purpose, the input can be set to coordinates, which is the sp package function that extracts point coordinates from the SpatialPointsDataFrame that was provided as input to bru_obs(). The code for this would look as follows:

components = y ~ field(coordinates, model = inla.spde2.matern(...))

Since coordinates is a function from the sp package, this results in evaluation of sp::coordinates(.data.), which loses any CRS information from the data object.

For sf data with a geometry column (by default named geometry), use

components = y ~ field(geometry, model = inla.spde2.matern(...))

Since the CRS information is part of the geometry column of the sf object, this retains CRS information, so this is more robust, and allows the model to be built on a different CRS than the observation data.

Author(s)

Fabian E. Bachl [email protected], Finn Lindgren [email protected]

See Also

bru_input_text()

summary.bru_input(), bru_comp()

ibm_input

Examples

(inp <- new_bru_input(x, "LABEL"))
bru_input(inp, data.frame(x = 1:3))

Description

Checks if a predictor expression is additive or not

Usage

bru_is_additive(x, ...)

## S3 method for class 'character'
bru_is_additive(x, ..., verbose = FALSE)

## S3 method for class 'expression'
bru_is_additive(x, ..., verbose = FALSE)

## S3 method for class 'formula'
bru_is_additive(x, ..., verbose = FALSE)

## S3 method for class 'bru_pred_expr'
bru_is_additive(x, ...)

## S3 method for class 'bru_obs'
bru_is_additive(x, ...)

## S3 method for class 'bru_obs_list'
bru_is_additive(x, ...)

Arguments

Value

TRUE if the expression is detected to be additive, FALSE otherwise.

Examples

bru_is_additive(~ x + y)
bru_is_additive(~ x * y)

Description

Checks if a predictor expression is linear (or affine)

Usage

bru_is_linear(x, ...)

## S3 method for class 'bru'
bru_is_linear(x, ...)

## S3 method for class 'bru_info'
bru_is_linear(x, ...)

## S3 method for class 'bru_model'
bru_is_linear(x, ...)

## S3 method for class 'bru_obs'
bru_is_linear(x, ...)

## S3 method for class 'bru_obs_list'
bru_is_linear(x, ...)

## S3 method for class 'bru_pred_expr'
bru_is_linear(x, ...)

## S3 method for class 'bru_comp_list'
bru_is_linear(x, ...)

## S3 method for class 'bru_comp'
bru_is_linear(x, ...)

## S3 method for class 'bru_mapper'
bru_is_linear(x, ...)

Arguments

Value

TRUE if the expression is detected to be linear, FALSE otherwise.

Examples

bru_is_linear(new_bru_pred_expr(~ x + y))
bru_is_linear(new_bru_pred_expr(~ x * y))
bru_is_linear(bm_scale())
bru_is_linear(bm_logsumexp())

Description

Checks if a predictor expression may be evaluated rowwise

Usage

bru_is_rowwise(x, ...)

## S3 method for class 'bru_pred_expr'
bru_is_rowwise(x, ...)

## S3 method for class 'bru_obs'
bru_is_rowwise(x, ...)

## S3 method for class 'bru_obs_list'
bru_is_rowwise(x, ...)

## S3 method for class 'bru_comp_list'
bru_is_rowwise(x, ...)

## S3 method for class 'bru_comp'
bru_is_rowwise(x, ...)

## S3 method for class 'bru_mapper'
bru_is_rowwise(x, ...)

Arguments

Value

TRUE if the expression is believed to be rowwise, FALSE otherwise.

Examples

bru_is_rowwise(new_bru_pred_expr(~ x + y))

Description

Access method for bru_log objects. Note: Up to version ⁠2.8.0⁠, bru_log() was a deprecated alias for bru_log_message(). When running on ⁠2.8.0⁠ or earlier, use bru_log_get() to access the global log, and cat(fit$bru_iinla$log, sep = "\n") to print a stored estimation object log. After version ⁠2.8.0⁠, use bru_log() to access the global log, and bru_log(fit) to access a stored estimation log.

Usage

bru_log(x = NULL, verbosity = NULL)

## S3 method for class 'character'
bru_log(x, verbosity = NULL)

## S3 method for class 'bru_log'
bru_log(x, verbosity = NULL)

## S3 method for class 'iinla'
bru_log(x, verbosity = NULL)

## S3 method for class 'bru'
bru_log(x, verbosity = NULL)

## S3 method for class 'bru_log'
format(x, ..., timestamp = TRUE, verbosity = FALSE)

## S3 method for class 'bru_log'
print(x, ..., timestamp = TRUE, verbosity = FALSE)

## S3 method for class 'bru_log'
as.character(x, ...)

## S3 method for class 'bru_log'
x[i]

## S3 method for class 'bru_log'
c(...)

## S3 method for class 'bru_log'
length(x)