inlabru (version 2.3.1)

bru_options: Create or update an options objects

Description

Create a new options object, or merge information from several objects.

The _get, _set, and _reset functions operate on a global package options override object. In many cases, setting options in specific calls to bru() is recommended instead.

Usage

bru_options(...)
as.bru_options(x = NULL)
bru_options_default()
bru_options_check(options, ignore_null = TRUE)
bru_options_get(name = NULL, include_default = TRUE)
bru_options_set(..., .reset = FALSE)
bru_options_reset()

Arguments

...

A collection of named options, optionally including one or more bru_options objects. Options specified later override the previous options.

x

An object to be converted to an bru_options object.

options

An bru_options object to be checked

ignore_null

Ignore missing or NULL options.

name

Either NULL, or single option name string, or character vector or list with option names, Default: NULL

include_default

logical; If TRUE, the default options are included together with the global override options. Default: TRUE

.reset

For bru_options_set, logical indicating if the global override options list should be emptied before setting the new option(s).

Value

bru_options() returns an bru_options object.

For as.bru_options(), NULL or no input returns an empty bru_options object, a list is converted via bru_options(...), and bru_options input is passed through. Other types of input generates an error.

bru_options_default() returns an bru_options object containing default options.

bru_options_check() returns a logical; TRUE if the object contains valid options for use by other functions

bru_options_get returns either an bru_options object, for name == NULL, the contents of single option, if name is a options name string, or a named list of option contents, if name is a list of option name strings.

bru_options_set() returns a copy of the global override options, invisibly (as bru_options_get(include_default = FALSE)).

Valid options

For bru_options and bru_options_set, recognised options are:

bru_verbose

logical or numeric; if TRUE, log messages of verbosity \(\le 1\) are printed by bru_log_message(). If numeric, log messages of verbosity \(\le\)bru_verbose are printed. For line search details, set bru_verbose=2 or 3. Default: 0, to not print any messages

bru_verbose_store

logical or numeric; if TRUE, log messages of verbosity \(\le 1\) are stored by bru_log_message(). If numeric, log messages of verbosity \(\le\) are stored. Default: Inf, to store all messages.

bru_run

If TRUE, run inference. Otherwise only return configuration needed to run inference.

bru_max_iter

maximum number of inla iterations

bru_initial

An inla object returned from previous calls of INLA::inla, bru() or lgcp(), or a list of named vectors of starting values for the latent variables. This will be used as a starting point for further improvement of the approximate posterior.

bru_int_args

List of arguments passed all the way to the integration method ipoints and int.polygon for 'cp' family models;

method

"stable" or "direct". For "stable" (default) integration points are aggregated to mesh vertices.

nsub1

Number of integration points per knot interval in 1D. Default 30.

nsub2

Number of integration points along a triangle edge for 2D. Default 9.

nsub

Deprecated parameter that overrides nsub1 and nsub2 if set. Default NULL.

bru_method

List of arguments controlling the iterative inlabru method:

taylor

Either 'legacy' (for the pre-2.1.15 method) or 'pandemic' (default, from version 2.1.15).

search

Either 'all' (default), to use all available line search methods, or one or more of 'finite' (reduce step size until predictor is finite), 'contract' (decrease step size until trust hypersphere reached) 'expand' (increase step size until no improvement), 'optimise' (fast approximate error norm minimisation). To disable line search, set to an empty vector. Line search is not available for taylor="legacy".

factor

Numeric, \(> 1\) determining the line search step scaling multiplier. Default \((1 + \sqrt{5})/2\).

inla() options

All options not starting with bru_ are passed on to inla(), sometimes after altering according to the needs of the inlabru method. Warning: Due to how inlabru currently constructs the inla() call, the mean, prec, mean.intercept, and prec.intercept settings in control.fixed will have no effect. Until a more elegant alternative has been implemented, use explicit mean.linear and prec.linear specifications in each model="linear" component instead.

Details

bru_options_check checks for valid contents of an bru_options object

bru_options_check() produces warnings for invalid options.

bru_options_set() is used to set global package options.

bru_options_reset() clears the global option overrides.

See Also

bru_options(), bru_options_default(), bru_options_get()

Examples

# NOT RUN {
if (interactive()) {
  # Combine global and user options:
  options1 <- bru_options(bru_options_get(), bru_verbose = TRUE)
  # Create a proto-options object in two equivalent ways:
  options2 <- as.bru_options(bru_verbose = TRUE)
  options2 <- as.bru_options(list(bru_verbose = TRUE))
  # Combine options objects:
  options3 <- bru_options(options1, options2)
}
# }
# NOT RUN {
if (interactive()) {
  # EXAMPLE1
}
# }
# NOT RUN {
if (interactive()) {
  bru_options_check(bru_options(bru_max_iter = "text"))
}
# }
# NOT RUN {
if (interactive()) {
  # EXAMPLE1
}
# }
# NOT RUN {
if (interactive()) {
  bru_options_set(
    bru_verbose = TRUE,
    verbose = TRUE
  )
}
# }