Skip to contents

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.



as.bru_options(x = NULL)


bru_options_check(options, ignore_null = TRUE)

bru_options_get(name = NULL, include_default = TRUE)

bru_options_set(..., .reset = FALSE)




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


An object to be converted to an bru_options object.


An bru_options object to be checked


Ignore missing or NULL options.


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


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


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


bru_options() returns a 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)).


  • as.bru_options(): Coerces inputs to a bru_options object.

  • bru_options_default(): Returns the default options.

  • bru_options_check(): Checks for valid contents of a bru_options object, and produces warnings for invalid options.

  • bru_options_get(): Used to access global package options.

  • bru_options_set(): Used to set global package options.

  • bru_options_reset(): Clears the global option overrides.

Valid options

For bru_options and bru_options_set, recognised options are:


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


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.


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


maximum number of inla iterations, default 10. Also see the bru_method$rel_tol and related options below.


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.


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


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


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


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


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


List of arguments controlling the iterative inlabru method:


'pandemic' (default, from version 2.1.15).


Either 'all' (default), to use all available line search methods, or one or more of


(reduce step size until predictor is finite)


(decrease step size until trust hypersphere reached)


(increase step size until no improvement)


(fast approximate error norm minimisation)

To disable line search, set to an empty vector. Line search is not available for taylor="legacy".


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


Stop the iterations when the largest change in linearisation point (the conditional latent state mode) in relation to the estimated posterior standard deviation is less than rel_tol. Default 0.1 (ten percent).


The largest allowed line search step factor. Factor 1 is the full INLA step. Default is 2.


Which method to use for the line search optimisation step. Default "onestep", using a quadratic approximation based on the value and gradient at zero, and the value at the current best step length guess. The method "full" does line optimisation on the full nonlinear predictor; this is slow and intended for debugging purposes only.


logical; when TRUE, compress the \(\sum_{i=1}^n \eta_i\) part of the Poisson process likelihood (family="cp") into a single term, with \(y=n\), and predictor mean(eta). Default: TRUE


logical; when TRUE, activate temporary debug features for package development. Default: FALSE

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.

See also

bru_options(), bru_options_default(), bru_options_get()


if (FALSE) {
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)
if (FALSE) {
if (interactive()) {
  bru_options_check(bru_options(bru_max_iter = "text"))
#> [1] 0
if (FALSE) {
if (interactive()) {
    bru_verbose = TRUE,
    verbose = TRUE