# R option: convenient inside an R session or script
options(rpact.summary.digits = 4)
# Environment variable: useful before code calls rpact functionality
Sys.setenv(RPACT_SUMMARY_DIGITS = "4")Hidden rpact Features: Options and Environment Variables
Utilities
Overview of hidden rpact configuration options that can be controlled through R options or environment variables, including summary formatting, plot defaults, markdown behavior, output formats, and validation-related settings.
Introduction
rpact exposes many user-facing arguments, but it also has a set of package options that can be used to adjust recurring behavior without passing the same argument again and again. These settings are intentionally lightweight: they can be configured through R options with options() or through environment variables, which is useful for reproducible scripts, CI jobs, validation runs, and shared project profiles.
This vignette collects the options that are currently read through the internal .getEnvironmentVariable() helper. The helper first checks the environment variable and then falls back to the R option. In practice, this means that an environment variable overrides the corresponding R option for the current R process.
For option keys that start with rpact., the environment variable name is derived by uppercasing the option key and replacing dots with underscores. For example, rpact.summary.digits becomes RPACT_SUMMARY_DIGITS.
Logical environment variables are parsed as TRUE for values such as "true", "1", "yes", and "on"; other non-empty values are interpreted as FALSE.
Configuration Pattern
Every option in this vignette can be adjusted in one of two ways:
# Option style
options(rpact.plot.show.beta.spent = TRUE)
# Environment-variable style
Sys.setenv(RPACT_PLOT_SHOW_BETA_SPENT = "true")Environment variables are strings, so quote values when using Sys.setenv(). R options can use native R values such as TRUE, 4L, or "large".
Summary and Printed Output
These options control the appearance and amount of information in printed summaries, markdown output, and formatted summary values.
rpact.summary.digits
Environment variable: RPACT_SUMMARY_DIGITS
Default: 3
Controls the default number of digits used by summary methods when no explicit digits argument is supplied.
options(rpact.summary.digits = 4L)
Sys.setenv(RPACT_SUMMARY_DIGITS = "4")rpact.summary.digits.probs
Environment variable: RPACT_SUMMARY_DIGITS_PROBS
Default: rpact.summary.digits + 1
Controls the number of digits used for probability-like summary values. If this setting cannot be parsed, rpact falls back to one more digit than rpact.summary.digits.
options(rpact.summary.digits.probs = 5L)
Sys.setenv(RPACT_SUMMARY_DIGITS_PROBS = "5")rpact.summary.intervalFormat
Environment variable: RPACT_SUMMARY_INTERVALFORMAT
Default: "[%s; %s]"
Controls how two-part values, for example intervals, are displayed in summaries. The format string must contain exactly two %s placeholders.
options(rpact.summary.intervalFormat = "(%s, %s)")
Sys.setenv(RPACT_SUMMARY_INTERVALFORMAT = "(%s, %s)")rpact.summary.justify
Environment variable: RPACT_SUMMARY_JUSTIFY
Default: "right"
Controls how values are aligned in printed summary tables. The value is passed to base R formatting, so typical values are "right", "left", "centre", and "none".
options(rpact.summary.justify = "left")
Sys.setenv(RPACT_SUMMARY_JUSTIFY = "left")rpact.summary.na
Environment variable: RPACT_SUMMARY_NA
Default: ""
Controls the replacement text for NA values in summaries. The default leaves these cells visually blank.
options(rpact.summary.na = "n/a")
Sys.setenv(RPACT_SUMMARY_NA = "n/a")rpact.summary.output.size
Environment variable: RPACT_SUMMARY_OUTPUT_SIZE
Default: "large"
Controls how much detail selected summary methods include. The code recognizes the levels "small", "medium", and "large" in several summary paths. "large" includes the most detail; "small" produces more compact summaries.
options(rpact.summary.output.size = "medium")
Sys.setenv(RPACT_SUMMARY_OUTPUT_SIZE = "medium")rpact.summary.trim.zeroes
Environment variable: RPACT_SUMMARY_TRIM_ZEROES
Default: TRUE
Controls whether formatted zero values such as "0.000" are shown as "0" in summary output.
options(rpact.summary.trim.zeroes = FALSE)
Sys.setenv(RPACT_SUMMARY_TRIM_ZEROES = "false")rpact.summary.width
Environment variable: RPACT_SUMMARY_WIDTH
Default: 83
Controls the maximum line length used when rpact inserts line breaks in summary header text.
options(rpact.summary.width = 100L)
Sys.setenv(RPACT_SUMMARY_WIDTH = "100")rpact.summary.list.item.prefix
Environment variable: RPACT_SUMMARY_LIST_ITEM_PREFIX
Default: two spaces
Controls the prefix used for certain generated group captions, especially in multi-group, enrichment, and multi-arm summaries.
options(rpact.summary.list.item.prefix = " - ")
Sys.setenv(RPACT_SUMMARY_LIST_ITEM_PREFIX = " - ")rpact.print.heading.base.number
Environment variable: RPACT_PRINT_HEADING_BASE_NUMBER
Default: -2
Controls how headings are rendered when rpact prints markdown output. Values below -2 are reset to the default; values above 4 are capped at 4.
The special values -2 and -1 render headings as italic and bold inline text, respectively. Non-negative values render markdown headings by adding the value to the internal heading level.
options(rpact.print.heading.base.number = 1L)
Sys.setenv(RPACT_PRINT_HEADING_BASE_NUMBER = "1")rpact.markdown.plot.print.separator
Environment variable: RPACT_MARKDOWN_PLOT_PRINT_SEPARATOR
Default: a markdown horizontal-rule separator
Controls the separator inserted between plot output and printed output in markdown contexts.
options(rpact.markdown.plot.print.separator = "\n\n---\n\n")
Sys.setenv(RPACT_MARKDOWN_PLOT_PRINT_SEPARATOR = "\n\n---\n\n")Automatic Markdown Behavior
rpact detects R Markdown and Quarto contexts and can switch selected print, summary, and plot methods into markdown-aware output. The following dynamic options are constructed from rpact.auto.markdown. plus a scope name.
| Option | Environment variable | Default | Scope |
|---|---|---|---|
rpact.auto.markdown.all |
RPACT_AUTO_MARKDOWN_ALL |
TRUE |
Global markdown checks |
rpact.auto.markdown.print |
RPACT_AUTO_MARKDOWN_PRINT |
TRUE |
Print methods |
rpact.auto.markdown.summary |
RPACT_AUTO_MARKDOWN_SUMMARY |
TRUE |
Summary methods |
rpact.auto.markdown.plot |
RPACT_AUTO_MARKDOWN_PLOT |
TRUE |
Plot methods |
Set a scope to FALSE when a document should keep console-style output for that part of rpact.
options(rpact.auto.markdown.plot = FALSE)
Sys.setenv(RPACT_AUTO_MARKDOWN_PLOT = "false")Output Number Formatting
Output-format options are dynamic. They are all listed in C_OUTPUT_FORMAT_DEFAULT_VALUES internally and are read with .getEnvironmentVariable(.getEnvironmentVariableKey(optionKey), optionKey).
Each value is a comma-separated string of formatting arguments. Supported arguments are:
| Argument | Meaning |
|---|---|
digits |
Significant digits, as an integer |
nsmall |
Minimum digits to the right of the decimal point |
trimSingleZeros |
If TRUE, display values such as "0.00" as "0" |
futilityProbabilityEnabled |
If TRUE, display very small futility probabilities below 1e-09 as 0 |
roundFunction |
One of ceiling, floor, trunc, round, or signif |
The public setOutputFormat() function is usually the safest way to change these values during an R session. Environment variables are useful when the same format must be active before rpact code is called.
options(rpact.output.format.p.value = "digits = 5, nsmall = 5")
Sys.setenv(RPACT_OUTPUT_FORMAT_P_VALUE = "digits = 5, nsmall = 5")The available output-format options are:
| Option | Environment variable | Default | Affects |
|---|---|---|---|
rpact.output.format.p.value |
RPACT_OUTPUT_FORMAT_P_VALUE |
digits = 4, nsmall = 4 |
p-values |
rpact.output.format.repeated.p.value |
RPACT_OUTPUT_FORMAT_REPEATED_P_VALUE |
digits = 4, nsmall = 4 |
repeated p-values |
rpact.output.format.probability |
RPACT_OUTPUT_FORMAT_PROBABILITY |
digits = 4, nsmall = 4 |
general probabilities |
rpact.output.format.futility.probability |
RPACT_OUTPUT_FORMAT_FUTILITY_PROBABILITY |
digits = 4, nsmall = 4, futilityProbabilityEnabled = TRUE |
futility probabilities |
rpact.output.format.sample.size |
RPACT_OUTPUT_FORMAT_SAMPLE_SIZE |
digits = 1, nsmall = 1 |
sample sizes |
rpact.output.format.event |
RPACT_OUTPUT_FORMAT_EVENT |
digits = 1, nsmall = 1, trimSingleZeros = TRUE |
event counts |
rpact.output.format.event.time |
RPACT_OUTPUT_FORMAT_EVENT_TIME |
digits = 3, trimSingleZeros = TRUE |
event times |
rpact.output.format.conditional.power |
RPACT_OUTPUT_FORMAT_CONDITIONAL_POWER |
digits = 4 |
conditional power values |
rpact.output.format.critical.value |
RPACT_OUTPUT_FORMAT_CRITICAL_VALUE |
digits = 3, nsmall = 3 |
critical values |
rpact.output.format.critical.value.fisher |
RPACT_OUTPUT_FORMAT_CRITICAL_VALUE_FISHER |
digits = 4 |
Fisher critical values |
rpact.output.format.test.statistic.fisher |
RPACT_OUTPUT_FORMAT_TEST_STATISTIC_FISHER |
digits = 4 |
Fisher test statistics |
rpact.output.format.test.statistic |
RPACT_OUTPUT_FORMAT_TEST_STATISTIC |
digits = 3, nsmall = 3 |
test statistics |
rpact.output.format.rate |
RPACT_OUTPUT_FORMAT_RATE |
digits = 3, nsmall = 3 |
rates and related rate values |
rpact.output.format.rate1 |
RPACT_OUTPUT_FORMAT_RATE1 |
digits = 1, nsmall = 1 |
dynamic rate values, including values routed through the rate formatter |
rpact.output.format.accrual.intensity |
RPACT_OUTPUT_FORMAT_ACCRUAL_INTENSITY |
digits = 2, nsmall = 1 |
accrual intensities |
rpact.output.format.mean |
RPACT_OUTPUT_FORMAT_MEAN |
digits = 4 |
means |
rpact.output.format.ratio |
RPACT_OUTPUT_FORMAT_RATIO |
digits = 3 |
ratios |
rpact.output.format.st.dev |
RPACT_OUTPUT_FORMAT_ST_DEV |
digits = 4 |
standard deviations |
rpact.output.format.duration |
RPACT_OUTPUT_FORMAT_DURATION |
digits = 2, nsmall = 2 |
durations |
rpact.output.format.time |
RPACT_OUTPUT_FORMAT_TIME |
digits = 2, nsmall = 2 |
time values |
Plot Options
These options change defaults used by selected plot methods. Explicit plot arguments still take precedence where such arguments are available.
rpact.plot.labs.type
Environment variable: RPACT_PLOT_LABS_TYPE
Default: "quote"
Controls how plot labels and title objects are rendered. The default "quote" uses plotmath-style expressions for selected labels such as theta and pi. Other values keep label items as text and can enable HTML title handling in contexts that support it.
options(rpact.plot.labs.type = "text")
Sys.setenv(RPACT_PLOT_LABS_TYPE = "text")rpact.plot.labs.caption.enabled
Environment variable: RPACT_PLOT_LABS_CAPTION_ENABLED
Default: TRUE
Controls whether additional plot title information is placed in the plot caption when rpact.plot.labs.type is not "quote". If disabled, the same information is appended to the subtitle instead.
options(rpact.plot.labs.caption.enabled = FALSE)
Sys.setenv(RPACT_PLOT_LABS_CAPTION_ENABLED = "false")rpact.plot.show.alpha.spent
Environment variable: RPACT_PLOT_SHOW_ALPHA_SPENT
Default: TRUE
Controls whether alpha-spent curves are included by default in plots that can show alpha and beta spending. Function arguments such as showAlphaSpent still override this option when supplied.
options(rpact.plot.show.alpha.spent = TRUE)
Sys.setenv(RPACT_PLOT_SHOW_ALPHA_SPENT = "true")rpact.plot.show.beta.spent
Environment variable: RPACT_PLOT_SHOW_BETA_SPENT
Default: FALSE
Controls whether beta-spent curves are included by default in the same plot contexts. Setting both alpha and beta spending to FALSE causes rpact to fall back to alpha-spent output and issue a warning.
options(rpact.plot.show.beta.spent = TRUE)
Sys.setenv(RPACT_PLOT_SHOW_BETA_SPENT = "true")rpact.plot.show.futility.on.pvalue.scale
Environment variable: RPACT_PLOT_SHOW_FUTILITY_ON_PVALUE_SCALE
Default: FALSE
Controls whether futility boundaries are shown by default on p-value scale boundary plots, provided that futility bounds are available for the design.
options(rpact.plot.show.futility.on.pvalue.scale = TRUE)
Sys.setenv(RPACT_PLOT_SHOW_FUTILITY_ON_PVALUE_SCALE = "true")Dataset and Numerical Calculation Options
rpact.dataset.stdev.calc.mode
Environment variable: RPACT_DATASET_STDEV_CALC_MODE
Default: "auto"
Controls how standard deviations are reconstructed from emmeans results in getDataset(). The internal comment lists the modes "auto", "sigma", "norm", and "t".
"sigma" uses the pooled standard deviation from the emmeans object. "t" uses a t-distribution based calculation when valid degrees of freedom are available. Other modes use the normal-distribution calculation, with special handling for non-lm model results.
options(rpact.dataset.stdev.calc.mode = "t")
Sys.setenv(RPACT_DATASET_STDEV_CALC_MODE = "t")rpact.multivar.dist.eps
Environment variable: RPACT_MULTIVAR_DIST_EPS
Default: 1e-05
Controls the epsilon tolerance used in multivariate Student t distribution calculations. rpact uses the configured value only if it is numeric and below 0.1.
options(rpact.multivar.dist.eps = 1e-06)
Sys.setenv(RPACT_MULTIVAR_DIST_EPS = "1e-06")Warnings and Messages
rpact.out.of.validated.bounds.message.type
Environment variable: RPACT_OUT_OF_VALIDATED_BOUNDS_MESSAGE_TYPE
Default: "warning"
Controls how rpact reports parameters that are outside validated bounds. With "warning" rpact emits a warning. With "message" it emits an informational message. Other values silence this particular notification path.
options(rpact.out.of.validated.bounds.message.type = "message")
Sys.setenv(RPACT_OUT_OF_VALIDATED_BOUNDS_MESSAGE_TYPE = "message")rpact.analyis.repeated.p.values.warnings.enabled
Environment variable: RPACT_ANALYIS_REPEATED_P_VALUES_WARNINGS_ENABLED
Default: TRUE
Controls whether rpact warns when repeated p-values are unavailable for certain inverse normal or group sequential designs. The option key intentionally uses the current spelling analyis.
options(rpact.analyis.repeated.p.values.warnings.enabled = FALSE)
Sys.setenv(RPACT_ANALYIS_REPEATED_P_VALUES_WARNINGS_ENABLED = "false")rpact.deprecated.message.time.function.kable
Environment variable: RPACT_DEPRECATED_MESSAGE_TIME_FUNCTION_KABLE
Default: not set
Stores the last time rpact warned about manual use of kable() for rpact result objects. rpact uses this timestamp to avoid repeating the deprecation message too frequently. This is primarily an internal throttle; users normally do not need to set it manually.
options(rpact.deprecated.message.time.function.kable = Sys.time())
Sys.setenv(RPACT_DEPRECATED_MESSAGE_TIME_FUNCTION_KABLE = as.character(Sys.time()))Startup and Validation Support
These options are mostly used by package startup and qualification workflows. They can be useful in automated validation environments, but most analyses do not need to change them.
rpact.startup.message.enabled
Environment variable: RPACT_STARTUP_MESSAGE_ENABLED
Default: TRUE
Controls whether rpact startup messages are enabled. The exported helper functions enableStartupMessages() and disableStartupMessages() update the R option and persist it through rpact’s option-saving mechanism.
options(rpact.startup.message.enabled = FALSE)
Sys.setenv(RPACT_STARTUP_MESSAGE_ENABLED = "false")rpact.startup.message.timestamp
Environment variable: RPACT_STARTUP_MESSAGE_TIMESTAMP
Default: not set
Stores the timestamp of the last startup message. rpact uses it to avoid showing the startup message again within a 72-hour window. The expected string begins with a timestamp like YYYY-MM-DD HH:MM:SS.
options(rpact.startup.message.timestamp = as.character(Sys.time()))
Sys.setenv(RPACT_STARTUP_MESSAGE_TIMESTAMP = "2026-06-17 09:00:00")Quick Reference
| Group | Option pattern |
|---|---|
| Summary formatting | rpact.summary.* |
| Output value formatting | rpact.output.format.* |
| Plot defaults | rpact.plot.* |
| Automatic markdown | rpact.auto.markdown.* |
| Dataset import helpers | rpact.dataset.* |
| Numerical tolerances | rpact.multivar.dist.* |
| Warnings and deprecation throttles | rpact.out.of.*, rpact.analyis.*, rpact.deprecated.* |
| Startup and validation | rpact.startup.*, rpact.system.* |
When both an environment variable and an R option are set, the environment variable wins. For project-local reproducibility, set these values near the start of the analysis script or in the execution environment before the script is launched.