# 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"
    )