Modifying a Teal application with R options

Paweł Rucki

2021-12-23

Motivation

Some R packages use options to modify their runtime behavior. These usually specify default values for internal functions or determine responses to users actions. For example, testthat uses an option testthat.progress.max_fails to define a default number of failed expectations before the testing functions terminate execution. While some of these adjustable values can be exposed as function parameters, some are destined to remain an option. This vignette details the options available to users of teal, teal.logger, teal.widgets, teal.modules.general, teal.modules.clinical.

Setting an option

At any time during an interactive session, you can change an option using:

options(option_to_set = "value")

A way to change options for only the execution of a specific block of code is with the withr package like so:

withr::with_options(list(digits = 3), print(pi))

## [1] 3.14

After the line above is run the option, digits, will go back to its value before the line was run.

The function getOption allows to inspect the value of an option:

getOption("option_to_set")

## [1] "value"

Once set, the value of an option persists during a session, but it returns to the default value in a new session. Make sure to change the options after all the teal-related packages are loaded because some of them initialize the options themselves and will overwrite your custom values.

Options used in a teal application

teal.log_layout (character)

This defines the layout of a log message used in a teal application. teal uses this layout to format the emitted log messages. Read the documentation of teal.logger::register_logger for more information.

Default: "[{level}] {format(time, \"%Y-%m-%d %H:%M:%OS4\")} pid:{pid} token:[{token}] {ans} {msg}".

Note that this layout is formatted by the package glue::glue.

teal.log_level (character)

This is the logging level threshold used in a teal application. A teal application will not emit logs below this level. Read the documentation of teal.logger::register_logger for more information. Possible values: "TRACE", "INFO", "WARNING", "ERROR". See the documentation of logger::TRACE for all possible values of logging threshold and more information on what it does.

Default: "INFO".

Note that there are two levels considered less severe than "INFO": "DEBUG" and "TRACE". In order to see the log messages for these two levels as well, change the log level from the default to "TRACE", the least severe log level.

teal_logging

Deprecated.

teal_show_js_log

Deprecated in favor of teal.show_js_log (see below).

teal.show_js_log (logical)

This indicates whether to print the Javascript console logs to the R console. If set to TRUE, the logs will be printed; otherwise, they won’t.

Default: FALSE.

teal.threshold_slider_vs_checkboxgroup (numeric)

It is the threshold that determines if a numeric variable is treated as a factor in the filter panel. If the number of unique values of a numeric variable is less than this threshold this variable will be treated as a factor instead of a numeric one. As an example, imagine teal.threshold_slider_vs_checkboxgroup equals to 2. Then a numeric variable c(1, 1, 1), which has only one unique value (a digit 1), is treated as a factor in the filter panel (and in the filter panel only!). The filter panel creates a checkbox widget to filter values from this variable, as it would for a factor variable, instead of a usual slider widget for numeric variables.

Default: 5.

teal.load_nest_code (character)

The value of this option is appended to the top of the code rendered when using the Show R Code modal button. See the documentation of teal::get_rcode for more information.

Default: "# Add any code to install/load your NEST environment here".

teal.widgets package

teal.basic_table_args (basic_table_args object)

This specifies the list of arguments passed to every call to rtables::basic_table made in a teal application. This can be used to format rtables without making any changes to the application code. See the documentation of teal.widgets::basic_table_args for more information.

Default: teal.widgets::basic_table_args().

teal.ggplot2_args (ggplot2_args object)

This option allows modifying labels and themes of all ggplot2 plots in a teal application. See the documentation of teal.widgets::ggplot2_args for more information.

Default: teal.widgets::ggplot2_args().

teal.plot_dpi (integer value 24 or larger)

This option controls the dots per inch of the graphs rendered and downloaded when using plot_with_settings.

Default: 72

teal.bs_theme (bslib::bs_theme object)

This option controls the bootstrap theme and version used in the teal apps. Achieve better UX with the customized UI of an app. Please visit the vignette("teal-bs-themes", package = "teal") to read more about the functionality.

Default: NULL