gtsummary themes

It’s possible to set themes in {gtsummary}. The themes control many aspects of how a table is printed. Function defaults can be controlled with themes, as well as other aspects that are not modifiable with function arguments.

The {gtsummary} package comes with a few themes, and we welcome user-contributed themes as well! Our focus is tables that are ready for publication and encourage themes that assist in that process; for example, the theme_gtsummary_journal(journal = "jama") theme sets defaults that align with the published guidelines from the Journal of the American Medical Association—JAMA. The defaults in {gtsummary} were written to align with the reporting guidelines for European Urology, The Journal of Urology, Urology, and the British Journal of Urology International.

Setting Themes

To set a theme, use the set_gtsummary_theme() function. Themes must be set before you create the {gtsummary} tables. Let’s take a look at the default table, comparing data between treatment groups.

Default Theme

library(gtsummary); library(gt); library(dplyr)

trial %>%
  select(trt, age, grade) %>%
  tbl_summary(by = trt) %>%
  add_p() %>%
  add_stat_label()
Characteristic Drug A, N = 98 Drug B, N = 102 p-value1
Age, yrs, median (IQR) 46 (37, 59) 48 (39, 56) 0.7
Unknown 7 4
Grade, n (%) 0.9
I 35 (36%) 33 (32%)
II 32 (33%) 36 (35%)
III 31 (32%) 33 (32%)

1 Statistical tests performed: Wilcoxon rank-sum test; chi-square test of independence

JAMA Theme

Now, the same code with the JAMA theme.

set_gtsummary_theme(theme_gtsummary_journal(journal = "jama"))
#> Setting `JAMA` theme
Characteristic Drug A, N = 98 Drug B, N = 102 p-value1
Age, yrs, median (IQR) 46 (37 - 59) 48 (39 - 56) 0.72
Unknown 7 4
Grade, n (%) 0.87
I 35 (36) 33 (32)
II 32 (33) 36 (35)
III 31 (32) 33 (32)

1 Statistical tests performed: Wilcoxon rank-sum test; chi-square test of independence

By setting the theme, we were able to change the default formatting for the p-value and add a dash between the 25th and 75th percentiles.

JAMA + Compact Theme

Themes can be stacked as well. In the example below, the JAMA theme and the compact theme (reduces font size and cell padding) are both called and both themes are utilized.

set_gtsummary_theme(theme_gtsummary_journal(journal = "jama"))
#> Setting `JAMA` theme
set_gtsummary_theme(theme_gtsummary_compact())
#> Setting `Compact` theme
Characteristic Drug A, N = 98 Drug B, N = 102 p-value1
Age, yrs, median (IQR) 46 (37 - 59) 48 (39 - 56) 0.72
Unknown 7 4
Grade, n (%) 0.87
I 35 (36) 33 (32)
II 32 (33) 36 (35)
III 31 (32) 33 (32)

1 Statistical tests performed: Wilcoxon rank-sum test; chi-square test of independence

Clear all previously set themes using the reset_gtsummary_theme()

reset_gtsummary_theme()

Writing Themes

Theme Structure

There are many parts of a {gtsummary} table that may be controlled with theme elements. To construct a personalized theme, create a named list of at least one theme element. Here’s an example of a theme that modifies the function that styles p-values and updates the default statistics reported in tbl_summary().

my_theme <-   
  list(
    "pkgwide-fn:pvalue_fun" = function(x) style_pvalue(x, digits = 2),
    "pkgwide-fn:prependpvalue_fun" = function(x) style_pvalue(x, digits = 2, prepend_p = TRUE),
    "tbl_summary-str:continuous_stat" = "{median} ({p25} - {p75})",
    "tbl_summary-str:categorical_stat" = "{n} ({p})"
  )

Once you create the theme, you can set it just like one of the included themes.

set_gtsummary_theme(my_theme)

Theme Elements

Each theme element follows a naming structure: "<function name>-<input type>:<description>". The function name is the function the change applies to, the input type specifies class or type of the theme element, and the description is brief text characterizing the theme element.

Theme elements fall into two categories. The first is modifying internal behavior of the functions that is not directly controllable by function arguments.

