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).

or equivalently

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.

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} contains a list of {gt} calls that are applied when printed. For example, here are the first few associated with a tbl_summary() table.

library(gtsummary)
tbl_summary(trial)$gt_calls %>% head(n = 4)
#> $gt
#> gt::gt(data = x$table_body)
#> 
#> $cols_align
#> gt::cols_align(align = 'center') %>% gt::cols_align(align = 'left', columns = gt::vars(label))
#> 
#> $fmt_missing
#> gt::fmt_missing(columns = gt::everything(), missing_text = '')
#> 
#> $tab_style_text_indent
#> gt::tab_style(style = gt::cell_text(indent = gt::px(10), align = 'left'),locations = gt::cells_data(columns = gt::vars(label),rows = row_type != 'label'))

You may append additional {gt} calls to this list using 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', 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"
)