Package 'inlabru'

Description

Convenient model fitting using (iterated) INLA.

Details

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

The main function for inference using inlabru is bru(). The general model specification details is documented in component() and like(). 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(..., like(model="cp", ...)).

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

Author(s)

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

See Also

Useful links:

• http://www.inlabru.org

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

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

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

Description

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)) {
  # 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")
  mdl <- x ~ spde1D(x, model = inla.spde2.matern(mesh1D)) + Intercept(1)
  fit.spde <- lgcp(mdl, pts2, domain = list(x = c(0, 55)))

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


  # Plot them!
  attributes(bc)$ggp
}

## End(Not run)

Description

bru_mapper lists can be combined into bm_list lists.

Usage

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

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

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

Arguments

Value

A bm_list object

Methods (by generic)

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

• [: Extract sub-list

Functions

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

Examples

m <- c(A = bru_mapper_const(), B = bru_mapper_scale())
str(m)
str(m[2])

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

Arguments

Details

• bru_rerun Continue the optimisation from a previously computed estimate.

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.

Author(s)

Fabian E. Bachl [email protected]

Examples

if (bru_safe_inla(multicore = FALSE)) {

  # 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, family = "gaussian", data = input.df)

  # Obtain summary
  fit$summary.fixed
}


if (bru_safe_inla(multicore = FALSE)) {

  # Alternatively, we can use the like() function to construct the likelihood:

  lik <- like(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 like()'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(multicore = FALSE)) {
  z <- 2
  input.df <- within(input.df, y <- 5 + exp(z) * x + rnorm(10, mean = 0, sd = 0.1))
  lik <- like(
    family = "gaussian", data = input.df,
    formula = y ~ exp(z) * x + Intercept
  )
  fit <- bru(~ z(1) + Intercept(1), lik)

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

Description

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 [email protected]

Examples

opts <- bru_call_options()

# Print them:
opts

Description

Compute inlabru model linearisation information

Usage

bru_compute_linearisation(...)

## S3 method for class 'component'
bru_compute_linearisation(
  cmp,
  model,
  lhood_expr,
  data,
  input,
  state,
  comp_simple,
  effects,
  pred0,
  used,
  allow_latent,
  allow_combine,
  eps,
  ...
)

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

## S3 method for class 'bru_like_list'
bru_compute_linearisation(
  lhoods,
  model,
  input,
  state,
  comp_simple,
  eps = 0.00001,
  ...
)

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

Arguments

Description

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

Usage

bru_convergence_plot(x, from = 1, to = 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)

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)

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)

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

Details

• bru_get_mapper.inla.spde extract an indexed mapper for the model$mesh object contained in the model object. It returns NULL gives a warning if no known mesh type is found in the model object.

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

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

Value

A bru_mapper object defined by the model component

See Also

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

Other mappers: bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

Description

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

• 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)
print(bru_log(), timestamp = TRUE, verbosity = TRUE)

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

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
)

Arguments

Value

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

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() {
    local_bru_options_set(
      # 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"])
}

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)

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

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)

Description

Constructors for bru_mapper objects

Usage

bru_mapper(...)

bru_mapper_define(mapper, new_class = NULL, ..., methods = deprecated())

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: bru_get_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

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

bru_mapper_aggregate(rescale = FALSE, n_block = NULL)

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

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

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

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

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

Arguments

Details

• For bru_mapper_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: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

Description

Constructs a concatenated collection mapping

Usage

bru_mapper_collect(mappers, hidden = FALSE)

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

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

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

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

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

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

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

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

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

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

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

Arguments

Details

• ibm_jacobian for bru_mapper_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.bru_mapper_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 for bru_mapper_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.bru_mapper_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.

Value

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

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

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

Description

Create a constant mapper

Usage

bru_mapper_const()

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

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

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

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

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

Description

Create a factor mapper

Usage

bru_mapper_factor(values, factor_mapping, indexed = FALSE)

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

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

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

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

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

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

## 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 bru_mapper_multi and bru_mapper_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 bru_mapper_multi, that returns a multi-column data frame.

• 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 bru_mapper_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 bru_mapper_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: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

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 = bru_mapper_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 = bru_mapper_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

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

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

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

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

Description

Create a an indexing mapper

Usage

bru_mapper_index(n = 1L, ...)

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

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

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