Theme Element Description Example
Package-wide

pkgwide-str:theme_name

 optional name of theme

"My Personal Theme"

pkgwide-str:print_engine

 string indicating the default print engine

"kable"

pkgwide-fn:pvalue_fun

 function to style p-values throughout package

function(x) style_pvalue(x, digits = 2)

pkgwide-fn:prependpvalue_fun

 function to style p-values throughout package that include a "p" prefix, e.g. "p<0.001" or "p=0.12"

function(x) style_pvalue(x, digits = 2, prepend_p = TRUE)

pkgwide-lgl:quiet

 logical indicating whether to suppress messages or not

NA
as_gt

as_gt-lst:addl_cmds

 list expression of gt-package commands inserted in the `as_gt()` call. Do not include the `data=` argument. Expression is inserted after the named call, e.g. after "tab_spanner" in the example.

list(tab_spanner = rlang::expr(gt::tab_options(table.font.size = 'small')))
as_flextable.gtsummary

as_flextable.gtsummary-lst:addl_cmds

 list of expressions of flextable-package commands inserted in the `as_flextable()` call. Do not include the `data=` argument. Expression is inserted after the named call, e.g. after "autofit" in the example.

list(autofit = list(rlang::expr(flextable::font(fontname = "Bodoni 72", part = "all")), rlang::expr(flextable::fontsize(size = 8, part = "all"))))
as_kable_extra

as_kable_extra-lst:addl_cmds

 list expression of kableExtra-package commands inserted in the `as_kable_extra()` call. Do not include the `data=` argument. Expression is inserted after the named call.

NA
tbl_summary

tbl_summary-fn:percent_fun

 function to style percentages

function(x) style_percent(x)

tbl_summary-fn:N_fun

 function to style integers

function(x) sprintf("%.0f", x)

tbl_summary-str:continuous_stat

 glue string defining the default continuous summary statistics to display

"{mean} ({sd})"

tbl_summary-str:categorical_stat

 glue string defining the default categorical and dichotomous summary statistics to display

"{n} / {N} ({p}%)"
add_p.tbl_summary

add_p.tbl_summary-attr:test.continuous_by2

 default test for continuous variables with a 2-level by variable

"t.test"

add_p.tbl_summary-attr:test.continuous

 default test for continuous variables with a 3- or more level by variable

"aov"

add_p.tbl_summary-attr:test.categorical

 default test for categorical/dichotomous variables

"chisq.test"

add_p.tbl_summary-attr:test.categorical.low_count

 default test for categorical/dichotomous variables with minimum expected count <5

"fisher.test"

add_p.tbl_summary-attr:test.categorical.group_by2

 default test for categorical/dichotomous grouped/correlated variables with a 2-level by variable

"lme4"

add_p.tbl_summary-attr:test.continuous.group_by2

 default test for continuous grouped/correlated variables with a 2-level by variable

"lme4"
tbl_regression

tbl_regression-str:coef_header

 String setting the default term for the beta coefficient column header

ifelse(exponentiate == TRUE, "exp(coef)", "coef")

The second type of theme elements set function argument defaults. The values of these theme elements must align with the functions’ accepted input for the argument.

Theme Element
tbl_summary

tbl_summary-arg:label, tbl_summary-arg:statistic, tbl_summary-arg:digits, tbl_summary-arg:type, tbl_summary-arg:value, tbl_summary-arg:missing, tbl_summary-arg:missing_text, tbl_summary-arg:percent, tbl_summary-arg:sort
add_p.tbl_summary

add_p.tbl_summary-arg:test, add_p.tbl_summary-arg:pvalue_fun
add_stat_label

add_stat_label-arg:location
add_q

add_q-arg:method, add_q-arg:pvalue_fun
add_p.tbl_cross

add_p.tbl_cross-arg:test, add_p.tbl_cross-arg:pvalue_fun
tbl_survfit

tbl_survfit-arg:statistic
tbl_regression

tbl_regression-arg:conf.level, tbl_regression-arg:estimate_fun, tbl_regression-arg:pvalue_fun, tbl_regression-arg:tidy_fun