Global Options

Announcement!

Use of the more full featured set_gtsummary_theme() function is preferred over global options. See the function help file for detailed examples, and the themes vignette for instruction on creating your own theme. Support for global options may be removed in a future release.

Global Options

There are various global options that can be set for {gtsummary}. Here we review a complete list of options available to users.

Styling Estimates

The {gtsummary} package includes various default functions for styling and formatting statistics. These defaults can be modified with global options.

p-values

P-values are reported throughout {gtsummary} tables. The default function to style p-values is style_pvalue(), where large p-values are rounded to one decimal place. Use the gtsummary.pvalue_fun option to change the function that styles p-values. For example, to report large p-values rounded to two decimal places rather that one, change the default function to style_pvalue(x, digits = 2).

options(gtsummary.pvalue_fun = function(x) style_pvalue(x, digits = 2))

percentages

In tbl_summary(), the default function for styling percentages is style_percent(). If you’d like to update the default, for example, because you’d prefer percentages rounded to one decimal place, you may include the gtsummary.tbl_summary.percent_fun option.

options(gtsummary.tbl_summary.percent_fun = function(x) sprintf(x * 100, fmt='%#.1f'))

survival estimates

Similar to the above options, the default function for styling estimates in tbl_survival() can be modified with gtsummary.tbl_survival.estimate_fun.

Printing

{gtsummary} uses the {gt} package to print all summary tables. In addition to supporting {gt}, the {gtsummary} package works well with knitr::kable(). This is particularly useful when outputting documents to Microsoft Word. If the {gt} package is not installed, {gtsummary} will fall back to knitr::kable(). To explicitly set the printing engine, set the option in the script or in the user- or project R profile, .Rprofile.

options(gtsummary.print_engine = "kable")

or

options(gtsummary.print_engine = "gt")

Output from {gt} is more full-featured compared to a summary table produced with {kable}. For example, {gt} summary tables can include indentation, footnotes, and spanning header rows.

Format {gt} Tables

Tables created with the {gt} package are incredibly customizable. You can set an option to apply additional {gt} formatting to all {gtsummary} tables. Every table returned from {gtsummary} maybe converted to a {gt} object with as_gt().

You may append additional {gt} calls the gtsummary.as_gt.addl_cmds option—with the following caveats:

  1. Only include {gt} functions you want to apply to all tables. For example, a {gt} function that changes the font size would be appropriate. A table-specific header may not.

  2. All {gt} functions must be referenced using the double-colon prefix (i.e. gt::foo()). These functions will execute when the {gt} library is not loaded.

  3. Do not include the data= argument in any {gt} function call. The function will appear in a chained sequence of {gt} calls with the %>% operator. The data argument is taken from the previous function in the sequence.

In the example below, the font size and cell padding are reduced globally.

options(gtsummary.as_gt.addl_cmds = "gt::tab_options(table.font.size = 'small', data_row.padding = gt::px(1))")

Default tests in add_p()

To update the default tests in the add_p() function, you can set the following global options.

Option Name Tests Modified
gtsummary.add_p.test.continuous_by2 continuous variables with 2-level by variable
gtsummary.add_p.test.continuous continuous variables with 3- or more level by variable
gtsummary.add_p.test.categorical categorical/dichotomous variables
gtsummary.add_p.test.categorical.low_count categorical/dichotomous variables with minimum expected count <5 in one cell
gtsummary.add_p.test.categorical.group_by2 categorical/dichotomous grouped/correlated variables with 2-level by variable
gtsummary.add_p.test.continuous.group_by2 continuous grouped/correlated variables with 2-level by variable

For example, to report the t-test and one-way ANOVA for continuous variables, use the following options:

options(
  gtsummary.add_p.test.continuous_by2 = "t.test",
  gtsummary.add_p.test.continuous = "aov"
)