Join a comparison column computed elsewhere onto a summary table

Adds one column to a table from hv_tbl_summary(), holding a value you computed yourself for each variable: typically the standardized difference %summarytable printed, which comes from the %stddiff macro and is not the number hv_tbl_summary()'s compare = "smd" gives. hvtiRpropensity::ps_stddiff() is the R port of %stddiff; this function is how its output reaches the table, without hvtiRtables depending on hvtiRpropensity.

Usage

hv_tbl_compare(tbl, values, label)

Arguments

tbl

A gtsummary object, normally from hv_tbl_summary().

values

Named character vector: variable name -> the text to show on that variable's first row.

label

The column header, e.g. "Std. Diff. (%)".

Value

tbl with the column added and its hv_trailing attribute extended by the new column.

Details

Each value goes on its variable's first row, as %summarytable laid it out: beside the label of a categorical variable, not on every level. The column is placed rightmost, after any compare column, so compare = "pvalue" followed by this function puts the p-value and the standardized difference side by side. Call it again for a further column. hv_man_table() shows the column directly; The manuscript style shows it too, from the table's hv_trailing attribute, which this function extends.

The values are shown exactly as given, so format them first, for example sprintf("%.1f", 100 * d) for a difference as a percentage. A variable missing from values is left blank.

Common mistakes

"values must be a character vector named by variable ..." Numbers are not formatted for you. Convert them with sprintf() or format(), and name each element by the variable's column name, the name in groups, not its label.

"values names variable(s) not in the table: ..." A name that matches no variable would silently show nothing. Usually a typo, or a variable dropped from groups.

See also

hv_tbl_summary(), whose compare argument computes a p-value and gtsummary's generic standardized difference.

Examples

tbl <- hv_tbl_summary(
  gtsummary::trial, by = "trt",
  groups = list(Demography = c("age", "grade")),
  continuous = "age", categorical = "grade",
  compare = "pvalue", show_variable = FALSE
)
# Standardized differences computed elsewhere, e.g. by
# hvtiRpropensity::ps_stddiff(), as proportions.
d <- c(age = 0.031, grade = 0.120)
tbl <- hv_tbl_compare(
  tbl, stats::setNames(sprintf("%.1f", 100 * d), names(d)),
  label = "Std. Diff. (%)"
)
hv_man_table(tbl)
Characteristic
No.
Overall  
N = 200
No.
Drug A  
N = 98
No.
Drug B  
N = 102
p-value
Std. Diff. (%)
Demography
Age
189
47 [33, 63]
91
46 [32, 63]
98
48 [34, 63]
.7
3.1
Grade
.9
12.0
I
200
68 (34)
98
35 (36)
102
33 (32)
II
200
68 (34)
98
32 (33)
102
36 (35)
III
200
64 (32)
98
31 (32)
102
33 (32)