Tutorial: tbl_regression

Last Updated: January 13, 2020

Introduction

The tbl_regression() function takes a regression model object in R and returns a formatted table of regression model results that is publication-ready. It is a simple way to summarize and present your analysis results using R! Like tbl_summary(), tbl_regression() creates highly customizable analytic tables with sensible defaults.

This vignette will walk a reader through the tbl_regression() function, and the various functions available to modify and make additions to an existing formatted regression table.

animated

Behind the scenes: tbl_regression() uses broom::tidy() to perform the initial model formatting, and can accommodate many different model types (e.g. lm(), glm(), survival::coxph(), survival::survreg() and more are vetted tidy models that are known to work with our package). It is also possible to specify your own function to tidy the model results if needed.

To start, a quick note on the {magrittr} package’s pipe function, %>%. By default the pipe operator puts whatever is on the left hand side of %>% into the first argument of the function on the right hand side. The pipe function can be used to make the code relating to tbl_regression() easier to use, but it is not required. Here are a few examples of how %>% translates into typical R notation.

x %>% f() is equivalent to f(x)
x %>% f(y) is equivalent to f(x, y)
y %>% f(x, .) is equivalent to f(x, y)
z %>% f(x, y, arg = .) is equivalent to f(x, y, arg = z)

Setup

Before going through the tutorial, install {gtsummary} and {gt}.

install.packages("gtsummary")
remotes::install_github("rstudio/gt", ref = gtsummary::gt_sha)

library(gtsummary)
library(dplyr)

Example data set

In this vignette we’ll be using the trial data set which is included in the {gtsummary package}.

Basic Usage

The default output from tbl_regression() is meant to be publication ready.

# build logistic regression model
m1 = glm(response ~ age + stage + grade, trial, family = binomial(link = "logit"))

# view raw model results
summary(m1)$coefficients
#>                Estimate Std. Error    z value   Pr(>|z|)
#> (Intercept) -1.42184501 0.65711995 -2.1637526 0.03048334
#> age          0.01935700 0.01149333  1.6841945 0.09214409
#> stageT2     -0.56765609 0.44328677 -1.2805618 0.20034764
#> stageT3     -0.09619949 0.45702787 -0.2104893 0.83328578
#> stageT4     -0.26797315 0.45364355 -0.5907130 0.55471272
#> gradeII     -0.17315419 0.40255106 -0.4301422 0.66709221
#> gradeIII     0.04434059 0.38892269  0.1140087 0.90923087
# format results
tbl_regression(m1, exponentiate = TRUE)
Characteristic OR1 95% CI1 p-value
Age, yrs 1.02 1.00, 1.04 0.092
T Stage
T1
T2 0.57 0.23, 1.34 0.2
T3 0.91 0.37, 2.22 0.8
T4 0.76 0.31, 1.85 0.6
Grade
I
II 0.84 0.38, 1.85 0.7
III 1.05 0.49, 2.25 >0.9

1 OR = Odds Ratio, CI = Confidence Interval

Note the sensible defaults with this basic usage (that can be customized later):

Customize Output

There are four primary ways to customize the output of the regression model table.

  1. Modify tbl_regression() function input arguments
  2. Add additional data/information to a summary table with add_*() functions
  3. Modify summary table appearance with the {gtsummary} functions
  4. Modify table appearance with {gt} package functions

Modifying function arguments

The tbl_regression() function includes many input options for modifying the appearance.

label            modify the variable labels printed in the table.  
exponentiate     exponentiate model coefficients.  
include          names of variables to include in output. Default is all variables.  
show_single_row  By default, categorical variables are printed on multiple rows.  
                 If a variable is dichotomous (e.g. Yes/No) and you wish to print 
                 the regression coefficient on a single row, include the variable name(s) here. 
conf.level       confidence level of confidence interval.  
intercept        logical argument indicates whether to include the intercept in output.  
estimate_fun     function to round and format coefficient estimates.  
pvalue_fun       function to round and format p-values.  
tidy_fun         function to specify/customize tidier function

{gtsummary} functions to add information

The {gtsummary} package has built-in functions for adding to results from tbl_regression(). The following functions add columns and/or information to the regression table.

