bru_mapper: Constructors for `bru_mapper` objects

Description

Constructors for bru_mapper objects

Usage

bru_mapper(...)
bru_mapper_define(mapper, new_class = NULL, ..., methods = NULL)
# S3 method for default
bru_mapper(...)
# S3 method for inla.mesh
bru_mapper(mesh, ...)
# S3 method for inla.mesh.1d
bru_mapper(mesh, indexed = NULL, ...)
bru_mapper_index(n = 1L, ...)
bru_mapper_taylor(
  offset = NULL,
  jacobian = NULL,
  state0 = NULL,
  ...,
  values_mapper = NULL
)
bru_mapper_linear(...)
bru_mapper_matrix(labels, ...)
bru_mapper_factor(values, factor_mapping, indexed = FALSE, ...)
bru_mapper_const(...)
bru_mapper_scale(mapper = NULL, ...)
bru_mapper_aggregate(rescale = FALSE, n_block = NULL, ...)
bru_mapper_logsumexp(rescale = FALSE, n_block = NULL, ...)
bru_mapper_pipe(mappers, ...)
bru_mapper_multi(mappers, ...)
bru_mapper_collect(mappers, hidden = FALSE, ...)
bru_mapper_harmonics(
  order = 1,
  scaling = 1,
  intercept = TRUE,
  interval = c(0, 1),
  ...
)
bru_mapper_mesh_B(mesh, B, ...)

Arguments

...

Deprecated, alternative way to supply optional method definitions.

mapper

For bru_mapper_define, a prototype mapper object, see Details. For bru_mapper_scale, a mapper to be scaled.

new_class

If non-NULL, this is added at the front of the class definition

methods

Deprecated.

mesh

An inla.mesh.1d or inla.mesh.2d object to use as a mapper

indexed

logical; if TRUE, the ibm_values() method will return an integer vector instead of the factor levels. This is needed e.g. for group and replicate mappers, since INLA::f() doesn't accept factor values. Default: FALSE, which works for the main input mappers. The default mapper constructions will set it the required setting.

n

Size of a model for bru_mapper_index

offset

For bru_mapper_taylor, an offset vector evaluated at state0. May be NULL, interpreted as an all-zero vector of length determined by a non-null Jacobian.

jacobian

For bru_mapper_taylor, the Jacobian matrix, evaluated at state0, or, a named list of such matrices. May be NULL or an empty list, for a constant mapping.

state0

For bru_mapper_taylor, the state the linearisation was evaluated at, or a list of length matching the jacobian list. NULL is interpreted as 0.

values_mapper

mapper object to be used for ibm_n and ibm_values for inla_f=TRUE (experimental, currently unused)

labels

Column labels for matrix mappings

values

Input values calculated by input_eval.bru_input()

factor_mapping

character; selects the type of factor mapping.

'contrast' for leaving out the first factor level.
'full' for keeping all levels.

rescale

logical; For bru_mapper_aggregate and bru_mapper_logsumexp, specifies if the blockwise sums should be normalised by the blockwise weight sums or not:

FALSE: (default) Straight weighted sum, no rescaling.
TRUE: Divide by the sum of the weight values within each block. This is useful for integration averages, when the given weights are plain integration weights. If the weights are NULL or all ones, this is the same as dividing by the number of entries in each block.

n_block

Predetermined number of output blocks. If NULL, overrides the maximum block index in the inputs.

mappers

A list of bru_mapper objects

hidden

logical, set to TRUE to flag that the mapper is to be used as a first level input mapper for INLA::f() in a model that requires making only the first mapper visible to INLA::f() and INLA::inla.stack(), such as for "bym2" models, as activated by the inla_f argument to ibm_n, ibm_values, and ibm_jacobian. Set to FALSE to always access the full mapper, e.g. for rgeneric models

order

For bru_mapper_harmonics, specifies the maximum cos/sin order. (Default 1)

scaling

For bru_mapper_harmonics, specifies an optional vector of scaling factors of length intercept + order, or a common single scalar.

intercept

logical; For bru_mapper_harmonics, if TRUE, the first basis function is a constant. (Default TRUE)

interval

numeric length-2 vector specifying a domain interval. Default c(0, 1).

B

a square or tall basis conversion matrix

Methods (by class)

bru_mapper(default): Calls bru_mapper_define, passing all arguments along. Mapper implementations should call bru_mapper_define() instead, and supply at least a new_class class name. Use of the bru_mapper.default method will be deprecated from version 2.7.0.
bru_mapper(inla.mesh): Creates a mapper for 2D inla.mesh objects
bru_mapper(inla.mesh.1d): Create mapper for an inla.mesh.1d 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.
bru_mapper_index(): Create a an indexing mapper
bru_mapper_taylor(): 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)
bru_mapper_linear(): Create a mapper for linear effects
bru_mapper_matrix(): Create a matrix mapper, for a given number of columns
bru_mapper_factor(): Create a factor mapper
bru_mapper_const(): Create a constant mapper
bru_mapper_scale(): 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()))
bru_mapper_aggregate(): 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.
bru_mapper_logsumexp(): 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 with (state-log_weights)[block] - max((state-log_weights)[block]), and shifting the result back afterwards.
bru_mapper_pipe(): 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.
bru_mapper_multi(): Constructs a rowwise Kronecker product mapping
bru_mapper_collect(): Constructs a concatenated collection mapping
bru_mapper_harmonics(): 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.

Examples

Run this code

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