gtsummary

The {gtsummary} package provides an elegant and flexible way to create publication-ready and reproducible analytical tables. The tables summarize data sets, regression models, and more. The code is concise and the tables are highly customizable. Data frames can be summarized with any function, e.g. mean(), median(), even user-written functions. Regression models are summarized and include the reference rows for categorical variables. Common regression models, such as logistic regression and Cox proportional hazards regression, are automatically identified and the tables are pre-filled with appropriate column headers (i.e. Odds Ratio, and Hazard Ratio). The package uses {broom} to perform initial tidying of the regression models, which means there is broad support for many types of regression models.

{gtsummary} uses the {gt} package enabling each table to be tailored to your preferences. If you label your data (which I recommend!), the labels will be used in the table output. With {gtsummary} and {labelled} data, you get beautifully formatted, ready-to-share tables in a single line of code! Check out the examples below, and review the vignettes for a detailed exploration of the output options.

Installation

The {gtsummary} package was written as a companion to the {gt} package from RStudio, and it is recommended to install both {gt} and {gtsummary}. The {gt} package is not automatically installed. If {gt} is not installed, knitr::kable() will be used to produce the summary tables. You can install {gtsummary} and {gt} with the following code.

1. Install {gtsummary}

   install.packages("gtsummary")

2. Install {gt} from GitHub (recommended)

   install.packages("remotes")
   remotes::install_github("rstudio/gt")

   • If you experience issues installing {gt} on Windows, install Rtools from CRAN, restart R, and attempt installation again.

Install the development version of {gtsummary} with:

remotes::install_github("ddsjoberg/gtsummary")

Examples

The {gtsummary} vignettes/tutorials contain detailed examples.

Summary Table

library(gtsummary)
t1 <-
  tbl_summary(
    data = trial[c("trt", "age", "grade", "response")],
    by = trt
  ) %>%
  add_p() 

Regression Models

mod1 <- 
  glm(response ~ trt + age + grade, trial, family = binomial(link = "logit"))

t2 <- tbl_regression(mod1, exponentiate = TRUE)

Other Tables

Side-by-side regression model results from tbl_merge()

Survival Estimates from tbl_survival()

Print Engine

{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 kable is less full featured compared to summary tables produced with {gt}. For example, kable summary tables do not include indentation, footnotes, and spanning header rows.

Contributing

Please note that the {gtsummary} project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms. A big thank you to all contributors!
@ablack3, @ahinton-mmc, @ddsjoberg, @emilyvertosick, @jennybc, @jflynn264, @karissawhiting, @margarethannum, @michaelcurry1123, @sammo3182, and @zabore