Type:	Package
Title:	Bayesian Latent Gaussian Modelling using INLA and Extensions
Version:	2.13.0
URL:	http://www.inlabru.org, https://inlabru-org.github.io/inlabru/, https://github.com/inlabru-org/inlabru
BugReports:	https://github.com/inlabru-org/inlabru/issues
Description:	Facilitates spatial and general latent Gaussian modeling using integrated nested Laplace approximation via the INLA package (https://www.r-inla.org). Additionally, extends the GAM-like model class to more general nonlinear predictor expressions, and implements a log Gaussian Cox process likelihood for modeling univariate and spatial point processes based on ecological survey data. Model components are specified with general inputs and mapping methods to the latent variables, and the predictors are specified via general R expressions, with separate expressions for each observation likelihood model in multi-likelihood models. A prediction method based on fast Monte Carlo sampling allows posterior prediction of general expressions of the latent variables. Ecology-focused introduction in Bachl, Lindgren, Borchers, and Illian (2019) <doi:10.1111/2041-210X.13168>.
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Additional_repositories:	https://inla.r-inla-download.org/R/testing
RoxygenNote:	7.3.2
Encoding:	UTF-8
Depends:	fmesher (≥ 0.4.0), methods, R (≥ 3.6), stats
Imports:	dplyr, lifecycle, magrittr, MatrixModels, Matrix, plyr, rlang, sf, tibble, utils, withr
Suggests:	covr, ggplot2, graphics, INLA (≥ 23.01.31), knitr, maps, mgcv, patchwork, raster, RColorBrewer, rgl, rmarkdown, scales, scoringRules, shiny, sn, sp (≥ 2.1), spatstat.geom, spatstat.data, sphereplot, splancs, terra, tidyterra, testthat (≥ 3.2.0), tidyr, DiagrammeR
Enhances:	stars
Config/testthat/parallel:	true
Config/testthat/edition:	3
Collate:	'0_inlabru_envir.R' 'bru.gof.R' 'bru.inference.R' 'bru_conversion.R' 'bru_index.R' 'bru_input.R' 'bru_sp.R' 'data.Poisson1_1D.R' 'data.Poisson2_1D.R' 'data.Poisson3_1D.R' 'data.gorillas.R' 'data.mexdolphin.R' 'data.mrsea.R' 'data.robins_subset.R' 'data.shrimp.R' 'data.toygroups.R' 'data.toypoints.R' 'deltaIC.R' 'deprecated.R' 'effect.R' 'environment.R' 'fmesher.R' 'ggplot.R' 'inla.R' 'inlabru-package.R' 'local_testthat.R' 'mappers.R' 'mapper_collect.R' 'mapper_repeat.R' 'mapper_sum.R' 'model.R' 'nlinla.R' 'plotsample.R' 'rgl.R' 'sampling.R' 'spatstat.R' 'spde.R' 'stack.R' 'track_plotting.R' 'transformation.R' 'used.R' 'utils.R'
VignetteBuilder:	knitr
BuildVignettes:	true
LazyData:	true
LazyDataCompression:	xz
NeedsCompilation:	no
Packaged:	2025-07-09 20:33:47 UTC; flindgre
Author:	Finn Lindgren [aut, cre, cph] (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, bugfixes, and vignettes), Suen Man Ho [ctb, cph] (Man Ho Suen contributed features for aggregated responses and vignette updates), Roudier Pierre [ctb, cph] (Pierre Roudier contributed general quantile summaries), Meehan Tim [ctb, cph] (Tim Meehan contributed the SVC vignette and robins data), Reddy Peddinenikalva Niharika [ctb, cph] (Niharika Peddinenikalva contributed the LGCP residuals vignette), Perepolkin Dmytro [ctb, cph] (Dmytro Perepolkin contributed the ZIP/ZAP vignette)
Maintainer:	Finn Lindgren <finn.lindgren@gmail.com>
Repository:	CRAN
Date/Publication:	2025-07-09 21:20:02 UTC

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 bachlfab@gmail.com and Finn Lindgren finn.lindgren@gmail.com

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

1-Dimensional Homogeneous Poisson example.

Description

Point data and count data, together with intensity function and expected counts for a homogeneous 1-dimensional Poisson process example.

Usage

data(Poisson1_1D)

Format

The data contain the following R objects:

lambda1_1D

A function defining the intensity function of a nonhomogeneous Poisson process. Note that this function is only defined on the interval (0,55).

E_nc1

The expected counts of the gridded data.

pts1

The locations of the observed points (a data frame with one column, named x).

countdata1

A data frame with three columns, containing the count data:

x

The grid cell midpoint.

count

The number of detections in the cell.

exposure

The width of the cell.

Examples

if (require("ggplot2", quietly = TRUE)) {
  data(Poisson1_1D)
  ggplot(countdata1) +
    geom_point(data = countdata1, aes(x = x, y = count), col = "blue") +
    ylim(0, max(countdata1$count)) +
    geom_point(data = pts1, aes(x = x), y = 0.2, shape = "|", cex = 4) +
    geom_point(
      data = countdata1, aes(x = x), y = 0, shape = "+",
      col = "blue", cex = 4
    ) +
    xlab(expression(bold(s))) +
    ylab("count")
}

1-Dimensional NonHomogeneous Poisson example.

Description

Point data and count data, together with intensity function and expected counts for a unimodal nonhomogeneous 1-dimensional Poisson process example.

Usage

data(Poisson2_1D)

Format

The data contain the following R objects:

lambda2_1D:

A function defining the intensity function of a nonhomogeneous Poisson process. Note that this function is only defined on the interval (0,55).

cov2_1D:

A function that gives what we will call a 'habitat suitability' covariate in 1D space.

E_nc2

The expected counts of the gridded data.

pts2

The locations of the observed points (a data frame with one column, named x).

countdata2

A data frame with three columns, containing the count data:

x

The grid cell midpoint.

count

The number of detections in the cell.

exposure

The width of the cell.

Examples

if (require("ggplot2", quietly = TRUE)) {
  data(Poisson2_1D)
  p1 <- ggplot(countdata2) +
    geom_point(data = countdata2, aes(x = x, y = count), col = "blue") +
    ylim(0, max(countdata2$count, E_nc2)) +
    geom_point(
      data = countdata2, aes(x = x), y = 0, shape = "+",
      col = "blue", cex = 4
    ) +
    geom_point(
      data = data.frame(x = countdata2$x, y = E_nc2), aes(x = x),
      y = E_nc2, shape = "_", cex = 5
    ) +
    xlab(expression(bold(s))) +
    ylab("count")
  ss <- seq(0, 55, length.out = 200)
  lambda <- lambda2_1D(ss)
  p2 <- ggplot() +
    geom_line(
      data = data.frame(x = ss, y = lambda),
      aes(x = x, y = y), col = "blue"
    ) +
    ylim(0, max(lambda)) +
    geom_point(data = pts2, aes(x = x), y = 0.2, shape = "|", cex = 4) +
    xlab(expression(bold(s))) +
    ylab(expression(lambda(bold(s))))
  multiplot(p1, p2, cols = 1)
}

1-Dimensional NonHomogeneous Poisson example.

Description

Point data and count data, together with intensity function and expected counts for a multimodal nonhomogeneous 1-dimensional Poisson process example. Counts are given for two different gridded data interval widths.

Usage

data(Poisson3_1D)

Format

The data contain the following R objects:

lambda3_1D

A function defining the intensity function of a nonhomogeneous Poisson process. Note that this function is only defined on the interval (0,55).

E_nc3a

The expected counts of gridded data for the wider bins (10 bins).

E_nc3b

The expected counts of gridded data for the wider bins (20 bins).

pts3

The locations of the observed points (a data frame with one column, named x).

countdata3a

A data frame with three columns, containing the count data for the 10-interval case:

countdata3b

A data frame with three columns, containing the count data for the 20-interval case:

x

The grid cell midpoint.

count

The number of detections in the cell.

exposure

The width of the cell.

Examples

if (require("ggplot2", quietly = TRUE)) {
  data(Poisson3_1D)
  # first the plots for the 10-bin case:
  p1a <- ggplot(countdata3a) +
    geom_point(data = countdata3a, aes(x = x, y = count), col = "blue") +
    ylim(0, max(countdata3a$count, E_nc3a)) +
    geom_point(
      data = countdata3a, aes(x = x), y = 0, shape = "+",
      col = "blue", cex = 4
    ) +
    geom_point(
      data = data.frame(x = countdata3a$x, y = E_nc3a),
      aes(x = x), y = E_nc3a, shape = "_", cex = 5
    ) +
    xlab(expression(bold(s))) +
    ylab("count")
  ss <- seq(0, 55, length.out = 200)
  lambda <- lambda3_1D(ss)
  p2a <- ggplot() +
    geom_line(
      data = data.frame(x = ss, y = lambda), aes(x = x, y = y),
      col = "blue"
    ) +
    ylim(0, max(lambda)) +
    geom_point(data = pts3, aes(x = x), y = 0.2, shape = "|", cex = 4) +
    xlab(expression(bold(s))) +
    ylab(expression(lambda(bold(s))))
  multiplot(p1a, p2a, cols = 1)

  # Then the plots for the 20-bin case:
  p1a <- ggplot(countdata3b) +
    geom_point(data = countdata3b, aes(x = x, y = count), col = "blue") +
    ylim(0, max(countdata3b$count, E_nc3b)) +
    geom_point(
      data = countdata3b, aes(x = x), y = 0, shape = "+",
      col = "blue", cex = 4
    ) +
    geom_point(
      data = data.frame(x = countdata3b$x, y = E_nc3b),
      aes(x = x), y = E_nc3b, shape = "_", cex = 5
    ) +
    xlab(expression(bold(s))) +
    ylab("count")
  ss <- seq(0, 55, length.out = 200)
  lambda <- lambda3_1D(ss)
  p2a <- ggplot() +
    geom_line(
      data = data.frame(x = ss, y = lambda), aes(x = x, y = y),
      col = "blue"
    ) +
    ylim(0, max(lambda)) +
    geom_point(data = pts3, aes(x = x), y = 0.2, shape = "|", cex = 4) +
    xlab(expression(bold(s))) +
    ylab(expression(lambda(bold(s))))
  multiplot(p1a, p2a, cols = 1)
}

Add component input/latent mappers

Description

Add missing mappers between input data and latent variables, based on likelihood data

Equip component(s) with mappers for subcomponents that do not have predefined mappers. When needed, the data in lhoods is used to determine the appropriate mapper(s).

Usage

add_mappers(...)

## S3 method for class 'bru_comp'
add_mappers(component, lhoods, inputs = NULL, lh_data = NULL, ...)

## S3 method for class 'bru_comp_list'
add_mappers(components, lhoods, inputs = NULL, lh_data = NULL, ...)

Arguments

Value

A component object with completed mapper information

Examples

## Not run: 
if (interactive() && bru_safe_inla()) {
}

## End(Not run)

Conversion methods for bru_comp and bru_comp_list objects

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

See Also

as_bru_obs(), as_bru_obs_list()

Methods for mapper extraction

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)

Conversion methods for bru_obs and bru_obs_list objects

Description

Methods for converting to bru_obs and bru_obs_list objects.

Usage

as_bru_obs(x, ...)

as_bru_obs_list(x, ...)

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

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

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

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

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

Arguments

