add_difference.tbl_summary: Add differences between groups

In gtsummary: Presentation-Ready Data Summary and Analytic Result Tables

Add differences between groups

Description

Adds difference to tables created by tbl_summary(). The difference between two groups (typically mean or rate difference) is added to the table along with the difference's confidence interval and a p-value (when applicable).

Usage

## S3 method for class 'tbl_summary'
add_difference(
  x,
  test = NULL,
  group = NULL,
  adj.vars = NULL,
  test.args = NULL,
  conf.level = 0.95,
  levels = NULL,
  include = everything(),
  pvalue_fun = label_style_pvalue(digits = 1),
  estimate_fun = list(c(all_continuous(), all_categorical(FALSE)) ~ label_style_sigfig(),
    all_dichotomous() ~ label_style_sigfig(scale = 100, suffix = "%"), all_tests("smd")
    ~ label_style_sigfig()),
  ...
)

Arguments

x	(tbl_summary) table created with tbl_summary()
test	(formula-list-selector) Specifies the tests/methods to perform for each variable, e.g. list(all_continuous() ~ "t.test", all_dichotomous() ~ "prop.test", all_categorical(FALSE) ~ "smd"). See below for details on default tests and ?tests for details on available tests and creating custom tests.
group	(tidy-select) Variable name of an ID or grouping variable. The column can be used to calculate p-values with correlated data. Default is NULL. See tests for methods that utilize the group argument.
adj.vars	(tidy-select) Variables to include in adjusted calculations (e.g. in ANCOVA models). Default is NULL.
test.args	(formula-list-selector) Containing additional arguments to pass to tests that accept arguments. For example, add an argument for all t-tests, use test.args = all_tests("t.test") ~ list(var.equal = TRUE).
conf.level	(numeric) a scalar in the interval ⁠(0, 1)⁠ indicating the confidence level. Default is 0.95
levels	(vector) a length-two vector of the tbl_summary(by=) levels to compare. The difference is calculated as levels[1] minus levels[2]. This argument is required when the by variable has more than two levels, and allows the user to select which two groups to compare. When by has exactly two levels, this argument is optional and can be used to flip the direction of the difference (e.g. levels[2] minus levels[1]). Default is NULL.
include	(tidy-select) Variables to include in output. Default is everything().
pvalue_fun	(function) Function to round and format p-values. Default is label_style_pvalue(). The function must have a numeric vector input, and return a string that is the rounded/formatted p-value (e.g. pvalue_fun = label_style_pvalue(digits = 2)).
estimate_fun	(formula-list-selector) List of formulas specifying the functions to round and format differences and confidence limits.
...	These dots are for future extensions and must be empty.

Value

a gtsummary table of class "tbl_summary"

Examples

# Example 1 ----------------------------------
trial |>
  select(trt, age, marker, response, death) %>%
  tbl_summary(
    by = trt,
    statistic =
      list(
        all_continuous() ~ "{mean} ({sd})",
        all_dichotomous() ~ "{p}%"
      ),
    missing = "no"
  ) |>
  add_n() |>
  add_difference()

# Example 2 ----------------------------------
# ANCOVA adjusted for grade and stage
trial |>
  select(trt, age, marker, grade, stage) %>%
  tbl_summary(
    by = trt,
    statistic = list(all_continuous() ~ "{mean} ({sd})"),
    missing = "no",
    include = c(age, marker, trt)
  ) |>
  add_n() |>
  add_difference(adj.vars = c(grade, stage))

# Example 3 ----------------------------------
# Select two groups to compare when `by=` has 3+ levels
trial |>
  tbl_summary(
    by = grade,
    statistic = all_continuous() ~ "{mean} ({sd})",
    include = c(age, marker),
    missing = "no"
  ) |>
  add_difference(levels = c("I", "III"))

gtsummary documentation built on Aug. 26, 2026, 9:07 a.m.