Add differences between groups

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_svysummary'
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() ~ "svy.t.test", all_dichotomous() ~ "emmeans", all_categorical(FALSE) ~ "svy.chisq.test").

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_svysummary(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. Default is list(c(all_continuous(), all_categorical(FALSE)) ~ label_style_sigfig(), all_categorical() ~ \(x) paste0(style_sigfig(x, scale = 100), "%"))

...

These dots are for future extensions and must be empty.

Value

a gtsummary table of class "tbl_summary"

Examples

# Example 1 ----------------------------------
survey::svydesign(~1, data = as.data.frame(Titanic), weights = ~Freq) |>
  tbl_svysummary(
    by = Survived,
    value = list(Class ~ "1st", Age = "Child"),
    include = c(Class, Age)
  ) |>
  add_difference()
#> The following warnings were returned during `add_difference()`:
#> ! For variable `Age` (`Survived`) and "estimate", "std.error", "conf.low",
#>   "conf.high", and "p.value" statistics: non-integer #successes in a binomial
#>   glm!
#> ! For variable `Class` (`Survived`) and "estimate", "std.error", "conf.low",
#>   "conf.high", and "p.value" statistics: non-integer #successes in a binomial
#>   glm!


  
Characteristic
      
No

N = 1,4901
      
Yes

N = 7111
      
Difference2
      
95% CI2
      
p-value2
    
Class
122 (8.2%)
203 (29%)
-15%
-85%, 54%
0.7
Age
52 (3.5%)
57 (8.0%)
-4.5%
-16%, 6.6%
0.4
1 n (%)
    
2 Least-squares mean difference
    
Abbreviation: CI = Confidence Interval
    

# Example 2 ----------------------------------
# Select two groups to compare when `by=` has 3+ levels
survey::svydesign(~1, data = trial, weights = ~1) |>
  tbl_svysummary(by = grade, include = c(age, marker), missing = "no") |>
  add_difference(levels = c("I", "III"))


  
Characteristic
      
I

N = 681
      
II

N = 681
      
III

N = 641
      
Difference2,3
      
95% CI2,3
      
p-value2,3
    
Age
47 (37, 56)
48 (37, 57)
47 (38, 58)
2.0
-3.2, 7.1
0.4
Marker Level (ng/mL)
0.98 (0.26, 1.65)
0.37 (0.14, 1.13)
0.62 (0.29, 1.68)
-0.07
-0.39, 0.24
0.7
1 Median (Q1, Q3)
    
2 Design-based t-test
    
3 Difference: I - III
    
Abbreviation: CI = Confidence Interval