samOptiPro options constructor

Build a consistent options list used internally by samOptiPro.

Usage

samOptiPro_options(
  include_data = FALSE,
  include_logLik = FALSE,
  extra_monitors = NULL,
  extra_monitors2 = NULL,
  ...
)

Arguments

include_data

logical; default FALSE. If TRUE, data nodes may be included when discovering monitors.

include_logLik

logical; default FALSE. If TRUE, a variable called "logLik" is added to default monitors when present.

extra_monitors

character vector of additional variable roots to monitor in the main samples. Default NULL.

extra_monitors2

character vector of additional variable roots to monitor in the secondary samples. Default NULL.

...

Named components that either extend or override entries in the options list. This is mainly intended for future extensions and for advanced users.

Value

A named list of options, to be passed around as opts.

Details

This helper gathers three sources of information, in increasing order of priority:

1. Package defaults (hard-coded in this function),

2. Global R option "samOptiPro.options" (a named list),

3. Explicit arguments passed to samOptiPro_options().

The returned object is a named list. Unknown fields are kept as-is so that new components can be added in the future without breaking the API.

Typical consumers only need a few fields:

• include_data : logical; whether to include data nodes when discovering monitors (rarely needed; default FALSE).

• include_logLik : logical; whether to include a "logLik" variable in default monitors (default FALSE).

• extra_monitors : character vector of additional variable roots to monitor in the main samples.

• extra_monitors2 : character vector of additional variable roots to monitor in the secondary samples (if any).

Internal functions such as default_monitors(), .configure_with_monitors(), or the various runner helpers are expected to accept a generic list opts and use only the fields they understand (ignoring unknown components).

Examples

# Default options
samOptiPro_options()
#> $include_data
#> [1] FALSE
#> 
#> $include_logLik
#> [1] FALSE
#> 
#> $extra_monitors
#> NULL
#> 
#> $extra_monitors2
#> NULL
#> 

# Override a few fields explicitly
samOptiPro_options(include_logLik = TRUE,
                   extra_monitors = c("logLik", "sigma_proc"))
#> $include_data
#> [1] FALSE
#> 
#> $include_logLik
#> [1] TRUE
#> 
#> $extra_monitors
#> [1] "logLik"     "sigma_proc"
#> 
#> $extra_monitors2
#> NULL
#> 

# Use a global R option and then refine locally
old <- options(samOptiPro.options = list(include_logLik = TRUE))
samOptiPro_options()  # will have include_logLik = TRUE
#> $include_data
#> [1] FALSE
#> 
#> $include_logLik
#> [1] TRUE
#> 
#> $extra_monitors
#> NULL
#> 
#> $extra_monitors2
#> NULL
#> 
samOptiPro_options(include_logLik = FALSE)  # local override
#> $include_data
#> [1] FALSE
#> 
#> $include_logLik
#> [1] TRUE
#> 
#> $extra_monitors
#> NULL
#> 
#> $extra_monitors2
#> NULL
#> 
options(old)