Hierarchical table

tbl_hierarchical() and tbl_hierarchical_count() build nested summary tables, e.g. adverse events by system organ class and preferred term. tbl_hierarchical() reports subject rates: within each cell, {n} counts the distinct values of id (a subject with two events of one term counts once), {N} comes from denominator, and {p} is their ratio. tbl_hierarchical_count() reports plain event counts: {n} counts rows, and denominator only decorates the headers.

Rows are ordered depth first, siblings by the byte order of their level text; only observed combinations appear, and a combination observed in one by column shows zero cells in the others. When the last hierarchy variable of a rate table is an ordered factor and there are at least two variables, each subject is tabulated once per section, at its highest level; tbl_hierarchical_count() counts an ordered factor like an unordered one (gtsummary errors there).

Usage

tbl_hierarchical(
  data,
  variables,
  id,
  denominator,
  by = NULL,
  include = everything(),
  statistic = everything() ~ "{n} ({p}%)",
  overall_row = FALSE,
  label = NULL,
  digits = NULL
)

tbl_hierarchical_count(
  data,
  variables,
  denominator = NULL,
  by = NULL,
  include = everything(),
  overall_row = FALSE,
  statistic = everything() ~ "{n}",
  label = NULL,
  digits = NULL
)

Arguments

data

(data.frame)
A data frame with one row per event.

variables

(selector)
The hierarchy, outermost first, e.g. variables = c(AESOC, AEDECOD).

id

(selector)
The column identifying the subjects, e.g. id = USUBJID. Rates count each subject once per cell.

denominator

(data.frame or integer)
The denominators of the rates: a data frame with one row per subject (its rows per by level are the column denominators), or a single integer used for every column. Optional in tbl_hierarchical_count(), where it only fills the header statistics.

by

(selector)
A single column of data; one table column per level found in data. Default is NULL.

include

(selector)
The hierarchy variables that get summary rows. Default is everything(); the last variable is always included, and the levels of an excluded variable become plain label rows.

statistic

(formula-list)
The cell statistic per hierarchy variable. tbl_hierarchical() accepts {n}, {N} and {p} with default "{n} ({p}%)"; tbl_hierarchical_count() accepts {n} with default "{n}". The overall row is addressed as "..ard_hierarchical_overall..".

overall_row

(scalar logical)
Whether to add a first row summarizing all events (tbl_hierarchical_count()) or the subjects with any event (tbl_hierarchical()). Default is FALSE.

label

(formula-list)
Variable labels, keyed by the hierarchy variables and "..ard_hierarchical_overall..". The defaults are the label attributes or the column names, and "Number of patients with event" / "Total number of events" for the overall row.

digits

(formula-list)
How the statistics are rounded, as in tbl_summary() categorical variables.

Value

A table of class c("tbl_hierarchical", "ltsummary") or c("tbl_hierarchical_count", "ltsummary").

See also

sort_hierarchical(), filter_hierarchical(); add_overall() works on both classes.

Other hierarchical tables: add_difference_hierarchical, filter_hierarchical(), sort_hierarchical()

Examples

ae <- data.frame(
  id = c(1L, 1L, 1L, 2L, 2L, 3L, 5L, 5L, 6L),
  trt = c("A", "A", "A", "A", "A", "A", "B", "B", "B"),
  soc = c("Nervous", "Nervous", "Gastro", "Nervous", "Gastro",
          "Gastro", "Nervous", "Gastro", "Gastro"),
  term = c("Headache", "Headache", "Nausea", "Dizziness", "Nausea",
           "Vomiting", "Headache", "Nausea", "Nausea")
)
enrolled <- data.frame(id = 1:8, trt = rep(c("A", "B"), each = 4))

# Example 1 ----------------------------------
# subjects with events, by system organ class and preferred term
tbl_hierarchical(ae, variables = c(soc, term), by = trt,
                 denominator = enrolled, id = id, overall_row = TRUE)

# Example 2 ----------------------------------
# event counts, no denominator
tbl_hierarchical_count(ae, variables = c(soc, term), by = trt)