Modifying a Teal application with R options
Paweł Rucki
2021-12-23
teal-options.Rmd
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.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