Add a Label Column to a Table

Source: R/add_label_column.R

Add a new column, label0, to the left of a {gtsummary} table's label column, and move part of the row content into it. This splits a single label column into two: label0 (the new label column) and label.

The contents of label0 are set by the value expression, which is evaluated against the table body. Any per-row content can be placed there, for example a stratum label on the first row only, a folded category, or a constant such as "n".

This is the layout tbl_shift() builds internally with strata_location = "new_column", provided here as a standalone step so other count and shift tables can reuse it instead of re-writing the modify_table_body() / alignment / indentation sequence.

add_label_column(
  x,
  value,
  header = "Value",
  label_header = NULL,
  .after = NULL,
  indent = 0L
)

Arguments

x

(gtsummary)
a gtsummary object.

value

(expression)
expression evaluated with dplyr::mutate() against x$table_body to fill the new label0 column. May reference any column in x$table_body (e.g. label, row_type) and dplyr::row_number(). NA rows render blank.

header

(string)
header for the new label0 column. Default is "Value".

label_header

(string)
header for the existing label column. Default is NULL, which leaves the current label header unchanged.

.after

(string)
name of the column after which label0 is placed. Default is NULL, which places label0 directly before label (the tbl_shift() layout, value column on the left). Use .after = "label" to place it on the right.

indent

(integer)
indentation applied to the label column via gtsummary::modify_indent(). Default is 0L, matching tbl_shift(), so value rows sit flush left once the stratum label moves to label0. Use NULL to leave the current label indentation unchanged (e.g. to keep a nested table's indentation).

Value

a gtsummary object with a label0 column added next to label.

See also

tbl_shift()

Examples

library(dplyr, warn.conflicts = FALSE)

tbl <- gtsummary::trial |>
  select(trt, grade) |>
  gtsummary::tbl_summary(by = trt, include = grade) |>
  gtsummary::remove_row_type(type = "header")

# place a stratum label on the first row, blank elsewhere
add_label_column(
  tbl,
  value = ifelse(dplyr::row_number() == 1L, "Grade", NA_character_),
  header = "Group"
)



  
Group
      Characteristic
      Drug A

N = 981		
      Drug B

N = 1021		
    
Grade
I
35 (36%)
33 (32%)


II
32 (33%)
36 (35%)


III
31 (32%)
33 (32%)
1 n (%)