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, ...)
# S3 method for default
ibm_n(mapper, inla_f = FALSE, ...)
# S3 method for default
ibm_n_output(mapper, input, state = NULL, inla_f = FALSE, ...)
# S3 method for default
ibm_values(mapper, inla_f = FALSE, ...)
# S3 method for default
ibm_is_linear(mapper, ...)
# S3 method for default
ibm_jacobian(mapper, input, state, ...)
# S3 method for default
ibm_linear(mapper, input, state, ...)
# S3 method for default
ibm_simplify(mapper, input = NULL, state = NULL, ...)
# S3 method for default
ibm_eval(mapper, input, state = NULL, ..., jacobian = NULL)
# S3 method for default
ibm_eval2(mapper, input, state, ...)
# S3 method for default
ibm_names(mapper, ...)
# S3 method for default
ibm_inla_subset(mapper, ...)
# S3 method for default
ibm_invalid_output(mapper, input, state, ...)
```

## Arguments

- mapper
A mapper S3 object, inheriting from

`bru_mapper`

.- inla_f
logical; when

`TRUE`

for`ibm_n()`

and`ibm_values()`

, the result must be compatible with the`INLA::f(...)`

and corresponding`INLA::inla.stack(...)`

constructions. For`ibm_{eval,jacobian,linear}`

, the`input`

interpretation may be different. Implementations do not normally need to do anything different, except for mappers of the type needed for hidden multicomponent models such as "bym2", which can be handled by`bru_mapper_collect`

.- ...
Arguments passed on to other methods

- input
Data input for the mapper.

- state
A vector of latent state values for the mapping, of length

`ibm_n(mapper, inla_f = FALSE)`

- value
a character vector of the same length as the number of sub-mappers in the mapper

- jacobian
For

`ibm_eval()`

methods, an optional pre-computed Jacobian, typically supplied by internal methods that already have the Jacobian.

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

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

,
`bru_mapper()`

## Examples

```
# ibm_names
mapper <- bru_mapper_multi(list(
A = bru_mapper_index(2),
B = bru_mapper_index(2)
))
ibm_names(mapper)
#> [1] "A" "B"
ibm_names(mapper) <- c("new", "names")
ibm_names(mapper)
#> [1] "new" "names"
```