Description

Create a mapper for linear effects

Usage

bru_mapper_linear()

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

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

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

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

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

bru_mapper_logsumexp(rescale = FALSE, n_block = NULL)

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

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

Arguments

Details

• For bru_mapper_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.

Methods (by generic)

• ibm_eval(bru_mapper_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: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

Description

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

Usage

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

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

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

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

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

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

Arguments

Details

For bru_mapper_marginal, non-NULL input values are interpreted as a parameter list for qfun, overriding that of the mapper itself.

Methods (by generic)

• ibm_eval(bru_mapper_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: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

Description

Create a matrix mapper, for a given number of columns

Usage

bru_mapper_matrix(labels)

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

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

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

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

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

Description

Creates a mapper for handling basis conversions

Usage

bru_mapper_mesh_B(mesh, B)

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

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

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

Arguments

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Description

Constructs a rowwise Kronecker product mapping

Usage

bru_mapper_multi(mappers)

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

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

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

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

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

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

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

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

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

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

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

Arguments

Details

• ibm_jacobian for bru_mapper_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.bru_mapper_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 for bru_mapper_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.bru_mapper_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.

Value

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

Methods (by generic)

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

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

Description

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

Usage

bru_mapper_pipe(mappers)

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

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

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

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

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

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

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

Arguments

Methods (by generic)

• ibm_simplify(bru_mapper_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 bru_mapper_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: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

m <- bru_mapper_pipe(list(
  scale = bru_mapper_scale(),
  shift = bru_mapper_shift()
))
ibm_eval2(m, input = list(scale = 2, shift = 1:4), state = 1:4)

Description

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

Usage

bru_mapper_scale(mapper = NULL)

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

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

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

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

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

Arguments

Details

For bru_mapper_scale, input NULL values are interpreted as no scaling.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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

Description

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

Usage

bru_mapper_shift(mapper = NULL)

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

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

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

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

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

Arguments

Details

For bru_mapper_shift, input NULL values are interpreted as no shift.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_taylor()

Examples

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

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

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

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

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

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

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

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

Arguments

Details

• The ibm_eval.bru_mapper_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: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift()

Examples

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

Description

Create mapper for an fm_mesh_1d object

Usage

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

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

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

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

## S3 method for class 'inla.mesh.1d'
bru_mapper(mesh, indexed = NULL, ...)

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

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

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

Arguments

Functions

• bru_mapper(inla.mesh.1d): Create mapper for an inla.mesh.1d object; converts the mesh fo fm_mesh_1d first.

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_2d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

Examples

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)), indexed = TRUE)
ibm_values(m)
ibm_eval(m, 1:7, 1:5)

Description

Creates a mapper for 2D fm_mesh_2d objects

Usage

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

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

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

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

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

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

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

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

Arguments

Functions

• bru_mapper(inla.mesh): Creates a mapper for 2D inla.mesh objects

See Also

bru_mapper, bru_mapper_generics

Other mappers: bru_get_mapper(), bru_mapper(), bru_mapper.fm_mesh_1d(), bru_mapper_aggregate(), bru_mapper_collect(), bru_mapper_const(), bru_mapper_factor(), bru_mapper_generics, bru_mapper_harmonics(), bru_mapper_index(), bru_mapper_linear(), bru_mapper_logsumexp(), bru_mapper_marginal(), bru_mapper_matrix(), bru_mapper_mesh_B(), bru_mapper_multi(), bru_mapper_pipe(), bru_mapper_scale(), bru_mapper_shift(), bru_mapper_taylor()

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

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

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.

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 $\le$bru_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)

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)

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)

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

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

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)

Description

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

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

Usage

component(...)

## S3 method for class 'character'
component(
  object,
  main = NULL,
  weights = NULL,
  ...,
  model = NULL,
  mapper = NULL,
  main_layer = NULL,
  main_selector = NULL,
  n = NULL,
  values = NULL,
  season.length = NULL,
  copy = NULL,
  weights_layer = NULL,
  weights_selector = NULL,
  group = 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 down 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 component.character method is inlabru's equivalent to INLA's f function but adds functionality that is unique to inlabru.

Deprecated parameters:

• map: Use main instead.

• mesh: Use mapper instead.

Naming random effects

In INLA, 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$