# 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} 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_body(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', 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"
    )