A bru_mapper sub-class implementation must provide an
ibm_matrix() 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.
ibm_n(mapper, inla_f = FALSE, ...)ibm_n_output(mapper, input, inla_f = FALSE, ...)
ibm_values(mapper, inla_f = FALSE, ...)
ibm_amatrix(mapper, input, state = NULL, inla_f = FALSE, ...)
ibm_is_linear(mapper, ...)
ibm_jacobian(mapper, input, state = NULL, inla_f = FALSE, ...)
ibm_linear(mapper, input, state = NULL, ...)
ibm_eval(mapper, input, state = NULL, ...)
ibm_inla_subset(mapper, ...)
ibm_valid_input(mapper, input, inla_f = FALSE, ...)
# S3 method for default
ibm_n(mapper, inla_f = FALSE, ...)
# S3 method for default
ibm_n_output(mapper, input, inla_f = FALSE, ...)
# S3 method for default
ibm_values(mapper, inla_f = FALSE, ...)
# S3 method for default
ibm_amatrix(mapper, ...)
# S3 method for default
ibm_is_linear(mapper, ...)
# S3 method for default
ibm_jacobian(mapper, input, state, ...)
ibm_offset.default(mapper, input, state = NULL, ...)
# S3 method for default
ibm_linear(mapper, input, state, ...)
# S3 method for default
ibm_eval(mapper, input, state = NULL, ...)
# S3 method for default
ibm_inla_subset(mapper, ...)
# S3 method for default
ibm_valid_input(mapper, input, ...)
# S3 method for bru_mapper_inla_mesh_2d
ibm_n(mapper, ...)
# S3 method for bru_mapper_inla_mesh_2d
ibm_values(mapper, ...)
# S3 method for bru_mapper_inla_mesh_2d
ibm_jacobian(mapper, input, ...)
# S3 method for bru_mapper_inla_mesh_2d
ibm_jacobian(mapper, input, ...)
# S3 method for bru_mapper_inla_mesh_1d
ibm_n(mapper, ...)
# S3 method for bru_mapper_inla_mesh_1d
ibm_values(mapper, ...)
# S3 method for bru_mapper_inla_mesh_1d
ibm_jacobian(mapper, input, ...)
# S3 method for bru_mapper_index
ibm_valid_input(mapper, input, ...)
# S3 method for bru_mapper_index
ibm_jacobian(mapper, input, ...)
# S3 method for bru_mapper_taylor
ibm_n(mapper, inla_f = FALSE, multi = FALSE, ...)
# S3 method for bru_mapper_taylor
ibm_n_output(mapper, input, inla_f = FALSE, ...)
# S3 method for bru_mapper_taylor
ibm_values(mapper, inla_f = FALSE, multi = FALSE, ...)
# S3 method for bru_mapper_taylor
ibm_jacobian(mapper, ..., multi = FALSE)
# S3 method for bru_mapper_taylor
ibm_eval(mapper, input = NULL, state = NULL, ...)
# S3 method for bru_mapper_linear
ibm_n(mapper, ...)
# S3 method for bru_mapper_linear
ibm_values(mapper, ...)
# S3 method for bru_mapper_linear
ibm_jacobian(mapper, input, ...)
# S3 method for bru_mapper_matrix
ibm_n(mapper, ...)
# S3 method for bru_mapper_matrix
ibm_values(mapper, ...)
# S3 method for bru_mapper_matrix
ibm_jacobian(mapper, input, state = NULL, inla_f = FALSE, ...)
# S3 method for bru_mapper_factor
ibm_n(mapper, ...)
# S3 method for bru_mapper_factor
ibm_values(mapper, ...)
# S3 method for bru_mapper_factor
ibm_jacobian(mapper, input, ...)
# S3 method for bru_mapper_const
ibm_n(mapper, ...)
# S3 method for bru_mapper_const
ibm_values(mapper, ...)
# S3 method for bru_mapper_const
ibm_jacobian(mapper, input, ...)
# S3 method for bru_mapper_const
ibm_eval(mapper, input, state = NULL, ...)
# S3 method for bru_mapper_scale
ibm_n(mapper, ...)
# S3 method for bru_mapper_scale
ibm_n_output(mapper, input, ...)
# S3 method for bru_mapper_scale
ibm_values(mapper, ...)
# S3 method for bru_mapper_scale
ibm_jacobian(mapper, input, state = NULL, ..., sub_lin = NULL)
ibm_offset.bru_mapper_scale(mapper, input, ..., sub_lin = NULL)
# S3 method for bru_mapper_scale
ibm_linear(mapper, input, state, ...)
# S3 method for bru_mapper_scale
ibm_eval(mapper, input, state = NULL, ..., sub_lin = NULL)
# S3 method for bru_mapper_scale
ibm_valid_input(mapper, input, ...)
# S3 method for bru_mapper_multi
ibm_n(mapper, inla_f = FALSE, multi = FALSE, ...)
# S3 method for bru_mapper_multi
ibm_n_output(mapper, input, ...)
# S3 method for bru_mapper_multi
ibm_values(mapper, inla_f = FALSE, multi = FALSE, ...)
# S3 method for bru_mapper_multi
ibm_is_linear(mapper, multi = FALSE, ...)
# S3 method for bru_mapper_multi
ibm_jacobian(
mapper,
input,
state = NULL,
inla_f = FALSE,
multi = FALSE,
...,
sub_A = NULL
)
# S3 method for bru_mapper_multi
ibm_linear(mapper, input, state, inla_f = FALSE, ...)
# S3 method for bru_mapper_multi
ibm_eval(mapper, input, state = NULL, inla_f = FALSE, ..., pre_A = NULL)
# S3 method for bru_mapper_multi
ibm_valid_input(mapper, input, inla_f = FALSE, multi = FALSE, ...)
# S3 method for bru_mapper_multi
[(x, i, drop = TRUE)
# S3 method for bru_mapper_multi
names(x)
# S3 method for bru_mapper_multi
names(x) <- value
# S3 method for bru_mapper_collect
ibm_n(mapper, inla_f = FALSE, multi = FALSE, ...)
# S3 method for bru_mapper_collect
ibm_n_output(mapper, input, inla_f = FALSE, multi = FALSE, ...)
# S3 method for bru_mapper_collect
ibm_values(mapper, inla_f = FALSE, multi = FALSE, ...)
# S3 method for bru_mapper_collect
ibm_is_linear(mapper, inla_f = FALSE, multi = FALSE, ...)
# S3 method for bru_mapper_collect
ibm_jacobian(
mapper,
input,
state = NULL,
inla_f = FALSE,
multi = FALSE,
...,
sub_lin = NULL
)
# S3 method for bru_mapper_collect
ibm_eval(
mapper,
input,
state,
inla_f = FALSE,
multi = FALSE,
...,
sub_lin = NULL
)
# S3 method for bru_mapper_collect
ibm_linear(mapper, input, state, inla_f = FALSE, ...)
# S3 method for bru_mapper_collect
ibm_valid_input(mapper, input, inla_f = FALSE, multi = FALSE, ...)
# S3 method for bru_mapper_collect
[(x, i, drop = TRUE)
# S3 method for bru_mapper_collect
names(x)
# S3 method for bru_mapper_collect
names(x) <- value
# S3 method for bru_mapper_harmonics
ibm_n(mapper, inla_f = FALSE, ...)
# S3 method for bru_mapper_harmonics
ibm_jacobian(mapper, input, state = NULL, inla_f = FALSE, ...)
[-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)
The names() method for bru_mapper_multi returns the names from the
sub-mappers list
[-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
A mapper S3 object, normally inheriting from bru_mapper
logical; when TRUE in ibm_n and ibm_values,
these must result in values compatible with INLA::f(...)
an specification and corresponding INLA::inla.stack(...) constructions.
For the ibm_eval and ibm_jacobian methods, it may influence how the
input data is interpreted.
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
Data input for the mapper.
A vector of latent state values for the mapping,
of length ibm_n(mapper, inla_f = FALSE)
logical;
If TRUE (or positive), recurse one level into sub-mappers
Internal, optional pre-computed sub-mapper information
Internal; precomputed Jacobian matrices.
Internal; precomputed Jacobian matrix
object from which to extract element(s)
indices specifying element(s) to extract
logical;
For [.bru_mapper_collect, whether to extract an individual mapper when
i identifies a single element. If FALSE, a list of sub-mappers is
returned (suitable e.g. for creating a new bru_mapper_collect object).
Default: TRUE
a character vector of up to the same length as x
ibm_n Generic. Implementations must return the size of the latent vector
being mapped to.
ibm_n_output Generic.
Implementations must return an integer denoting the
mapper output length, for valid inputs as determined by
ibm_valid_input(mapper, input, inla_f = inla_f).
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 Generic. 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_amatrix Generic, will become deprecated in 2.7.0. Use ibm_jacobian
instead.
Implementations must return a (sparse) matrix of size ibm_n_output(...)
by ibm_n(...). The inla_f=TRUE argument should only affect
the allowed type of input format.
ibm_is_linear Generic.
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 Generic.
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() Generic.
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_eval Generic.
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_inla_subset Generic.
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_valid_input Generic.
Implementations should return a logical vector of length NROW(input),
or for bru_mapper_multi and bru_mapper_collect a list of such
vectors.
The default ibm_n() method 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.
The default ibm_values() method returns a non-null element
'values' from the mapper object, and seq_len(ibm_n(mapper)) if
it doesn't exist.
The default ibm_amatrix() method gives an error message.
Mapper classes must implement their own ibm_jacobian or
ibm_amatrix methods. New implementations should use
a ibm_jacobian method. ibm_amatrix may become deprecated
in a future version.
The default ibm_is_linear() method returns logical
'is_linear' from the mapper object if it exists, and otherwise TRUE.
The default ibm_jacobian() calls ibm_amatrix, which
by default gives an error.
Mapper classes should implement their own ibm_jacobian method.
The default ibm_linear() method 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)
The default ibm_eval() method 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.
The default ibm_inla_subset method 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).
The default ibm_valid_input() method returns an all-TRUE logical vector.
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.
For bru_mapper_scale, input values without a scale element
are interpreted as no scaling.
ibm_valid_input for bru_mapper_scale accepts a list with
named entries mapper and scale. The contents of the mapper
element is checked for validity for the submapper
with ibm_valid_input(mapper$mapper, input$mapper, ...)
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 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_valid_input 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 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_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 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_valid_input 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 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.
bru_mapper for constructor methods, and bru_get_mapper for hooks to extract mappers from latent model object class objects.