Value

An object of class bru_obs or bru_obs_list.

See Also

as_bru_comp_list()

1D LGCP bin count simulation and comparison with data

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

Mapper for aggregation

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

## S3 method for class 'bm_aggregate'
ibm_n(mapper, ..., input = NULL, state = NULL, n_state = NULL)

## S3 method for class 'bm_aggregate'
ibm_n_output(mapper, input = NULL, ...)

## S3 method for class 'bm_aggregate'
ibm_values(mapper, ..., state = NULL, n_state = NULL)

## S3 method for class 'bm_aggregate'
ibm_jacobian(mapper, input, state = NULL, ...)

## S3 method for class 'bm_aggregate'
ibm_eval(mapper, input, state = NULL, ..., sub_lin = NULL)

Arguments

Methods (by generic)

• ibm_jacobian(bm_aggregate): input should be a list with elements block and weights. block should be a vector of the same length as the state, or NULL, with NULL equivalent to all-1. If weights is NULL, it's interpreted as all-1.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_collect(), bm_const(), bm_factor(), bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

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)

Mapper for concatenated variables

Description

Constructs a concatenated collection mapping

Usage

bm_collect(mappers, hidden = FALSE)

bru_mapper_collect(...)

## S3 method for class 'bm_collect'
ibm_n(mapper, inla_f = FALSE, multi = FALSE, ...)

## S3 method for class 'bm_collect'
ibm_n_output(mapper, input, state = NULL, inla_f = FALSE, multi = FALSE, ...)

## S3 method for class 'bm_collect'
ibm_values(mapper, inla_f = FALSE, multi = FALSE, ...)

## S3 method for class 'bm_collect'
ibm_is_linear(mapper, inla_f = FALSE, multi = FALSE, ...)

## S3 method for class 'bm_collect'
ibm_jacobian(
  mapper,
  input,
  state = NULL,
  inla_f = FALSE,
  multi = FALSE,
  ...,
  sub_lin = NULL
)

## S3 method for class 'bm_collect'
ibm_eval(
  mapper,
  input,
  state,
  inla_f = FALSE,
  multi = FALSE,
  ...,
  sub_lin = NULL
)

## S3 method for class 'bm_collect'
ibm_linear(mapper, input, state, inla_f = FALSE, ...)

## S3 method for class 'bm_collect'
ibm_invalid_output(mapper, input, state, inla_f = FALSE, multi = FALSE, ...)

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

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

## S3 method for class 'bm_collect'
ibm_names(mapper)

## S3 replacement method for class 'bm_collect'
ibm_names(mapper) <- value

## S3 replacement method for class 'bru_mapper_collect'
ibm_names(mapper) <- value

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)

• The names() method for bm_collect returns the names from the sub-mappers list

Methods (by generic)

• ibm_jacobian(bm_collect): Accepts a list with named entries, or a list with unnamed but ordered elements. The names must match the sub-mappers, see ibm_names.bm_collect(). Each list element should take a format accepted by the corresponding sub-mapper. In case each element is a vector, the input can be given as a data.frame with named columns, a matrix with named columns, or a matrix with unnamed but ordered columns. When inla_f=TRUE and hidden=TRUE in the mapper definition, the input format should instead match that of the first, non-hidden, sub-mapper.

• ibm_invalid_output(bm_collect): Accepts a list with named entries, or a list with unnamed but ordered elements. The names must match the sub-mappers, see ibm_names.bm_collect(). Each list element should take a format accepted by the corresponding sub-mapper. In case each element is a vector, the input can be given as a data.frame with named columns, a matrix with named columns, or a matrix with unnamed but ordered columns.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_const(), bm_factor(), bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

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)

Constant mapper

Description

Create a constant mapper

Usage

bm_const()

bru_mapper_const()

## S3 method for class 'bm_const'
ibm_n(mapper, ...)

## S3 method for class 'bm_const'
ibm_values(mapper, ...)

## S3 method for class 'bm_const'
ibm_jacobian(mapper, input, ...)

## S3 method for class 'bm_const'
ibm_eval(mapper, input, state = NULL, ...)

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_factor(), bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

Examples

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

Mapper for factor variables

Description

Create a factor mapper

Usage

bm_factor(values, factor_mapping, indexed = FALSE)

bru_mapper_factor(...)

## S3 method for class 'bm_factor'
ibm_n(mapper, ...)

## S3 method for class 'bm_factor'
ibm_values(mapper, ...)

## S3 method for class 'bm_factor'
ibm_jacobian(mapper, input, ...)

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

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)

Mapper for general fmesher function space objects

Description

Creates a mapper for general fmesher function space objects.

Usage

bm_fmesher(mesh)

bru_mapper_fmesher(...)

## S3 method for class 'bm_fmesher'
ibm_n(mapper, ...)

## S3 method for class 'bm_fmesher'
ibm_values(mapper, ...)

## S3 method for class 'bm_fmesher'
ibm_jacobian(mapper, input, ...)

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.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_harmonics(), bm_index(), bm_linear(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

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

Mapper for cos/sin functions

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

## S3 method for class 'bm_harmonics'
ibm_n(mapper, inla_f = FALSE, ...)

## S3 method for class 'bm_harmonics'
ibm_jacobian(mapper, input, state = NULL, inla_f = FALSE, ...)

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fmesher(), bm_index(), bm_linear(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

Examples

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

Mapper for indexed variables

Description

Create a an indexing mapper

Usage

bm_index(n = 1L, ...)

bru_mapper_index(...)

## S3 method for class 'bm_index'
ibm_invalid_output(mapper, input, state, ...)

## S3 method for class 'bm_index'
ibm_jacobian(mapper, input, state, ...)

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fmesher(), bm_harmonics(), bm_linear(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

Examples

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

Mapper for a linear effect

Description

Create a mapper for linear effects

Usage

bm_linear()

bru_mapper_linear()

## S3 method for class 'bm_linear'
ibm_n(mapper, ...)

## S3 method for class 'bm_linear'
ibm_values(mapper, ...)

## S3 method for class 'bm_linear'
ibm_jacobian(mapper, input, ...)

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fmesher(), bm_harmonics(), bm_index(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

Examples

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

Methods for mapper lists

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]

## S3 method for class 'bm_list'
ibm_linear(mapper, input, state = NULL, ...)

## S3 method for class 'bm_list'
ibm_simplify(mapper, input = NULL, state = NULL, ...)

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])

Mapper for log-sum-exp aggregation

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

## S3 method for class 'bm_logsumexp'
ibm_jacobian(mapper, input, state = NULL, ...)

## S3 method for class 'bm_logsumexp'
ibm_eval(mapper, input, state = NULL, log = TRUE, ..., sub_lin = NULL)

Arguments

Methods (by generic)

• ibm_jacobian(bm_logsumexp): input should be a list with elements block and weights. block should be a vector of the same length as the state, or NULL, with NULL equivalent to all-1. If weights is NULL, it's interpreted as all-1.

• ibm_eval(bm_logsumexp): When log is TRUE (default), ibm_eval() for logsumexp returns the log-sum-weight-exp value. If FALSE, the sum-weight-exp value is returned.

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_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

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)

Mapper for marginal distribution transformation

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

## S3 method for class 'bm_marginal'
ibm_n(mapper, ..., state = NULL, n_state = NULL)

## S3 method for class 'bm_marginal'
ibm_n_output(mapper, input, state = NULL, ..., n_state = NULL)

## S3 method for class 'bm_marginal'
ibm_values(mapper, ..., state = NULL, n_state = NULL)

## S3 method for class 'bm_marginal'
ibm_jacobian(mapper, input, state = NULL, ..., reverse = FALSE)

## S3 method for class 'bm_marginal'
ibm_eval(mapper, input, state = NULL, ..., reverse = FALSE)

Arguments

Methods (by generic)

• ibm_jacobian(bm_marginal): Non-NULL input values are interpreted as a parameter list for qfun, overriding that of the mapper itself.

• ibm_eval(bm_marginal): When xor(mapper[["inverse"]], reverse) is FALSE, ibm_eval() for marginal returns qfun(pnorm(x), param), evaluated in a numerically stable way. Otherwise, evaluates the inverse qnorm(pfun(x, param)) instead.

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_logsumexp(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

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)

Mapper for matrix multiplication

Description

Create a matrix mapper, for a given number of columns

Usage

bm_matrix(labels)

bru_mapper_matrix(...)

## S3 method for class 'bm_matrix'
ibm_n(mapper, ...)

## S3 method for class 'bm_matrix'
ibm_values(mapper, ...)

## S3 method for class 'bm_matrix'
ibm_jacobian(mapper, input, state = NULL, inla_f = FALSE, ...)

Arguments

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_logsumexp(), bm_marginal(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

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)

Mapper for basis conversion

Description

Creates a mapper for handling basis conversions

Usage

bm_mesh_B(mesh, B)

bru_mapper_mesh_B(...)

## S3 method for class 'bm_mesh_B'
ibm_n(mapper, ...)

## S3 method for class 'bm_mesh_B'
ibm_values(mapper, ...)

## S3 method for class 'bm_mesh_B'
ibm_jacobian(mapper, input, ...)

Arguments

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_logsumexp(), bm_marginal(), bm_matrix(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

Mapper for tensor product domains

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)

bru_mapper_multi(mappers)

## S3 method for class 'bm_multi'
ibm_n(mapper, inla_f = FALSE, multi = FALSE, ...)

## S3 method for class 'bm_multi'
ibm_n_output(mapper, input, ...)

## S3 method for class 'bm_multi'
ibm_values(mapper, inla_f = FALSE, multi = FALSE, ...)

## S3 method for class 'bm_multi'
ibm_is_linear(mapper, multi = FALSE, ...)

## S3 method for class 'bm_multi'
ibm_jacobian(
  mapper,
  input,
  state = NULL,
  inla_f = FALSE,
  multi = FALSE,
  ...,
  sub_A = NULL
)

## S3 method for class 'bm_multi'
ibm_linear(mapper, input, state, inla_f = FALSE, ...)

## S3 method for class 'bm_multi'
ibm_eval(
  mapper,
  input,
  state = NULL,
  inla_f = FALSE,
  ...,
  jacobian = NULL,
  pre_A = deprecated()
)

## S3 method for class 'bm_multi'
ibm_invalid_output(mapper, input, state, inla_f = FALSE, multi = FALSE, ...)

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

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

## S3 method for class 'bm_multi'
ibm_names(mapper)

## S3 replacement method for class 'bm_multi'
ibm_names(mapper) <- value

## S3 replacement method for class 'bru_mapper_multi'
ibm_names(mapper) <- value

Arguments

Value

• [-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)

Methods (by generic)

• ibm_jacobian(bm_multi): Accepts a list with named entries, or a list with unnamed but ordered elements. The names must match the sub-mappers, see ibm_names.bm_multi(). Each list element should take a format accepted by the corresponding sub-mapper. In case each element is a vector, the input can be given as a data.frame with named columns, a matrix with named columns, or a matrix with unnamed but ordered columns.

• ibm_invalid_output(bm_multi): Accepts a list with named entries, or a list with unnamed but ordered elements. The names must match the sub-mappers, see ibm_names.bm_multi(). Each list element should take a format accepted by the corresponding sub-mapper. In case each element is a vector, the input can be given as a data.frame with named columns, a matrix with named columns, or a matrix with unnamed but ordered columns.