add_global_p()  adds the global p-value for a categorical variables   
add_nevent()    adds the number of observed events to the results object    

{gtsummary} functions to format table

The {gtsummary} package comes with functions specifically made to modify and format summary tables.

bold_labels()       bold variable labels  
bold_levels()       bold variable levels  
italicize_labels()  italicize variable labels  
italicize_levels()  italicize variable levels  
bold_p()            bold significant p-values  

{gt} functions to format table

The {gt} package is packed with many great functions for modifying table output—too many to list here. Review the package’s website for a full listing. https://gt.rstudio.com/index.html

To use the {gt} package functions with {gtsummary} tables, the regression table must first be converted into a {gt} object. To this end, use the as_gt() function after modifications have been completed with {gtsummary} functions.

m1 %>%
  tbl_regression(exponentiate = TRUE) %>%
  as_gt() %>%
  <gt functions>

Example

There are formatting options available, such as adding bold and italics to text. In the example below,
- Variable labels are bold
- Levels of categorical levels are italicized
- Global p-values for T Stage and Grade are reported - P-values less than 0.10 are bold - Large p-values are rounded to two decimal places
- Coefficients are exponentiated to give odds ratios
- Odds ratios are rounded to 2 or 3 significant figures

Characteristic OR1 95% CI1 p-value
Age, yrs 1.020 0.997, 1.043 0.092
T Stage 0.60
T1
T2 0.567 0.234, 1.342
T3 0.908 0.367, 2.220
T4 0.765 0.310, 1.854
Grade 0.85
I
II 0.841 0.379, 1.849
III 1.045 0.486, 2.246

1 OR = Odds Ratio, CI = Confidence Interval

Advanced Customization

When you print the output from the tbl_regression() function into the R console or into an R markdown, there are default printing functions that are called in the background: print.tbl_regression() and knit_print.tbl_regression(). The true output from tbl_regression() is a named list, but when you print the object, a formatted version of .$table_body is displayed. All formatting and modifications are made using the {gt} package by default.

tbl_regression(m1) %>% names()
#> [1] "table_body"   "table_header" "n"            "model_obj"    "inputs"      
#> [6] "call_list"    "gt_calls"     "kable_calls"  "fmt_fun"

These are the additional data stored in the tbl_regression() output list.

table_body   data frame with summary statistics  
n            N included in model  
model_obj    the model object passed to `tbl_regression`  
call_list    named list of each function called on the `tbl_regression` object  
inputs       inputs from the `tbl_regression()` function call  
gt_calls     named list of {gt} function calls  
kable_calls  named list of function calls to be applied before knitr::kable()  

gt_calls is a named list of saved {gt} function calls. The {gt} calls are run when the object is printed to the console or in an R markdown document. Here’s an example of the first few calls saved with tbl_regression():

tbl_regression(m1) %>% purrr::pluck("gt_calls") %>% head(n = 5)
#> $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 = '')
#> 
#> $fmt_missing_ref
#> gt::fmt_missing(columns = gt::vars(estimate, ci), rows = row_ref == TRUE, 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'))

The {gt} functions are called in the order they appear, always beginning with the gt() function.

If the user does not want a specific {gt} function to run, any {gt} call can be excluded in the as_gt() function. For example, the tbl_regression() call creates many named {gt} function calls: gt, cols_align, fmt_missing, fmt_missing_ref, tab_style_text_indent, cols_label, cols_hide, fmt, tab_footnote. Any one of these can be excluded. In this example, the default footnote will be excluded from the output.

tbl_regression(m1, exponentiate = TRUE) %>%
  as_gt(include = -tab_footnote)
Characteristic OR 95% CI p-value
Age, yrs 1.02 1.00, 1.04 0.092
T Stage
T1
T2 0.57 0.23, 1.34 0.2
T3 0.91 0.37, 2.22 0.8
T4 0.76 0.31, 1.85 0.6
Grade
I
II 0.84 0.38, 1.85 0.7
III 1.05 0.49, 2.25 >0.9

Univariate Regression

The tbl_uvregression() produces a table of univariate regression results. The function is a wrapper for tbl_regression(), and as a result, accepts nearly identical function arguments. The function’s results can be modified in similar ways to tbl_regression() and the results reported inline similarly to tbl_regression().