Skip to contents

Regression model summary table

Source: R/tbl_regression.R
tbl_regression.Rd

Creates a table of regression model results. The table shows the estimate (a coefficient, or an odds, hazard or rate ratio when exponentiate = TRUE), its confidence interval and p-value for every term, with categorical variables shown one level per row and a reference row for the reference level. lm, glm and coxph models are tidied in base R; other model classes go through tidy_fun, or through broom::tidy() when broom is installed.

Usage

tbl_regression(
  x,
  label = NULL,
  exponentiate = FALSE,
  include = everything(),
  show_single_row = NULL,
  conf.level = 0.95,
  intercept = FALSE,
  estimate_fun = ifelse(exponentiate, label_style_ratio(), label_style_sigfig()),
  pvalue_fun = label_style_pvalue(digits = 1),
  tidy_fun = NULL,
  add_estimate_to_reference_rows = FALSE,
  conf.int = TRUE,
  ...
)

Arguments

x

(regression model)
A fitted model, e.g. from stats::lm(), stats::glm() or survival::coxph().

label

(formula-list)
Variable labels, e.g. list(age ~ "Age, years"). The default for each variable is its label attribute in the model data, or the variable name when there is none.

exponentiate

(scalar logical)
Whether to exponentiate the coefficient estimates and their confidence limits. Default is FALSE.

include

(selector)
Variables to include in the table. Default is everything().

show_single_row

(selector)
Dichotomous variables to show on a single row (the row of the non-reference level, labelled with the variable label) instead of a label row, a reference row and a level row. Default is NULL.

conf.level

(scalar numeric)
Confidence level of the interval. Default is 0.95.

intercept

(scalar logical)
Whether to include the intercept. Default is FALSE.

estimate_fun

(function)
Function that formats the estimate and the confidence limits. Default is label_style_sigfig() when exponentiate = FALSE and label_style_ratio() when it is TRUE.

pvalue_fun

(function)
Function that formats p-values. Default is label_style_pvalue(digits = 1).

tidy_fun

(function)
A tidier with the signature of broom::tidy(), function(x, conf.int, conf.level, exponentiate), returning a data frame with a term column and estimate, std.error, statistic, p.value, conf.low and conf.high columns. Default is NULL, which uses the built-in tidier for lm, glm and coxph models and broom::tidy() for anything else.

add_estimate_to_reference_rows

(scalar logical)
Whether to show the reference estimate (0, or 1 when exponentiated) on reference rows. Default is FALSE.

conf.int

(scalar logical)
Whether to compute and show the confidence interval. Default is TRUE.

...

Not used.

Value

A tbl_regression object, which is an ltsummary object with the model kept in x$inputs$x, the total N and, for models with events, N_event.

Variables, levels and labels

Terms are mapped to the variables of the model formula through the model matrix. A factor, character or logical variable is shown as a label row followed by one row per level, with the reference level of treatment contrasts (the first level; the last for contr.SAS and contr.sum) shown as a reference row with no estimate. Variables coded with Helmert, polynomial or custom contrasts keep the coefficient names as labels and have no reference row. Interaction terms are labelled by their parts joined with " * ". A term that spans several columns, such as splines::ns(age, 3), gets a label row and one row per column.

Confidence intervals

lm models use stats::confint() (t distribution). glm models use the profile-likelihood interval of stats::confint(), the interval broom::tidy() and gtsummary report; it is computed by stats from R 4.4 and by MASS before that. coxph models use Wald intervals from the variance matrix, again as broom does.

Why this is not an S3 generic

gtsummary's tbl_regression() is a generic with a default method. When both packages are attached, a method named tbl_regression.default in ltsummary would be found by gtsummary's generic as well, because R looks along the search path before the generic's own method registry. ltsummary therefore exposes one plain function; model classes without a built-in tidier are supported through tidy_fun.

See also

The tbl_regression() tutorial walks through the options; tbl_uvregression() builds one table of univariable models.

Other regression tables: add_glance_table(), add_global_p(), add_n_regression, add_nevent(), add_significance_stars(), add_vif(), combine_terms(), glance_fun_s3(), global_pvalue_fun(), tbl_uvregression()

Other table builders: tbl_continuous(), tbl_cross(), tbl_custom_summary(), tbl_likert(), tbl_merge(), tbl_stack(), tbl_strata(), tbl_strata_nested_stack(), tbl_summary(), tbl_survfit(), tbl_uvregression(), tbl_wide_summary()

Examples

# Example 1 ----------------------------------
# logistic regression with odds ratios
glm(response ~ age + grade, trial, family = binomial) |>
  tbl_regression(exponentiate = TRUE)


# Example 2 ----------------------------------
# linear regression, a variable on a single row, relabelled
lm(marker ~ age + trt + grade, trial) |>
  tbl_regression(show_single_row = trt, label = list(grade = "Tumor grade"))


# Example 3 ----------------------------------
# Cox model with hazard ratios and the number of events
if (requireNamespace("survival", quietly = TRUE)) {
  survival::coxph(survival::Surv(ttdeath, death) ~ age + grade, trial) |>
    tbl_regression(exponentiate = TRUE) |>
    add_nevent() |>
    bold_labels()
}