• ibm_names(bm_multi): Returns the names from the sub-mappers list

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_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

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)

Mapper for linking several mappers in sequence

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

## S3 method for class 'bm_pipe'
ibm_n(mapper, ..., input = NULL, state = NULL)

## S3 method for class 'bm_pipe'
ibm_n_output(mapper, input, state = NULL, ..., n_state = NULL)

## S3 method for class 'bm_pipe'
ibm_values(mapper, ...)

## S3 method for class 'bm_pipe'
ibm_jacobian(mapper, input, state = NULL, ...)

## S3 method for class 'bm_pipe'
ibm_eval(mapper, input, state = NULL, ...)

## S3 method for class 'bm_pipe'
ibm_eval2(mapper, input, state = NULL, ...)

## S3 method for class 'bm_pipe'
ibm_simplify(
  mapper,
  input = NULL,
  state = NULL,
  inla_f = FALSE,
  ...,
  n_state = NULL
)

Arguments

Methods (by generic)

• ibm_simplify(bm_pipe): Constructs a simplified pipe mapper. For fully linear pipes, calls ibm_linear(). For partially non-linear pipes, replaces each sequence of linear mappers with a single bm_taylor() mapper, while keeping the full list of original mapper names, allowing the original input structure to be used also with the simplified mappers, since the taylor mappers are not dependent on inputs.

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_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

Examples

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

Mapper for repeating a mapper

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

## S3 method for class 'bm_repeat'
ibm_n(mapper, ...)

## S3 method for class 'bm_repeat'
ibm_n_output(mapper, ...)

## S3 method for class 'bm_repeat'
ibm_values(mapper, ...)

## S3 method for class 'bm_repeat'
ibm_jacobian(
  mapper,
  input,
  state = NULL,
  inla_f = FALSE,
  multi = FALSE,
  ...,
  sub_lin = NULL
)

## S3 method for class 'bm_repeat'
ibm_eval(mapper, input, state, multi = FALSE, ..., sub_lin = NULL)

## S3 method for class 'bm_repeat'
ibm_linear(mapper, input, state, ...)

## S3 method for class 'bm_repeat'
ibm_invalid_output(mapper, input, state, ...)

Arguments

Value

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

Methods (by generic)

• ibm_jacobian(bm_repeat): The input should take the format of the repeated submapper.

• ibm_invalid_output(bm_repeat): Passes on the input to the corresponding method.

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_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

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

Re-indexing matrix for repeated mappers

Description

Helper methods for regular and interleaved state vector indexing, meant for use in bm_repeat mappers.

Usage

bm_repeat_indexing(n_map, n_rep, interleaved = FALSE)

bm_repeat_indexing_matrix(n_map, n_rep)

Arguments

Value

bm_repeat_indexing: Returns a list with a vector of offsets, offsets, and a vector of relative index values, index; block k indexing is given by offsets[k] + index.

bm_repeat_indexing_matrix: A sparseMatrix object.

Functions

• bm_repeat_indexing(): Construct the offsets and within-block index vectors for a repeated mapper, with or without interleaving.

• bm_repeat_indexing_matrix(): Creates a sparse matrix A such that z <- A %*% x constructs a blockwise version z = c(x1, x2, ..., xn) of an interleaved state vector x = c(x1[1], x2[1], ..., x1[2], x2[2], ...). Each block is of size n_map, and there are n_rep blocks. The reverse operation, taking a blockwise z = c(x1, x2, ..., xn) to an interleaved vector is x <- Matrix::t(A) %*% z.

Examples

(idx <- bm_repeat_indexing(3, 2, FALSE))
(idx <- bm_repeat_indexing(3, 2, TRUE))
(A <- bm_repeat_indexing_matrix(3, 2))
(x_interleaved <- 1:6)
(x_blockwise <- as.vector(A %*% x_interleaved))
(x_recovered <- as.vector(Matrix::t(A) %*% x_blockwise))

Mapper for element-wise scaling

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

## S3 method for class 'bm_scale'
ibm_n(mapper, ..., state = NULL, n_state = NULL)

## S3 method for class 'bm_scale'
ibm_n_output(mapper, input, state = NULL, ..., n_state = NULL)

## S3 method for class 'bm_scale'
ibm_values(mapper, ..., state = NULL, n_state = NULL)

## S3 method for class 'bm_scale'
ibm_jacobian(mapper, input, state = NULL, ..., sub_lin = NULL)

## S3 method for class 'bm_scale'
ibm_eval(mapper, input, state = NULL, ..., sub_lin = NULL)

Arguments

Methods (by generic)

• ibm_jacobian(bm_scale): input NULL values are interpreted as no scaling.

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_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

Examples

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

Mapper for element-wise shifting

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

## S3 method for class 'bm_shift'
ibm_n(mapper, ..., state = NULL, n_state = NULL)

## S3 method for class 'bm_shift'
ibm_n_output(mapper, input, state = NULL, ..., n_state = NULL)

## S3 method for class 'bm_shift'
ibm_values(mapper, ..., state = NULL, n_state = NULL)

## S3 method for class 'bm_shift'
ibm_jacobian(mapper, input, state = NULL, ..., sub_lin = NULL)

## S3 method for class 'bm_shift'
ibm_eval(mapper, input, state = NULL, ..., sub_lin = NULL)

Arguments

Methods (by generic)

• ibm_jacobian(bm_shift): input NULL values are interpreted as no shift.

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_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

Examples

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

Mapper for adding multiple mappers

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'
ibm_n(mapper, inla_f = FALSE, multi = FALSE, ...)

## S3 method for class 'bm_sum'
ibm_n_output(mapper, input, state = NULL, ...)

## S3 method for class 'bm_sum'
ibm_values(mapper, inla_f = FALSE, multi = FALSE, ...)

## S3 method for class 'bm_sum'
ibm_is_linear(mapper, multi = FALSE, ...)

## S3 method for class 'bm_sum'
ibm_jacobian(
  mapper,
  input,
  state = NULL,
  inla_f = FALSE,
  multi = FALSE,
  ...,
  sub_lin = NULL
)

## S3 method for class 'bm_sum'
ibm_eval(mapper, input, state, multi = FALSE, ..., sub_lin = NULL)

## S3 method for class 'bm_sum'
ibm_linear(mapper, input, state, ...)

## S3 method for class 'bm_sum'
ibm_invalid_output(mapper, input, state, multi = FALSE, ...)

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

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

## S3 method for class 'bm_sum'
ibm_names(mapper)

## S3 replacement method for class 'bm_sum'
ibm_names(mapper) <- value

## S3 replacement method for class 'bru_mapper_sum'
ibm_names(mapper) <- value

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)

• The names() method for bm_sum returns the names from the sub-mappers list

Methods (by generic)

• ibm_jacobian(bm_sum): Accepts a list with named entries, or a list with unnamed but ordered elements. The names must match the sub-mappers, see ibm_names.bm_sum(). Each list element should take a format accepted by the corresponding sub-mapper. In case each element is a vector, the input can be given as a data.frame with named columns, a matrix with named columns, or a matrix with unnamed but ordered columns.

• ibm_invalid_output(bm_sum): Accepts a list with named entries, or a list with unnamed but ordered elements. The names must match the sub-mappers, see ibm_names.bm_sum(). Each list element should take a format accepted by the corresponding sub-mapper. In case each element is a vector, the input can be given as a data.frame with named columns, a matrix with named columns, or a matrix with unnamed but ordered columns.

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_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

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

Mapper for linear Taylor approximations

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

## S3 method for class 'bm_taylor'
ibm_n(mapper, inla_f = FALSE, multi = FALSE, ...)

## S3 method for class 'bm_taylor'
ibm_n_output(mapper, input, ...)

## S3 method for class 'bm_taylor'
ibm_values(mapper, inla_f = FALSE, multi = FALSE, ...)

## S3 method for class 'bm_taylor'
ibm_jacobian(mapper, ..., multi = FALSE)

## S3 method for class 'bm_taylor'
ibm_eval(mapper, input = NULL, state = NULL, ...)

Arguments

Methods (by generic)

• ibm_eval(bm_taylor): Evaluates linearised mapper information at the given state. The input argument is ignored, so that the usual argument order ibm_eval(mapper, input, state) syntax can be used, but also ibm_eval(mapper, state = state). For a mapper with a named jacobian list, the state argument must also be a named list. If state is NULL, all-zero is assumed.

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_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

Examples

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

Convenient model fitting using (iterated) INLA

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 likelihoods is straight forward. See like for more information on how to provide additional likelihoods 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'
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)

• 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 bachlfab@gmail.com

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
}

Additional bru options

Description

Construct a bru_options object including the default and global options, and converting deprecated option names.

Usage

bru_call_options(...)

Arguments

Value

A bru_options object

Author(s)

Finn Lindgren finn.lindgren@gmail.com

Examples

opts <- bru_call_options()

# Print them:
opts

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

Deprecated parameters:

• map: Use main instead.

• mesh: Use mapper instead.

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 bachlfab@gmail.com and Finn Lindgren Finn.Lindgren@gmail.com

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(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)
}

Evaluate component values in predictor expressions

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
  )
}

Methods for inlabru component lists

Description

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

Usage

bru_comp_list(object, lhoods = NULL, .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_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 and/or component formulas into a bru_comp_list object

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 bachlfab@gmail.com and Finn Lindgren finn.lindgren@gmail.com

See Also

Other component constructors: bru_comp()

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")

Compute inlabru model linearisation information

Description

Compute inlabru model linearisation information

Usage

bru_compute_linearisation(...)

## S3 method for class 'bru_comp'
bru_compute_linearisation(
  cmp,
  model,
  lhood_expr,
  data,
  data_extra,
  input,
  state,
  comp_simple,
  effects,
  pred0,
  used,
  allow_combine,
  eps,
  n_pred = NULL,
  ...
)

## S3 method for class 'bru_obs'
bru_compute_linearisation(
  lhood,
  model,
  data,
  input,
  state,
  comp_simple,
  eps,
  ...
)

## S3 method for class 'bru_obs_list'
bru_compute_linearisation(
  lhoods,
  model,
  input,
  state,
  comp_simple,
  eps = 1e-05,
  ...
)

## S3 method for class 'bru_model'
bru_compute_linearisation(model, lhoods, input, state, comp_simple, ...)

Arguments

Plot inlabru convergence diagnostics

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", "magrittr", 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)

Get access to the internal environment

Description

Get access to the internal environment

Usage

bru_env_get()

Details

The environment is defined in ⁠0_inlabru_envir.R⁠ which is loaded first.

Evaluate expressions in data contexts

Description

Evaluate an expression in a series of data contexts, also making the objects directly available as names surrounded by ".", stopping when the expression evaluation completes with no error.

This is an internal inlabru method, not intended for general use.

Usage

bru_eval_in_data_context(
  input,
  data = NULL,
  default = NULL,
  .envir = parent.frame()
)

Arguments

Value

The result of expression evaluation

Examples

# The A values come from the 'data' element, and the B values come from
# the 'response_data' element, as that is listed first.
bru_eval_in_data_context(
  quote(
    list(A = .data.$x, B = x)
  ),
  list(
    response_data = tibble::tibble(x = 1:5),
    data = tibble::tibble(x = 1:10)
  )
)
# Both A and B come from the 'data' element, as 'x' is found there,
# terminating the evaluation attempt.
bru_eval_in_data_context(
  quote(
    list(A = .data.$x, B = x)
  ),
  list(
    data = tibble::tibble(x = 1:10),
    response_data = tibble::tibble(x = 1:5)
  )
)

Fill in missing values in Spatial grids

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 (bru_safe_inla()) {
  points <-
    sp::SpatialPointsDataFrame(
      matrix(1:6, 3, 2),
      data = data.frame(val = c(NA, NA, NA))
    )
  input_coord <- expand.grid(x = 0:7, y = 0:7)
  input <-
    sp::SpatialPixelsDataFrame(
      input_coord,
      data = data.frame(val = as.vector(input_coord$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)

Convert components to R code

Description

Convert components to R code

Usage

bru_formula_to_bru_obs_code(components, add = "")

Arguments

Author(s)

Fabian E. Bachl bachlfab@gmail.com

Extract mapper information from INLA model component objects

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

bru_get_mapper_safely(model, ...)

Arguments

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 call to model$f$rgeneric$definition("mapper"). To support this for your own inla.rgeneric models, add a "mapper" option to the cmd argument of your rgeneric definition function. You will need to store the mapper in your object as well. Alternative, define your model using a subclass and define a corresponding bru_get_mapper.subclass method that should return the corresponding bru_mapper object.

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_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

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)
}

Extract predictor or component index information

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'
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): 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): 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 bachlfab@gmail.com, Finn Lindgren finn.lindgren@gmail.com

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"
  )
)
bru_index(fit)
bru_index(fit, "A")
bru_index(fit, "B")
bru_index(fit, c("B", "A"))
bru_index(fit, what = "missing")

