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

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

.

## 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, where 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`= 1 / (1 + (0:4)^2) scaling <- seq(0, 1, length.out = 11) x = bru_mapper_harmonics(order = 4, interval = c(0, 1)) bmh1 <- ibm_eval( u1 bmh1,input = x, state = rnorm(9, sd = rep(scaling, c(1, 2, 2, 2, 2))) )`

Then, with

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

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`

.

## See also

bru_mapper_generics for generic methods, bru_mapper_methods for specific method implementations, and bru_get_mapper for hooks to extract mappers from latent model object class objects.

## Examples

```
mapper <- bru_mapper_index(5)
ibm_jacobian(mapper, input = c(1, 3, 4, 5, 2))
#> 5 x 5 sparse Matrix of class "dgCMatrix"
#>
#> [1,] 1 . . . .
#> [2,] . . 1 . .
#> [3,] . . . 1 .
#> [4,] . . . . 1
#> [5,] . 1 . . .
```