Add differences between groups

Adds the difference between the two groups of a table created with tbl_summary(by =), with its confidence interval and a p-value when the method provides one: the difference in means for continuous variables, the difference in proportions for dichotomous variables, and the standardized mean difference for categorical variables.

Usage

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)
A table created with tbl_summary() with a by variable: two levels, or more when levels names the two compared.

test

(formula-list)
The method for each variable, e.g. list(all_continuous() ~ "t.test", all_dichotomous() ~ "prop.test", all_categorical(FALSE) ~ "smd"). See the section below for the defaults and ?tests for the available methods and how to write your own.

group

(selector)
Column identifying the pairs or groups of correlated observations, used by the paired tests. Default is NULL. See tests for the methods that use it.

adj.vars

(selector)
Variables to adjust for in an ANCOVA. With adj.vars, the default method for continuous variables is "ancova" and the estimate is headed "Adjusted Difference". Default is NULL.

test.args

(formula-list)
Additional arguments passed to the tests, as a named list per variable. To assume equal variances in every t-test, use test.args = all_tests("t.test") ~ list(var.equal = TRUE).

conf.level

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

levels

(vector)
The two by levels to compare, the difference being levels[1] minus levels[2]. Required when by has more than two levels; with two levels it can flip the direction. Default is NULL, the two levels in their order.

include

(selector)
Variables to compute a p-value for. Default is everything().

pvalue_fun

(function)
Function that rounds and formats the p-values. Default is label_style_pvalue(). The function takes a numeric vector and returns a character vector, e.g. pvalue_fun = label_style_pvalue(digits = 2).

estimate_fun

(formula-list)
Functions that format the difference and its confidence limits, per variable. The default formats differences in proportions as percentages and everything else with label_style_sigfig(). A single function is not accepted; use a formula, e.g. estimate_fun = everything() ~ label_style_number(digits = 2).

...

Not used.

Value

A table of class c("tbl_summary", "ltsummary") with estimate, conf.low and p.value columns; conf.low shows the merged interval. The other statistics the method returns (std.error, statistic, parameter, conf.high) are stored as hidden columns.

Details

On a tbl_hierarchical() table, add_difference() adds the difference between the event rates of two by levels instead; see add_difference_hierarchical.

test argument

The default method depends on the summary type of the variable:

• "t.test" for continuous variables, or "ancova" when adj.vars is given;

• "prop.test" for dichotomous variables;

• "smd" for categorical variables.

There is no default for paired data. When group is specified, name the method for every variable, e.g. test = everything() ~ "paired.t.test". See ?tests for the methods available in add_difference() and what each computes.

See also

add_p() for p-values alone, add_ci() for an interval around each statistic, tests for the methods.

Other add statistics: add_ci(), add_difference_row(), add_n(), add_overall(), add_p(), add_p_continuous, add_q(), add_stat(), add_stat_label(), tests

Examples

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

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

# Example 3 ----------------------------------
# the Hodges-Lehmann difference in location, and a standardized mean
# difference for a dichotomous variable
trial |>
  tbl_summary(by = trt, include = c(age, marker, response), missing = "no") |>
  add_difference(
    test = list(all_continuous() ~ "wilcox.test", response ~ "smd"),
    estimate_fun = all_continuous() ~ label_style_number(digits = 2),
    conf.level = 0.9
  )

# Example 4 ----------------------------------
# two of three groups, in the order given
trial |>
  tbl_summary(
    by = grade,
    include = c(age, marker),
    statistic = all_continuous() ~ "{mean} ({sd})",
    missing = "no"
  ) |>
  add_difference(levels = c("I", "III"))