Options API (R)

In jamovi, the self$options object is the single source of truth for your analysis. It acts as the bridge between the user interface (defined in your .a.yaml file) and your R execution logic.

When a user changes a setting in the jamovi UI, those changes are synchronized to self$options. Your R code then reads from this object to determine how to perform the analysis.

The Mental Model

Think of self$options as a read-only contract. It is an R6 object automatically generated by jmvtools based on your analysis definition. You should never try to modify self$options directly in your R code; instead, you treat it as the set of instructions provided by the user.

Accessing Values (The Shorthand)

The most common task is retrieving the value of an option. jamovi provides a convenient shorthand using the $ operator. This is the standard way to get the current state of a parameter.

# Accessing a boolean (Bool) option
if (self$options$showDescriptives) {
    # ... calculate descriptives
}

# Accessing a variable selection (Variables)
# Returns a character vector of variable names
dependentVariable <- self$options$dep

# Accessing a numeric value (Number)
alpha <- self$options$alphaLevel

The values returned are standard R types (logical, character, numeric, etc.) corresponding to the option type defined in your YAML.

The Options Object API

While the shorthand gives you the value, sometimes you need to interact with the Option Object itself. This is useful if you need to access metadata (like the option’s title or default value) or if you are working with special types like Actions.

To get the underlying R6 object, use the $option() method:

# Get the R6 object for 'myOption'
opt <- self$options$option('myOption')

# Access metadata
title <- opt$title
defaultValue <- opt$default

When to use the Object API

Actions: To trigger an action via self$options$option('myAction')$perform().
Metadata: If your logic needs to know the default value or the title of the option as defined in the YAML.
Advanced Logic: If you are writing generic code that needs to inspect the properties of the options.

Utility Methods

The self$options object provides several utility methods to help manage parameters.

`as.list()`

Converts all current option values into a standard R list. This is particularly useful when you want to pass all analysis parameters to an external function or a base R function.

# Convert options to a list
args <- self$options$as.list()

# Pass to another function
do.call(stats::t.test, args)

`has(name)`

Checks if an option with the given name is defined in the analysis. This is useful for shared code that might be used across different analyses with slightly different option sets.

if (self$options$has('optionalSetting')) {
    # Logic for when the option exists
}

Relationship to Results

Options are the primary drivers of your analysis results. This relationship manifests in two ways:

Conditional Logic (R): You use if statements checking self$options to decide which tables to fill or which calculations to run.
Data Binding (YAML): You can bind the visibility or content of results directly to options in your .r.yaml file. For example, a table might only be visible if self$options$showTable is TRUE.

By keeping self$options as the single source of truth, jamovi ensures that your analysis remains reproducible and consistent with the UI state.