Methods for bru_info objects

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

## 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 show information about model components and observation models.

Backwards compatibility to handle mexpand for INLA <= 24.06.02

Description

Expand observation vectors/matrices in stacks into to a multicolumn matrix for multiple likelihoods

Usage

bru_inla.stack.mexpand(
  ...,
  old.names = "BRU.response",
  new.name = "BRU.response"
)

Arguments

Value

a list of modified stacks with multicolumn observations

Author(s)

Fabian E. Bachl f.e.bachl@bath.ac.uk and Finn Lindgren finn.lindgren@gmail.com

Join stacks intended to be run with different likelihoods

Description

Helper functions for multi-likelihood models

Usage

bru_inla.stack.mjoin(
  ...,
  compress = TRUE,
  remove.unused = TRUE,
  old.names = "BRU.response",
  new.name = "BRU.response"
)

Arguments

Obtain component inputs

Description

Obtain component inputs

Usage

bru_input(...)

## Default S3 method:
bru_input(input, label = NULL, layer = NULL, selector = NULL, ...)

## S3 method for class 'bru_comp'
bru_input(component, data, ...)

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

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

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

## S3 method for class 'bru_input'
bru_input(input, data, env = NULL, null.on.fail = FALSE, ...)

input_eval(...)

evaluate_inputs(...)

Arguments

Value

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

Methods (by class)

• bru_input(default): Create a bru_input object.

• bru_input(bru_obs_list): Computes the component inputs for included components for each model likelihood

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

  1. If eval() 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, (e.g. via used or include/exclude) 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. 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

Functions

• input_eval(): from ⁠2.12.0.9023⁠. Use bru_input() instead.

• evaluate_inputs(): since version ⁠2.12.0.9023⁠. Use bru_input() instead. Computes the component inputs for included components for each observation model.

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
}

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 bachlfab@gmail.com, Finn Lindgren finn.lindgren@gmail.com

See Also

summary.bru_input(), bru_comp()

Examples

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

Check for predictor expression additivity

Description

Checks if a predictor expression is additive or not

Usage

bru_is_additive(x, ...)

## S3 method for class 'data.frame'
bru_is_additive(x, root_id = 0, ..., verbose = FALSE)

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

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

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

Arguments

Value

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

Access methods for bru_log objects

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)

Arguments

Value

bru_log A bru_log object, containing a character vector of log messages, and potentially a vector of bookmarks.

Methods (by generic)

• format(bru_log): Format a bru_log object for printing. If verbosity is TRUE, include the verbosity level of each message.

• print(bru_log): Print a bru_log object with cat(x, sep = "\n"). If verbosity is TRUE, include the verbosity level of each message.

• as.character(bru_log): Convert bru_log object to a plain character vector

