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. Forbru_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
orinla.mesh.2d
object to use as a mapper- indexed
logical; if
TRUE
, theibm_values()
method will return an integer vector instead of the factor levels. This is needed e.g. forgroup
andreplicate
mappers, sinceINLA::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 atstate0
. May beNULL
, interpreted as an all-zero vector of length determined by a non-null Jacobian.- jacobian
For
bru_mapper_taylor
, the Jacobian matrix, evaluated atstate0
, or, a named list of such matrices. May beNULL
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 thejacobian
list.NULL
is interpreted as 0.- values_mapper
mapper object to be used for
ibm_n
andibm_values
forinla_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
andbru_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 areNULL
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 toTRUE
to flag that the mapper is to be used as a first level input mapper forINLA::f()
in a model that requires making only the first mapper visible toINLA::f()
andINLA::inla.stack()
, such as for "bym2" models, as activated by theinla_f
argument toibm_n
,ibm_values
, andibm_jacobian
. Set toFALSE
to always access the full mapper, e.g. forrgeneric
models- order
For
bru_mapper_harmonics
, specifies the maximumcos
/sin
order. (Default 1)- scaling
For
bru_mapper_harmonics
, specifies an optional vector of scaling factors of lengthintercept + order
, or a common single scalar.- intercept
logical; For
bru_mapper_harmonics
, ifTRUE
, the first basis function is a constant. (DefaultTRUE
)- interval
numeric length-2 vector specifying a domain interval. Default
c(0, 1)
.
Methods (by class)
bru_mapper(default)
: Callsbru_mapper_define
, passing all arguments along. Mapper implementations should callbru_mapper_define()
instead, and supply at least anew_class
class name. Use of thebru_mapper.default
method will be deprecated from version 2.7.0.bru_mapper(inla.mesh)
: Creates a mapper for 2Dinla.mesh
objectsbru_mapper(inla.mesh.1d)
: Create mapper for aninla.mesh.1d
object
Functions
bru_mapper()
: Generic mapper S3 constructor, used for constructing mappers for special objects. See below for details of the default constructorbru_mapper_define()
that can be used to define new mappers in user code.bru_mapper_define()
: Adds thenew_class
and "bru_mapper" class names to the inheritance list for the inputmapper
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 mapperbru_mapper_taylor()
: Provides a pre-computed affine mapping, internally used to represent and evaluate linearisation information. Thestate0
information indicates for which state theoffset
was evaluated; The affine mapper output is defined aseffect(state) = offset + jacobian %*% (state - state0)
bru_mapper_linear()
: Create a mapper for linear effectsbru_mapper_matrix()
: Create a matrix mapper, for a given number of columnsbru_mapper_factor()
: Create a factor mapperbru_mapper_const()
: Create a constant mapperbru_mapper_scale()
: Create a standalone scaling mapper that can be used as part of abru_mapper_pipe
. Ifmapper
is non-null, thebru_mapper_scale()
constructor returnsbru_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 ofexp(state)
, with optional non-negative weighting, and then takes thelog()
, 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 forbru_mapper_aggregate
, but also allows the weights to be supplied on a logarithmic scale aslog_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.. Theinput
format for theibm_eval
andibm_jacobian
methods is a list of inputs, one for each mapper.bru_mapper_multi()
: Constructs a rowwise Kronecker product mappingbru_mapper_collect()
: Constructs a concatenated collection mappingbru_mapper_harmonics()
: Constructs a mapper forcos
/sin
functions of orders 1 (ifintercept
isTRUE
, otherwise 0) throughorder
. The total number of basis functions isintercept + 2 * order
.Optionally, each order can be given a non-unit scaling, via the
scaling
vector, of lengthintercept + 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
andu2
will be the same, withscaling^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 . . .