This function creates a listing from a data frame. Common uses rely on few pre-processing steps, such as ensuring unique values in key columns or split by rows or columns. They are described in the note section.
(data.frame)
a data frame containing the data to be displayed in the listing.
(named list)
split_by_rows: Named list of arguments that are passed to gtsummary::tbl_split_by_rows().
split_by_columns: Named list of arguments that are passed to gtsummary::tbl_split_by_columns().
add_blank_rows: Named list of arguments that are passed to crane::add_blank_rows().
add_blank_rows() is applied after table splitting and applied to each table individually.
Variable names passed in these named lists must be character vectors; tidyselect/unquoted syntax is not accepted.
(tbl_listing or list)
a tbl_listing object or a list of tbl_listing objects.
(tidy-select)
columns to highlight for duplicate values. If NULL, nothing is done.
(string)
string to use for blank values. Defaults to NA. It should not be changed.
Common pre-processing steps for the data frame that may be common:
Unique values - this should be enforced in pre-processing by users.
NA values - they are not printed by default in {gtsummary}. You can make them explicit if
they need to be displayed in the listing. See example 3.
Sorting key columns and moving them to the front. See the examples pre-processing.
Split by rows - you can split the data frame by rows by using split_by_rows parameter. You can use the same
parameters used in gtsummary::tbl_split_by_rows(). See example 4.
Split by columns - you can split the data frame by columns by using split_by_columns parameter. Use the same
parameters from gtsummary::tbl_split_by_rows(). See example 5.
# Load the trial dataset
trial_data <- trial |>
dplyr::select(trt, age, marker, stage) |>
dplyr::filter(stage %in% c("T2", "T3")) |>
dplyr::slice_head(n = 2, by = c(trt, stage)) |> # downsampling
dplyr::arrange(trt, stage) |> # key columns should be sorted
dplyr::relocate(trt, stage) # key columns should be first
# Example 1 --------------------------------
out <- tbl_listing(trial_data)
out
#> Error in add_expr_after(calls = x, add_after = names(insert_expr_after[y]), expr = insert_expr_after[[y]], new_name = paste0("user_added", y)): Argument `add_after` must be one of "gt", "fmt_missing", "cols_merge",
#> "cols_align", "indent", "fmt", "tab_style_bold", "tab_style_italic",
#> "cols_label", "tab_spanner", "tab_footnote", "abbreviations",
#> "tab_source_note", and "text_transform".
out |> remove_duplicate_keys(keys = "trt")
#> Error in add_expr_after(calls = x, add_after = names(insert_expr_after[y]), expr = insert_expr_after[[y]], new_name = paste0("user_added", y)): Argument `add_after` must be one of "gt", "fmt_missing", "cols_merge",
#> "cols_align", "indent", "fmt", "tab_style_bold", "tab_style_italic",
#> "cols_label", "tab_spanner", "tab_footnote", "abbreviations",
#> "tab_source_note", and "text_transform".
# Example 2 --------------------------------
# make NAs explicit
trial_data_na <- trial_data |>
mutate(across(everything(), ~ tidyr::replace_na(labelled::to_character(.), "-")))
tbl_listing(trial_data_na)
#> Error in add_expr_after(calls = x, add_after = names(insert_expr_after[y]), expr = insert_expr_after[[y]], new_name = paste0("user_added", y)): Argument `add_after` must be one of "gt", "fmt_missing", "cols_merge",
#> "cols_align", "indent", "fmt", "tab_style_bold", "tab_style_italic",
#> "cols_label", "tab_spanner", "tab_footnote", "abbreviations",
#> "tab_source_note", and "text_transform".
# Example 3 --------------------------------
# Add blank rows for first key column
lst <- tbl_listing(trial_data_na, add_blank_rows = list(variable_level = "trt"))
lst
#> Error in add_expr_after(calls = x, add_after = names(insert_expr_after[y]), expr = insert_expr_after[[y]], new_name = paste0("user_added", y)): Argument `add_after` must be one of "gt", "fmt_missing", "cols_merge",
#> "cols_align", "indent", "fmt", "tab_style_bold", "tab_style_italic",
#> "cols_label", "tab_spanner", "tab_footnote", "abbreviations",
#> "tab_source_note", and "text_transform".
# Can add them also manually in post-processing
lst |> add_blank_rows(row_numbers = seq(2))
#> Error in add_expr_after(calls = x, add_after = names(insert_expr_after[y]), expr = insert_expr_after[[y]], new_name = paste0("user_added", y)): Argument `add_after` must be one of "gt", "fmt_missing", "cols_merge",
#> "cols_align", "indent", "fmt", "tab_style_bold", "tab_style_italic",
#> "cols_label", "tab_spanner", "tab_footnote", "abbreviations",
#> "tab_source_note", and "text_transform".
# Example 4 --------------------------------
# Split by rows
list_lst <- tbl_listing(trial_data, split_by_rows = list(row_numbers = c(2, 3, 4)))
list_lst[[2]]
Chemotherapy Treatment
T Stage
Age
Marker Level (ng/mL)
# Example 5 --------------------------------
# Split by columns
show_header_names(lst)
#> Column Name Header
#> trt "Chemotherapy Treatment"
#> stage "T Stage"
#> age "Age"
#> marker "Marker Level (ng/mL)"
#>
#> * These values may be dynamically placed into headers (and other locations).
#> ℹ Review the `modify_header()` (`?gtsummary::modify_header()`) help for
#> examples.
grps <- list(c("trt", "stage", "age"), c("trt", "stage", "marker"))
list_lst <- tbl_listing(trial_data, split_by_columns = list(groups = grps))
list_lst[[2]]
Chemotherapy Treatment
T Stage
Marker Level (ng/mL)
# Example 6 --------------------------------
# Split by rows and columns
list_lst <- tbl_listing(trial_data,
split_by_rows = list(row_numbers = c(2, 3, 4)), split_by_columns = list(groups = grps)
)
length(list_lst) # 8 tables are flatten out
#> [1] 8
list_lst[[2]]
Chemotherapy Treatment
T Stage
Marker Level (ng/mL)
# Example 7 --------------------------------
# Hide duplicate columns in post-processing
out <- list_lst |>
remove_duplicate_keys(keys = c("trt", "stage"))
out[[2]]
Chemotherapy Treatment
T Stage
Marker Level (ng/mL)