• [: Extract a subset of a bru_log object

• c(bru_log): Concatenate several bru_log or character objects into a bru_log object.

• length(bru_log): Obtain the number of log entries into a bru_log object.

Functions

• bru_log(): Extract stored log messages. If non-NULL, the verbosity argument determines the maximum verbosity level of the messages to extract.

See Also

Other inlabru log methods: bru_log_bookmark(), bru_log_message(), bru_log_new(), bru_log_offset(), bru_log_reset()

Examples

bru_log(verbosity = 2L)
format(bru_log())

bru_log(verbosity = 2L)
print(bru_log(), timestamp = TRUE, verbosity = TRUE)

Methods for bru_log bookmarks

Description

Methods for bru_log bookmarks.

Usage

bru_log_bookmark(bookmark = "", offset = NULL, x = NULL)

bru_log_bookmarks(x = NULL)

Arguments

Value

bru_log_bookmark(): Returns the modified bru_log object if x is non-NULL.

bru_log_bookmarks(): Returns the bookmark vector associated with x

Functions

• bru_log_bookmark(): Set a log bookmark. If offset is NULL (the default), the bookmark will point to the current end of the log.

• bru_log_bookmarks(): Return a integer vector with named elements being bookmarks into the global inlabru log with associated log position offsets.

See Also

Other inlabru log methods: bru_log(), bru_log_message(), bru_log_new(), bru_log_offset(), bru_log_reset()

Add a log message

Description

Adds a log message.

Usage

bru_log_message(
  ...,
  domain = NULL,
  appendLF = TRUE,
  verbosity = 1L,
  allow_verbose = TRUE,
  verbose = NULL,
  verbose_store = NULL,
  x = NULL
)

bru_log_abort(
  msg,
  ...,
  domain = NULL,
  appendLF = TRUE,
  verbosity = 1L,
  allow_verbose = TRUE,
  verbose = FALSE,
  verbose_store = NULL,
  call = rlang::caller_env(),
  .frame = rlang::caller_env()
)

bru_log_warn(
  msg,
  ...,
  domain = NULL,
  appendLF = TRUE,
  verbosity = 1L,
  allow_verbose = TRUE,
  verbose = FALSE,
  verbose_store = NULL,
  call = rlang::caller_env(),
  .frame = rlang::caller_env()
)

Arguments

Value

bru_log_message returns invisible(x), where x is the updated bru_log object, or NULL.

Functions

• bru_log_abort(): Store a log message and throw an error.

• bru_log_warn(): Store a log message and throw a warning.

See Also

Other inlabru log methods: bru_log(), bru_log_bookmark(), bru_log_new(), bru_log_offset(), bru_log_reset()

Examples

if (interactive()) {
  code_runner <- function() {
    bru_options_set_local(
      # Show messages up to and including level 2 (default 0)
      bru_verbose = 2,
      # Store messages to an including level 3 (default Inf, storing all)
      bru_verbose_store = 3
    )

    bru_log_bookmark("bookmark 1")
    bru_log_message("Test message 1", verbosity = 1)
    bru_log_message("Test message 2", verbosity = 2)
    bru_log_bookmark("bookmark 2")
    bru_log_message("Test message 3", verbosity = 3)
    bru_log_message("Test message 4", verbosity = 4)

    invisible()
  }
  message("Run code")
  code_runner()
  message("Check log from bookmark 1")
  print(bru_log()["bookmark 1"])
  message("Check log from bookmark 2")
  print(bru_log()["bookmark 2"])
}

Create a bru_log object

Description

Create a bru_log object, by default empty.

Usage

bru_log_new(x = NULL, bookmarks = NULL)

Arguments

See Also

Other inlabru log methods: bru_log(), bru_log_bookmark(), bru_log_message(), bru_log_offset(), bru_log_reset()

Examples

x <- bru_log_new()
x <- bru_log_message("Test message", x = x)
print(x)

Position methods for bru_log objects

Description

Position methods for bru_log objects.

Usage

bru_log_offset(x = NULL, bookmark = NULL, offset = NULL)

bru_log_index(x = NULL, i, verbosity = NULL)

Arguments

Functions

• bru_log_offset(): Utility function for computing log position offsets.

• bru_log_index(): Utility function for computing index vectors for bru_log objects.

See Also

Other inlabru log methods: bru_log(), bru_log_bookmark(), bru_log_message(), bru_log_new(), bru_log_reset()

Clear log contents

Description

Clears the log contents up to a given offset or bookmark. Default: clear the entire log. When x is NULL, the global inlabru log is updated, and invisible(NULL) is returned. Otherwise the updated object is returned (invisibly).

Usage

bru_log_reset(x = NULL, bookmark = NULL, offset = NULL)

Arguments

Value

Returns (invisibly) the modified bru_log object, or NULL (when x is NULL)

See Also

Other inlabru log methods: bru_log(), bru_log_bookmark(), bru_log_message(), bru_log_new(), bru_log_offset()

Examples

## Not run: 
if (interactive()) {
  bru_log_reset()
}

## End(Not run)

Build an inla data stack from linearisation information

Description

Combine linearisation for multiple likelihoods

Usage

bru_make_stack(...)

## S3 method for class 'bru_obs'
bru_make_stack(lhood, lin, idx, ..., family_index = 1L)

## S3 method for class 'bru_obs_list'
bru_make_stack(lhoods, lin, idx, ...)

Arguments

Constructors for bru_mapper objects

Description

Constructors for bru_mapper objects

Usage

bru_mapper(...)

bru_mapper_define(mapper, new_class = NULL, remove_class = "list", ...)

Arguments

Value

• bru_mapper() returns a bru_mapper object

Functions

• bru_mapper(): Generic mapper S3 constructor, used for constructing mappers for special objects. See below for details of the default constructor bru_mapper_define() that can be used to define new mappers in user code.

• bru_mapper_define(): Adds the new_class and "bru_mapper" class names to the inheritance list for the input mapper object, unless the object already inherits from these.

  To register mapper classes and methods in scripts, use .S3method() to register the methods, e.g. .S3method("ibm_jacobian", "my_mapper_class", ibm_jacobian.my_mapper_class).

  In packages with Suggests: inlabru, add method information for delayed registration, e.g.:

  #' @rawNamespace S3method(inlabru::bru_get_mapper, inla_rspde)
  #' @rawNamespace S3method(inlabru::ibm_n, bru_mapper_inla_rspde)
  #' @rawNamespace S3method(inlabru::ibm_values, bru_mapper_inla_rspde)
  #' @rawNamespace S3method(inlabru::ibm_jacobian, bru_mapper_inla_rspde)
  

  or before each method, use ⁠@exportS3Method⁠:

  #' @exportS3Method inlabru::bru_get_mapper
  

  etc., which semi-automates it.

See Also

bru_mapper_generics for generic methods, the individual mapper pages for special method implementations, and bru_get_mapper for hooks to extract mappers from latent model object class objects.

Other mappers: bm_aggregate(), bm_collect(), bm_const(), bm_factor(), bm_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

Examples

mapper <- bm_index(5)
ibm_jacobian(mapper, input = c(1, 3, 4, 5, 2))

Mapper for fm_mesh_1d

Description

Create mapper for an fm_mesh_1d object

Usage

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

## S3 method for class 'bm_fm_mesh_1d'
ibm_n(mapper, ...)

## S3 method for class 'bm_fm_mesh_1d'
ibm_values(mapper, ...)

## S3 method for class 'bm_fm_mesh_1d'
ibm_jacobian(mapper, input, ...)

## S3 method for class 'bm_inla_mesh_1d'
ibm_n(mapper, ...)

## S3 method for class 'bm_inla_mesh_1d'
ibm_values(mapper, ...)

## S3 method for class 'bm_inla_mesh_1d'
ibm_jacobian(mapper, input, ...)

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_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_2d(), bru_mapper_generics

Examples

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

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

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

Mapper for fm_mesh_2d

Description

Creates a mapper for 2D fm_mesh_2d objects. Equivalent to calling bm_fmesher().

Usage

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

## S3 method for class 'bm_fm_mesh_2d'
ibm_n(mapper, ...)

## S3 method for class 'bm_fm_mesh_2d'
ibm_values(mapper, ...)

## S3 method for class 'bm_fm_mesh_2d'
ibm_jacobian(mapper, input, ...)

## S3 method for class 'bm_inla_mesh_2d'
ibm_n(mapper, ...)

## S3 method for class 'bm_inla_mesh_2d'
ibm_values(mapper, ...)

## S3 method for class 'bm_inla_mesh_2d'
ibm_jacobian(mapper, input, ...)

Arguments

Value

A bm_fmesher object. Note: Prior to version ⁠2.12.0.9021⁠, this was 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_fmesher(), bm_harmonics(), bm_index(), bm_linear(), bm_logsumexp(), bm_marginal(), bm_matrix(), bm_mesh_B(), bm_multi(), bm_pipe(), bm_repeat(), bm_scale(), bm_shift(), bm_sum(), bm_taylor(), bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper_generics

Examples

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

Generic methods for bru_mapper objects

Description

A bru_mapper sub-class implementation must provide an ibm_jacobian() method. If the model size 'n' and definition values 'values' are stored in the object itself, default methods are available (see Details). Otherwise the ibm_n() and ibm_values() methods also need to be provided.

Usage

ibm_n(mapper, inla_f = FALSE, ...)

ibm_n_output(mapper, input, state = NULL, inla_f = FALSE, ...)

ibm_values(mapper, inla_f = FALSE, ...)

ibm_is_linear(mapper, ...)

ibm_jacobian(mapper, input, state = NULL, inla_f = FALSE, ...)

ibm_linear(mapper, input, state = NULL, ...)

ibm_simplify(mapper, input = NULL, state = NULL, ...)

ibm_eval(mapper, input, state = NULL, ...)

ibm_eval2(mapper, input, state = NULL, ...)

ibm_names(mapper)

ibm_names(mapper) <- value

ibm_inla_subset(mapper, ...)

ibm_invalid_output(mapper, input, state, ...)

## Default S3 method:
ibm_n(mapper, inla_f = FALSE, ...)

## Default S3 method:
ibm_n_output(mapper, input, state = NULL, inla_f = FALSE, ...)

## Default S3 method:
ibm_values(mapper, inla_f = FALSE, ...)

## Default S3 method:
ibm_is_linear(mapper, ...)

## Default S3 method:
ibm_jacobian(mapper, input, state = NULL, ...)

## Default S3 method:
ibm_linear(mapper, input, state, ...)

## Default S3 method:
ibm_simplify(mapper, input = NULL, state = NULL, ...)

## Default S3 method:
ibm_eval(mapper, input, state = NULL, ..., jacobian = NULL)

## Default S3 method:
ibm_eval2(mapper, input, state, ...)

## Default S3 method:
ibm_names(mapper, ...)

## Default S3 method:
ibm_inla_subset(mapper, ...)

## Default S3 method:
ibm_invalid_output(mapper, input, state, ...)

Arguments

Functions

• ibm_n(): Implementations must return the size of the latent vector being mapped to.

• ibm_n_output(): Implementations must return an integer denoting the mapper output length. The default implementation returns NROW(input). Mappers such as bm_multi and bm_collect, that can accept list() inputs require their own methods implementations.

• ibm_values(): When inla_f=TRUE, implementations must return a vector that would be interpretable by an INLA::f(..., values = ...) specification. The exception is the method for bm_multi, that returns a multi-column data frame if multi=TRUE.

• ibm_is_linear(): Implementations must return TRUE or FALSE. If TRUE (returned by the default method unless the mapper contains an is_linear variable), users of the mapper may assume the mapper is linear.

• ibm_jacobian(): Implementations must return a (sparse) matrix of size ibm_n_output(mapper, input, inla_f) by ibm_n(mapper, inla_f = FALSE). The inla_f=TRUE argument should only affect the allowed type of input format.

• ibm_linear(): Implementations must return a bm_taylor object The linearisation information includes offset, jacobian, and state0. The state information indicates for which state the offset was evaluated, with NULL meaning all-zero. The linearised mapper output is defined as

  effect(input, state) =
    offset(input, state0) + jacobian(input, state0) %*% (state - state0)
  

  The default method calls ibm_eval() and ibm_jacobian() to generate the needed information.

• ibm_simplify(): Implementations must return a bru_mapper object. The default method returns ibm_linear(...) for linear mappers, and the original mapper for non-linear mappers.

• ibm_eval(): Implementations must return a vector of length ibm_n_output(...). The input contents must be in a format accepted by ibm_jacobian(...) for the mapper.

• ibm_eval2(): Implementations must return a list with elements offset and jacobian. The input contents must be in a format accepted by ibm_jacobian(...) for the mapper.

• ibm_names(): Implementations must return a character vector of sub-mapper names, or NULL. Intended for providing information about multi-mappers and mapper collections.

• ibm_names(mapper) <- value: Set mapper names.

• ibm_inla_subset(): Implementations must return a logical vector of TRUE/FALSE for the subset such that, given the full A matrix and values output, A[, subset, drop = FALSE] and values[subset] (or values[subset, , drop = FALSE] for data.frame values) are equal to the inla_f = TRUE version of A and values. The default method uses the ibm_values output to construct the subset indexing.

• ibm_invalid_output(): Implementations should return a logical vector of length ibm_n_output(mapper, input, state, ...) indicating which, if any, output elements of ibm_eval(mapper, input, state, ...) are known to be invalid. For for multi/collect mappers, a list, when given a multi=TRUE argument.

• ibm_n(default): Returns a non-null element 'n' from the mapper object, and gives an error if it doesn't exist. If inla_f=TRUE, first checks for a 'n_inla' element.

• ibm_n_output(default): Returns NROW(input)

• ibm_values(default): Returns a non-null element 'values' from the mapper object, and seq_len(ibm_n(mapper)) if it doesn't exist.

• ibm_is_linear(default): Returns logical is_linear from the mapper object if it exists, and otherwise TRUE.

• ibm_jacobian(default): Mapper classes must implement their own ibm_jacobian method.

• ibm_linear(default): Calls ibm_eval() and ibm_jacobian() and returns a bm_taylor object. The state0 information in the affine mapper indicates for which state the offset was evaluated; The affine mapper output is defined as

  effect(input, state) =
    offset(input, state0) + jacobian(input, state0) %*% (state - state0)
  

• ibm_simplify(default): Calls ibm_linear() for linear mappers, and returns the original mapper for non-linear mappers.

• ibm_eval(default): Verifies that the mapper is linear with ibm_is_linear(), and then computes a linear mapping as ibm_jacobian(...) %*% state. When state is NULL, a zero vector of length ibm_n_output(...) is returned.

• ibm_eval2(default): Calls jacobian <- ibm_jacobian(...) and offset <- ibm_eval(..., jacobian = jacobian) and returns a list with elements offset and jacobian, as needed by ibm_linear.default() and similar methods. Mapper classes can implement their own ibm_eval2 method if joint construction of evaluation and Jacobian is more efficient than separate or sequential construction.

• ibm_names(default): Returns NULL

• ibm_inla_subset(default): Uses the ibm_values output to construct the inla subset indexing, passing extra arguments such as multi on to the methods (this means it supports both regular vector values and multi=1 data.frame values).

• ibm_invalid_output(default): Returns an all-FALSE logical vector.

See Also

bru_mapper for constructor methods, and bru_get_mapper for hooks to extract mappers from latent model object class objects.

bru_mapper, bru_get_mapper()

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

Examples

# ibm_names
mapper <- bm_multi(list(A = bm_index(2), B = bm_index(2)))
ibm_names(mapper)
ibm_names(mapper) <- c("new", "names")
ibm_names(mapper)

Create an inlabru model object from model components

Description

The inlabru syntax for model formulae is different from what INLA::inla considers a valid. In inla most of the effects are defined by adding an f(...) expression to the formula. In inlabru the f is replaced by an arbitrary (exceptions: const and offset) string that will determine the label of the effect. See Details for further information.

Usage

bru_model(components, lhoods, options = list(), .envir = parent.frame())

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

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

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

Arguments

Details

For instance

y ~ f(myspde, ...)

in INLA is equivalent to

y ~ myspde(...)

in inlabru.

A disadvantage of the inla way is that there is no clear separation between the name of the covariate and the label of the effect. Furthermore, for some models like SPDE it is much more natural to use spatial coordinates as covariates rather than an index into the SPDE vertices. For this purpose inlabru provides the main argument. For convenience, the main argument can be used like the first argument of the f function, e.g., and is the first argument of the component definition. The INLA model formula

y ~ f(temperature, model = 'linear')

is equivalent to the inlabru component and formula definition

y ~ temperature(temperature, model = 'linear') and y ~ temperature(main = temperature, model = 'linear') as well as y ~ temperature(model = 'linear') which sets main = temperature.

On the other hand, main can also be a function mapping, e.g the sp::coordinates() function:

y ~ mySPDE(coordinates, ...)

This extracts the coordinates from the data object, and maps it to the latent field via the information given in the mapper, which by default is extracted from the model object, in the case of spde model objects.

Morevover, main can be any expression that evaluates within your data as an environment. For instance, if your data has columns 'a' and 'b', you can create a fixed effect of 'sin(a+b)' by setting map in the following way:

y ~ myEffect(sin(a+b))

Value

A bru_model object

Mapper methods for model objects

Description

Methods for the ibm_linear() and ibm_simplify() methods for bru model objects and related classes.

Usage

## S3 method for class 'bru_model'
ibm_linear(mapper, input, state = NULL, ...)

## S3 method for class 'bru_comp_list'
ibm_linear(mapper, input, state = NULL, ...)

## S3 method for class 'bru_comp'
ibm_linear(mapper, input, state = NULL, ...)

## S3 method for class 'bru_model'
ibm_simplify(mapper, input = NULL, state = NULL, ...)

## S3 method for class 'bru_comp'
ibm_simplify(mapper, input = NULL, state = NULL, ...)

## S3 method for class 'bru_comp_list'
ibm_simplify(mapper, input = NULL, state = NULL, ...)

Arguments

Functions

• ibm_linear(bru_model): Returns a list (one element per observation model) of bm_list objects, each with one bm_taylor entry for each included component.

• ibm_simplify(bru_model): Returns a list (one element per observation model) of bm_list objects, each with one bru_mapper entry for each included component.

Observation model construction for usage with bru()

Description

Observation model construction for usage with bru().

Note: Prior to version ⁠2.12.0⁠, this function was called like(), and that alias will remain for a while until examples etc have been updated and users made aware of the change. The name change is to avoid issues with namespace clashes, e.g. with data.table::like(), and also to signal that the function defines observation models, not just likelihood functions.

Usage

bru_obs(
  formula = . ~ .,
  family = "gaussian",
  data = NULL,
  response_data = NULL,
  data_extra = NULL,
  E = NULL,
  Ntrials = NULL,
  weights = NULL,
  scale = NULL,
  domain = NULL,
  samplers = NULL,
  ips = NULL,
  used = NULL,
  allow_combine = NULL,
  aggregate = NULL,
  aggregate_input = NULL,
  control.family = NULL,
  tag = NULL,
  options = list(),
  .envir = parent.frame(),
  include = deprecated(),
  exclude = deprecated(),
  include_latent = deprecated()
)

like(
  formula = . ~ .,
  family = "gaussian",
  data = NULL,
  response_data = NULL,
  E = NULL,
  Ntrials = NULL,
  weights = NULL,
  scale = NULL,
  domain = NULL,
  samplers = NULL,
  ips = NULL,
  used = NULL,
  allow_combine = NULL,
  control.family = NULL,
  tag = NULL,
  options = list(),
  .envir = parent.frame(),
  mesh = deprecated(),
  include = deprecated(),
  exclude = deprecated(),
  include_latent = deprecated()
)

bru_obs_list(...)

## S3 method for class 'list'
bru_obs_list(object, ..., .envir = NULL)

## S3 method for class 'bru_obs_list'
bru_obs_list(..., .envir = NULL)

## S3 method for class 'bru_obs'
c(..., .envir = NULL)

## S3 method for class 'bru_obs_list'
c(..., .envir = NULL)

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

like_list(...)

bru_like_list(...)

Arguments

list(block = .data.[[".block"]],
     weights = .data.[["weight"]],
     n_block = bru_response_size(.response_data.))

Value

A likelihood configuration which can be used to parameterise bru().

Methods (by generic)

• c(bru_obs): Combine several bru_obs objects into a bru_obs_list object

Functions

• like(): Legacy like() method for inlabru prior to version ⁠2.12.0⁠. Use bru_obs() instead.

• bru_obs_list(): Combine bru_obs observation model object into a bru_obs_list object

• bru_obs_list(list): Combine one or more lists of bru_obs observation model objects into a bru_obs_list object

• bru_obs_list(bru_obs_list): Combine a list of bru_obs observation model objects into a bru_obs_list object

• c(bru_obs_list): Combine several bru_obs_list objects into a bru_obs_list object

• like_list(): Backwards compatibility for versions ⁠<= 2.12.0⁠. For later versions, use as_bru_obs_list(), bru_obs_list(), or c().

• bru_like_list(): Backwards compatibility for versions ⁠<= 2.12.0.9017⁠. For later versions, use as_bru_obs_list(), bru_obs_list() or c().

Author(s)

Fabian E. Bachl bachlfab@gmail.com

Finn Lindgren finn.lindgren@gmail.com

See Also

bru_response_size(), bru_used(), bru_comp(), bru_comp_eval()

summary.bru_obs()

Examples

if (bru_safe_inla() &&
    require(ggplot2, quietly = TRUE)) {

  # The 'bru_obs()' (previously 'like()') function's main purpose is to set up
  # observation models, both for single- and multi-likelihood models.
  # The following example generates some random covariates which are observed
  # through two different random effect models with different likelihoods

  # Generate the data

  set.seed(123)

  n1 <- 200
  n2 <- 10

  x1 <- runif(n1)
  x2 <- runif(n2)
  z2 <- runif(n2)

  y1 <- rnorm(n1, mean = 2 * x1 + 3)
  y2 <- rpois(n2, lambda = exp(2 * x2 + z2 + 3))

  df1 <- data.frame(y = y1, x = x1)
  df2 <- data.frame(y = y2, x = x2, z = z2)

  # Single likelihood models and inference using bru are done via

  cmp1 <- y ~ -1 + Intercept(1) + x
  fit1 <- bru(cmp1, family = "gaussian", data = df1)
  summary(fit1)

  cmp2 <- y ~ -1 + Intercept(1) + x + z
  fit2 <- bru(cmp2, family = "poisson", data = df2)
  summary(fit2)

  # A joint model has two likelihoods, which are set up using the bru_obs
  # function

  lik1 <- bru_obs(
    "gaussian",
    formula = y ~ x + Intercept,
    data = df1,
    tag = "norm"
  )
  lik2 <- bru_obs(
    "poisson",
    formula = y ~ x + z + Intercept,
    data = df2,
    tag = "pois"
  )

  # The union of effects of both models gives the components needed to run bru

  jcmp <- ~ x + z + Intercept(1)
  jfit <- bru(jcmp, lik1, lik2)

  bru_index(jfit, "norm")
  bru_index(jfit, "pois")

  # Compare the estimates

  p1 <- ggplot() +
    gg(fit1$summary.fixed, bar = TRUE) +
    ylim(0, 4) +
    ggtitle("Model 1")
  p2 <- ggplot() +
    gg(fit2$summary.fixed, bar = TRUE) +
    ylim(0, 4) +
    ggtitle("Model 2")
  pj <- ggplot() +
    gg(jfit$summary.fixed, bar = TRUE) +
    ylim(0, 4) +
    ggtitle("Joint model")

  multiplot(p1, p2, pj)
}

Utility functions for bru observation model objects

Description

Utility functions for bru observation model objects

Usage

bru_obs_inla_family(x, ...)

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

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

bru_obs_control_family(x, control.family = NULL, ...)

## S3 method for class 'bru_obs'
bru_obs_control_family(x, control.family = NULL, ...)

## S3 method for class 'bru_obs_list'
bru_obs_control_family(x, control.family = NULL, ...)

Arguments

Value

• bru_obs_inla_family() returns a string or vector of strings

• bru_obs_control_family() returns a list with INLA::control.family options, or a list of such lists, with one element per observation model

See Also

summary.bru_obs()

Create or update an options objects

Description

Create a new options object, or merge information from several objects.

The ⁠_get⁠, ⁠_set⁠, and ⁠_reset⁠ functions operate on a global package options override object. In many cases, setting options in specific calls to bru() is recommended instead.

Usage

bru_options(...)

as.bru_options(x = NULL)

bru_options_default()

bru_options_check(options, ignore_null = TRUE)

bru_options_get(name = NULL, include_default = TRUE)

bru_options_set(..., .reset = FALSE)

bru_options_reset()

bru_options_set_local(..., .reset = FALSE, .envir = parent.frame())

Arguments

Value

bru_options() returns a bru_options object.

For as.bru_options(), NULL or no input returns an empty bru_options object, a list is converted via bru_options(...), and bru_options input is passed through. Other types of input generates an error.

bru_options_default() returns an bru_options object containing default options.

bru_options_check() returns a logical; TRUE if the object contains valid options for use by other functions

bru_options_get returns either an bru_options object, for name == NULL, the contents of single option, if name is a options name string, or a named list of option contents, if name is a list of option name strings.

bru_options_set() returns a copy of the global override options, invisibly (as bru_options_get(include_default = FALSE)).

Functions

• as.bru_options(): Coerces inputs to a bru_options object.

• bru_options_default(): Returns the default options.

• bru_options_check(): Checks for valid contents of a bru_options object, and produces warnings for invalid options.

• bru_options_get(): Used to access global package options.

• bru_options_set(): Used to set global package options.

• bru_options_reset(): Clears the global option overrides.

• bru_options_set_local(): Sets local option overrides, that are automatically reset using withr::defer().

Valid options

For bru_options and bru_options_set, recognised options are:

bru_verbose

logical or numeric; if TRUE, log messages of verbosity \le 1 are printed by bru_log_message(). If numeric, log messages of verbosity \lebru_verbose are printed. For line search details, set bru_verbose=2 or 3. Default: 0, to not print any messages

bru_verbose_store

logical or numeric; if TRUE, log messages of verbosity \le 1 are stored by bru_log_message(). If numeric, log messages of verbosity \le are stored. Default: Inf, to store all messages.

bru_run

If TRUE, run inference. Otherwise only return configuration needed to run inference.

bru_max_iter

maximum number of inla iterations, default 10. Also see the bru_method$rel_tol and related options below.

bru_initial

An inla object returned from previous calls of INLA::inla, bru() or lgcp(), or a list of named vectors of starting values for the latent variables. This will be used as a starting point for further improvement of the approximate posterior.

bru_int_args

List of arguments passed all the way to the integration method ipoints and int.polygon for 'cp' family models;

method

"stable" or "direct". For "stable" (default) integration points are aggregated to mesh vertices.

nsub1

Number of integration points per knot interval in 1D. Default 30.

nsub2

Number of integration points along a triangle edge for 2D. Default 9.

nsub

Deprecated parameter that overrides nsub1 and nsub2 if set. Default NULL.

bru_method

List of arguments controlling the iterative inlabru method:

taylor

'pandemic' (default, from version 2.1.15).

search

Either 'all' (default), to use all available line search methods, or one or more of

'finite'

(reduce step size until predictor is finite)

'contract'

(decrease step size until trust hypersphere reached)

'expand'

(increase step size until no improvement)

'optimise'

(fast approximate error norm minimisation)

To disable line search, set to an empty vector. Line search is not available for taylor="legacy".

factor

Numeric, > 1 determining the line search step scaling multiplier. Default (1 + \sqrt{5})/2.

rel_tol

Stop the iterations when the largest change in linearisation point (the conditional latent state mode) in relation to the estimated posterior standard deviation is less than rel_tol. Default 0.1 (ten percent).

max_step

The largest allowed line search step factor. Factor 1 is the full INLA step. Default is 2.

line_opt_method

Which method to use for the line search optimisation step. Default "onestep", using a quadratic approximation based on the value and gradient at zero, and the value at the current best step length guess. The method "full" does line optimisation on the full nonlinear predictor; this is slow and intended for debugging purposes only.

bru_compress_cp

logical; when TRUE, compress the \sum_{i=1}^n \eta_i part of the Poisson process likelihood (family="cp") into a single term, with y=n, and predictor mean(eta). Default: TRUE

bru_debug

logical; when TRUE, activate temporary debug features for package development. Default: FALSE

inla() options

All options not starting with bru_ are passed on to inla(), sometimes after altering according to the needs of the inlabru method. Warning: Due to how inlabru currently constructs the inla() call, the mean, prec, mean.intercept, and prec.intercept settings in control.fixed will have no effect. Until a more elegant alternative has been implemented, use explicit mean.linear and prec.linear specifications in each model="linear" component instead.

See Also

bru_options(), bru_options_default(), bru_options_get()

Examples

## Not run: 
if (interactive()) {
  # Combine global and user options:
  options1 <- bru_options(bru_options_get(), bru_verbose = TRUE)
  # Create a proto-options object in two equivalent ways:
  options2 <- as.bru_options(bru_verbose = TRUE)
  options2 <- as.bru_options(list(bru_verbose = TRUE))
  # Combine options objects:
  options3 <- bru_options(options1, options2)
}

## End(Not run)
## Not run: 
if (interactive()) {
  bru_options_check(bru_options(bru_max_iter = "text"))
}

## End(Not run)
bru_options_get("bru_verbose")
## Not run: 
if (interactive()) {
  bru_options_set(
    bru_verbose = TRUE,
    verbose = TRUE
  )
}

## End(Not run)
my_fun <- function(val) {
  bru_options_set_local(bru_verbose = val)
  bru_options_get("bru_verbose")
}
# Inside the function, the bru_verbose option is changed.
# Outside the function, the bru_verbose option is unchanged.
print(my_fun(TRUE))
print(bru_options_get("bru_verbose"))
print(my_fun(FALSE))
print(bru_options_get("bru_verbose"))

Response size queries

Description

Extract the number of response values from bru and related objects.

Usage

bru_response_size(object)

## Default S3 method:
bru_response_size(object)

## S3 method for class 'inla.surv'
bru_response_size(object)

## S3 method for class 'bru_obs'
bru_response_size(object)

## S3 method for class 'bru_obs_list'
bru_response_size(object)

## S3 method for class 'bru_info'
bru_response_size(object)

## S3 method for class 'bru'
bru_response_size(object)

Arguments

Value

An integer vector.

Methods (by class)

• bru_response_size(default): Extract the number of observations from an object supporting NROW().

• bru_response_size(inla.surv): Extract the number of observations from an inla.surv object.

• bru_response_size(bru_obs): Extract the number of observations from a bru_obs object.

• bru_response_size(bru_obs_list): Extract the number of observations from a bru_obs_list object, as a vector with one value per observation model.

• bru_response_size(bru_info): Extract the number of observations from a bru_info object, as a vector with one value per observation model.

• bru_response_size(bru): Extract the number of observations from a bru object, as a vector with one value per observation model.

See Also

like()

Examples

bru_response_size(
  bru_obs(y ~ 1, data = data.frame(y = rnorm(10)), family = "gaussian")
)

Load INLA safely for examples and tests

Description

Loads the INLA package with requireNamespace("INLA", quietly = TRUE), and optionally checks and sets the multicore num.threads INLA option.

Usage

bru_safe_inla(multicore = NULL, quietly = FALSE, minimum_version = "23.1.31")

Arguments

Value

logical; TRUE if INLA was loaded safely, otherwise FALSE

Examples

## Not run: 
if (bru_safe_inla()) {
  # Run inla dependent calculations
}

## End(Not run)

Check for potential sp version compatibility issues

Description

Loads the sp package with requireNamespace("sp", quietly = TRUE), and checks and optionally sets the sp evolution status flag if rgdal is unavailable.

Usage

bru_safe_sp(quietly = FALSE, force = FALSE, minimum_version = "1.4-5")

Arguments

Value

Returns (invisibly) FALSE if a potential issue is detected, and give a message if quietly is FALSE. Otherwise returns TRUE

Examples

## Not run: 
if (bru_safe_sp() &&
  require("sp")) {
  # Run sp dependent calculations
}

## End(Not run)

Set missing values in observation models

Description

Set all or parts of the observation model response data to NA, for example for use in cross validation (with bru_rerun()) or prior sampling (with bru_rerun() and generate()).

Usage

bru_set_missing(object, keep = FALSE, ...)

## S3 method for class 'bru'
bru_set_missing(object, keep = FALSE, ...)

## S3 method for class 'bru_obs_list'
bru_set_missing(object, keep = FALSE, ...)

## S3 method for class 'bru_obs'
bru_set_missing(object, keep = FALSE, ...)

Arguments

Details

For bru and bru_obs_list,

• keep must be either a single logical, which is expanded to a list,

• a logical vector, which is converted to a list,

• an unnamed list of the same length as the number of observation models, with elements compatible with the bru_obs method, or

• a named list with elements compatible with the bru_obs method, and only the named bro_obs models are acted upon, i.e. the elements not present in the list are treated as keep = TRUE.

E.g.: keep = list(b = FALSE) sets all observations in model b to missing, and does not change model a.

E.g.: keep = list(a = 1:4, b = -(3:5)) keeps only observations 1:4 of model a, marking the rest as missing, and sets observations 3:5 of model b to missing.

Examples

obs <- c(
  A = bru_obs(y_A ~ ., data = data.frame(y_A = 1:6)),
  B = bru_obs(y_B ~ ., data = data.frame(y_B = 11:15))
)
bru_response_size(obs)
lapply(
  bru_set_missing(obs, keep = FALSE),
  function(x) {
    x[["response_data"]][["BRU_response"]]
  }
)
lapply(
  bru_set_missing(obs, keep = list(B = FALSE)),
  function(x) {
    x[["response_data"]][["BRU_response"]]
  }
)
lapply(
  bru_set_missing(obs, keep = list(1:4, -(3:5))),
  function(x) {
    x[["response_data"]][["BRU_response"]]
  }
)

Standardise inla hyperparameter names

Description

The inla hyperparameter output uses parameter names that can include whitespace and special characters. This function replaces those characters with underscores.

Usage

bru_standardise_names(x)

Arguments

Value

A character vector with standardised names

Examples

bru_standardise_names("Precision for the Gaussian observations")

Summarise and annotate data

Description

Summarise and annotate data

Usage

bru_summarise(
  data,
  probs = c(0.025, 0.5, 0.975),
  x = NULL,
  cbind.only = FALSE,
  max_moment = 2
)

Arguments

Value

A data.frame or ⁠Spatial[Points/Pixels]DataFrame⁠ with summary statistics, "mean", "sd", paste0("q", probs), "mean.mc_std_err", "sd.mc_std_err"

Examples

bru_summarise(matrix(rexp(10000), 10, 1000), max_moment = 4, probs = NULL)

Extract timing information from fitted bru object

Description

Extracts a data.frame or tibble with information about the Time (CPU), System, and Elapsed time for each step of a bru() run.

Usage

bru_timings(object, ...)

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

Arguments

Plot inlabru iteration timings

Description

Draws the time per iteration for preprocessing (including linearisation), inla() calls, and line search. Iteration 0 is the time used for defining the model structure.

Usage

bru_timings_plot(x)

Arguments

Details

Requires the "ggplot2" package to be installed.

Examples

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

## End(Not run)

Transformation tools

Description

Tools for transforming between N(0,1) variables and other distributions in predictor expressions

Usage

bru_forward_transformation(qfun, x, ..., tail.split. = 0)

bru_inverse_transformation(pfun, x, ..., tail.split. = NULL)

Arguments

Value

• For bru_forward_transformation, a numeric vector

• For bru_inverse_transformation, a numeric vector

Examples

u <- rnorm(5, 0, 1)
y <- bru_forward_transformation(qexp, u, rate = 2)
v <- bru_inverse_transformation(pexp, y, rate = 2)
rbind(u, y, v)

List components used in a model

Description

Create or extract information about which components are used by a model, or its individual observation models. If a non-NULL labels argument is supplied, also calls bru_used_update() on the bru_used objects.

Usage

bru_used(x = NULL, ...)

## S3 method for class ''NULL''
bru_used(
  x = NULL,
  ...,
  effect = NULL,
  effect_exclude = NULL,
  latent = NULL,
  labels = NULL
)

## S3 method for class 'character'
bru_used(
  x,
  ...,
  effect = NULL,
  effect_exclude = NULL,
  latent = NULL,
  labels = NULL
)

## S3 method for class 'expression'
bru_used(
  x,
  ...,
  effect = NULL,
  effect_exclude = NULL,
  latent = NULL,
  labels = NULL
)

## S3 method for class 'formula'
bru_used(
  x,
  ...,
  effect = NULL,
  effect_exclude = NULL,
  latent = NULL,
  labels = NULL
)

## S3 method for class 'bru'
bru_used(x, ..., join = TRUE)

## S3 method for class 'list'
bru_used(x, ..., join = TRUE)

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

## S3 method for class 'bru_used'
bru_used(x, labels = NULL, ...)

## S3 method for class 'bru_used'
format(x, ...)

## S3 method for class 'bru_used'
summary(object, ...)

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

Arguments

Details

The arguments effect, effect_exclude, and latent control what components and effects are available for use in predictor expressions.

effect

Character vector of component labels that are used as effects by the predictor expression; If NULL (default), the names are extracted from the formula.

exclude

Character vector of component labels to be excluded from the effect list even if they have been auto-detected as being necessary. Default is NULL; do not remove any components from the inclusion list.

include_latent

Character vector. Specifies which latent state variables need to be directly available to the predictor expression, with a ⁠_latent⁠ suffix. This also makes evaluator functions with suffix ⁠_eval⁠ available, taking parameters main, group, and replicate, taking values for where to evaluate the component effect that are different than those defined in the component definition itself (see bru_comp_eval()). If NULL, the use of ⁠_latent⁠ and ⁠_eval⁠ in the predictor expression is detected automatically.

Value

A bru_used object (a list with elements effect and latent), or a list of such objects (for methods with join = FALSE)

Methods (by class)

• bru_used(`NULL`): Create a bru_used object from effect name character vectors.

• bru_used(character): Create a bru_used object from a character representation of an expression.

• bru_used(expression): Create a bru_used object from an expression object.

• bru_used(formula): Create a bru_used object from a formula (only the right-hand side is used).

• bru_used(bru): Extract the bru_used information for the collection of observation models used in a bru object.

• bru_used(list): Extract the bru_used information for each element of a list, and optionally join into a single bru_used object.

• bru_used(bru_obs): Extract the bru_used information for the collection of observation models used in a bru observation model bru_obs object.

• bru_used(bru_used): Convenience method that takes an existing bru_used object and calls bru_used_update() if labels is non-NULL.

Methods (by generic)

• format(bru_used): Text formatting method for bru_used objects.

• summary(bru_used): Summary method for bru_used objects.

• print(bru_used): Print method for bru_used objects.

See Also

Other bru_used: bru_used_update(), bru_used_vars()

Examples

(used <- bru_used(~.))
bru_used(used, labels = c("a", "c"))
(used <- bru_used(~ a + b + c_latent + d_latent))
bru_used(used, labels = c("a", "c"))
(used <- bru_used(expression(a + b + c_latent + d_latent)))
bru_used(used, labels = c("a", "c"))

Update used_component information objects

Description

Merge available component labels information with used components information.

Usage

bru_used_update(x, labels, ...)

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

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

## S3 method for class 'bru_used'
bru_used_update(x, labels, ...)

Arguments

Value

An updated version of x

See Also

Other bru_used: bru_used(), bru_used_vars()

Extract basic variable names from expression

Description

Extracts the variable names from an R expression by pre- and post-processing around all.vars(). First replaces $ with [[ indexing, so that internal column/variable names are ignored, then calls all.vars().

Usage

bru_used_vars(x, functions = FALSE)

## S3 method for class 'character'
bru_used_vars(x, functions = FALSE)

## S3 method for class 'expression'
bru_used_vars(x, functions = FALSE)

## S3 method for class 'formula'
bru_used_vars(x, functions = FALSE)

Arguments

Value

If successful, a character vector, otherwise NULL

Methods (by class)

• bru_used_vars(formula): Only the right-hand side is used.

See Also

Other bru_used: bru_used(), bru_used_update()

Examples

bru_used_vars(~.)
bru_used_vars(~ a + b + c_latent + d_eval())
bru_used_vars(expression(a + b + c_latent + d_eval()))

bru_used_vars(~., functions = TRUE)
bru_used_vars(~ a + b + c_latent + d_eval(), functions = TRUE)
bru_used_vars(expression(a + b + c_latent + d_eval()), functions = TRUE)

bru_used_vars(a ~ b)
bru_used_vars(expression(a ~ b))

Summarise DIC and WAIC from lgcp objects.

Description

Calculates DIC and/or WAIC differences and produces an ordered summary.

Usage

deltaIC(..., criterion = "DIC")

Arguments

Value

A data frame with each row containing the Model name, DIC and Delta.DIC, and/or WAIC and Delta.WAIC.

Examples

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

  # Fit two models
  fit1 <- bru(
    y ~ x,
    family = "poisson",
    data = input.df,
    options = list(control.compute = list(dic = TRUE))
  )
  fit2 <- bru(
    y ~ x + rand(idx, model = "iid"),
    family = "poisson",
    data = input.df,
    options = list(control.compute = list(dic = TRUE))
  )

  # Compare DIC

  deltaIC(fit1, fit2)
}

Variance and correlations measures for prediction components

Description

Calculates local and integrated variance and correlation measures as introduced by Yuan et al. (2017).

Usage

devel.cvmeasure(joint, prediction1, prediction2, samplers = NULL, mesh = NULL)

Arguments

Value

Variance and correlations measures.

References

Y. Yuan, F. E. Bachl, F. Lindgren, D. L. Brochers, J. B. Illian, S. T. Buckland, H. Rue, T. Gerrodette. 2017. Point process models for spatio-temporal distance sampling data from a large-scale survey of blue whales. https://arxiv.org/abs/1604.06013

Examples

if (bru_safe_inla() &&
  require("ggplot2", quietly = TRUE) &&
  require("patchwork", quietly = TRUE) &&
  require("sn", quietly = TRUE) &&
  require("terra", quietly = TRUE) &&
  require("sf", quietly = TRUE) &&
  require("RColorBrewer", quietly = TRUE) &&
  require("dplyr", quietly = TRUE) &&
  require("magrittr", quietly = TRUE)) {
  # Load Gorilla data

  gorillas <- gorillas_sf
  gorillas$gcov <- gorillas_sf_gcov()

  # Use RColorBrewer

  # Fit a model with two components:
  # 1) A spatial smooth SPDE
  # 2) A spatial covariate effect (vegetation)

  pcmatern <- INLA::inla.spde2.pcmatern(
    gorillas$mesh,
    prior.sigma = c(0.1, 0.01),
    prior.range = c(0.01, 0.01)
  )

  cmp <- geometry ~ 0 +
    vegetation(gorillas$gcov$vegetation, model = "factor_contrast") +
    spde(geometry, model = pcmatern) -
    Intercept(1)

  fit <- lgcp(
    cmp,
    gorillas$nests,
    samplers = gorillas$boundary,
    domain = list(geometry = gorillas$mesh),
    options = list(control.inla = list(int.strategy = "eb"))
  )

  # Predict SPDE and vegetation at a grid covering the domain of interest
  pred_loc <- fm_pixels(
    gorillas$mesh,
    mask = gorillas$boundary,
    dims = c(200, 200),
    format = "sf"
  )
  pred <- predict(
    fit,
    pred_loc,
    ~ list(
      joint = spde + vegetation,
      field = spde,
      veg = vegetation
    )
  )

  pred_collect <-
    rbind(
      pred$joint %>% dplyr::mutate(component = "joint"),
      pred$field %>% dplyr::mutate(component = "field"),
      pred$veg %>% dplyr::mutate(component = "veg")
    ) %>%
    dplyr::mutate(var = sd^2)

  # Plot component mean

  ggplot(pred_collect) +
    geom_tile(aes(geometry = geometry, fill = mean), stat = "sf_coordinates") +
    coord_equal() +
    facet_wrap(~component, nrow = 1) +
    theme(legend.position = "bottom")

  # Plot component variance

  ggplot(pred_collect) +
    geom_tile(aes(geometry = geometry, fill = var), stat = "sf_coordinates") +
    coord_equal() +
    facet_wrap(~component, nrow = 1) +
    theme(legend.position = "bottom")

  # Calculate variance and correlation measure

  vm <- devel.cvmeasure(pred$joint, pred$field, pred$veg)
  # Compute nominal relative variance contributions; note that these can be
  # greater than 100%!
  vm <- dplyr::mutate(
    vm,
    var1_rel = if_else(var1 <= 0, NA, var1 / var.joint),
    var2_rel = if_else(var2 <= 0, NA, var2 / var.joint)
  )
  lprange <- range(vm$var.joint, vm$var1, vm$var2)
  vm <- tidyr::pivot_longer(vm,
    cols = c(var.joint, var1, var2, cov, cor, var1_rel, var2_rel),
    names_to = "component",
    values_to = "value"
  )

  # Variance contribution of the components

  csc <- scale_fill_gradientn(
    colours = brewer.pal(9, "YlOrRd"),
    limits = lprange
  )

  vm_ <- dplyr::filter(vm, component %in% c("var.joint", "var1", "var2"))
  ggplot(vm_) +
    geom_tile(aes(geometry = geometry, fill = value),
      stat = "sf_coordinates"
    ) +
    csc +
    coord_equal() +
    facet_wrap(~component, nrow = 1) +
    theme(legend.position = "bottom")

  # Relative variance contribution of the components
  # When bo

  vm_ <- dplyr::filter(vm, component %in% c("var1_rel", "var2_rel"))
  ggplot(vm_) +
    geom_tile(aes(geometry = geometry, fill = value),
      stat = "sf_coordinates"
    ) +
    scale_fill_gradientn(
      colours = brewer.pal(9, "YlOrRd"),
      trans = "log"
    ) +
    coord_equal() +
    facet_wrap(~component, nrow = 1)

  # Where both relative contributions are larger than 1, the posterior
  # correlations are strongly negative.

  # Covariance and correlation of field and vegetation

  vm_cov <- dplyr::filter(vm, component %in% "cov")
  vm_cor <- dplyr::filter(vm, component %in% "cor")
  (ggplot(vm_cov) +
    geom_tile(aes(geometry = geometry, fill = value),
      stat = "sf_coordinates"
    ) +
    scale_fill_gradientn(
      colours = rev(brewer.pal(9, "RdBu")),
      limits = c(-1, 1) * max(abs(vm_cov$value), na.rm = TRUE)
    ) +
    coord_equal() +
    theme(legend.position = "bottom") +
    ggtitle("Covariances") |
    ggplot(vm_cor) +
      geom_tile(aes(geometry = geometry, fill = value),
        stat = "sf_coordinates"
      ) +
      scale_fill_gradientn(
        colours = rev(brewer.pal(9, "RdBu")),
        limits = c(-1, 1) * max(abs(vm_cor$value), na.rm = TRUE)
      ) +
      coord_equal() +
      theme(legend.position = "bottom") +
      ggtitle("Correlations")
  )

  # Variance and correlation integrated over space

  vrt <- fm_vertices(gorillas$mesh, format = "sf")
  pred_vrt <- predict(
    fit,
    vrt,
    ~ list(
      joint = spde + vegetation,
      field = spde,
      veg = vegetation
    )
  )

  vm.int <- devel.cvmeasure(
    pred_vrt$joint,
    pred_vrt$field,
    pred_vrt$veg,
    samplers = fm_int(gorillas$mesh, gorillas$boundary),
    mesh = gorillas$mesh
  )
  vm.int
}

Evaluate spatial covariates

Description

Evaluate spatial covariates

Usage

eval_spatial(data, where, layer = NULL, selector = NULL)

## S3 method for class 'SpatialPolygonsDataFrame'
eval_spatial(data, where, layer = NULL, selector = NULL)

## S3 method for class 'SpatialPixelsDataFrame'
eval_spatial(data, where, layer = NULL, selector = NULL)

## S3 method for class 'SpatialGridDataFrame'
eval_spatial(data, where, layer = NULL, selector = NULL)

## S3 method for class 'sf'
eval_spatial(data, where, layer = NULL, selector = NULL)

## S3 method for class 'SpatRaster'
eval_spatial(data, where, layer = NULL, selector = NULL)

## S3 method for class 'stars'
eval_spatial(data, where, layer = NULL, selector = NULL)

Arguments

Methods (by class)

• eval_spatial(SpatialPolygonsDataFrame): Compatibility wrapper for eval_spatial.sf

• eval_spatial(sf): Supports point-in-polygon information lookup. Other combinations are untested.

Evaluate a component effect

Description

Calculate latent component effects given some data and the state of the component's internal random variables.

Usage

evaluate_effect_single_state(...)

## S3 method for class 'bru_mapper'
evaluate_effect_single_state(component, input, state, ..., label = NULL)

## S3 method for class 'bm_list'
evaluate_effect_single_state(components, input, state, ...)

## S3 method for class 'bru_comp_list'
evaluate_effect_single_state(components, input, state, ...)

Arguments

Value

• evaluate_effect_single_state.bm_list: A list of evaluated component effect values

Author(s)

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

Evaluate or sample from a posterior result given a model and locations

Description

Evaluate or sample from a posterior result given a model and locations

Usage

evaluate_model(
  model,
  state,
  data = NULL,
  data_extra = NULL,
  input = NULL,
  comp_simple = NULL,
  predictor = NULL,
  format = NULL,
  used = NULL,
  n_pred = NULL,
  ...
)

evaluate_state(
  model,
  result,
  property = "mode",
  n = 1,
  seed = 0L,
  num.threads = NULL,
  internal_hyperpar = FALSE,
  ...
)

Arguments

Details

• evaluate_model is a wrapper to evaluate model state, A-matrices, effects, and predictor, all in one call.

• evaluate_state evaluates model state properties or samples

Evaluate component effects or expressions

Description

Evaluate component effects or expressions, based on a bru model and one or several states of the latent variables and hyperparameters.

Usage

evaluate_predictor(
  model,
  state,
  data,
  data_extra,
  effects,
  predictor,
  used = NULL,
  format = "auto",
  n_pred = NULL
)

Arguments

Details

For each component, e.g. "name", the state values are available as name_latent, and arbitrary evaluation can be done with name_eval(...), see bru_comp_eval().

Value

A list or matrix is returned, as specified by format

Expand labels

Description

Expand labels

Usage

expand_labels(labels, expand, suffix)

Arguments

Value

a vector of labels with suffix appended to the selected labels

Extract a summary property from all results of an inla result

Description

Extract a summary property from all results of an inla result

Usage

extract_property(result, property, internal_hyperpar = FALSE)

Arguments

Value

named list for each estimated fixed effect coefficient, random effect vector, and hyperparameter. The hyperparameter names are standardised with bru_standardise_names()

Summarise component inputs

Description

Summarise component inputs

Usage

## S3 method for class 'bru_input'
format(x, verbose = TRUE, ..., label.override = NULL, type = NULL)

## S3 method for class 'bru_input'
summary(object, verbose = TRUE, ..., label.override = NULL)

## S3 method for class 'bru_input'
print(x, verbose = TRUE, ..., label.override = NULL)

Arguments

Author(s)

Fabian E. Bachl bachlfab@gmail.com

Finn Lindgren finn.lindgren@gmail.com

See Also

bru_input(), bru_comp()