tbl_hierarchical_rate_by_grade: AE Rates by Highest Toxicity Grade

In crane: Supplements the 'gtsummary' Package for Pharmaceutical Reporting

AE Rates by Highest Toxicity Grade

Description

A wrapper function for gtsummary::tbl_hierarchical() to calculate rates of highest toxicity grades with the options to add rows for grade groups and additional summary sections at each variable level.

Only the highest grade level recorded for each subject will be analyzed. Prior to running the function, ensure that the toxicity grade variable (grade) is a factor variable, with factor levels ordered lowest to highest.

Grades will appear in rows in the order of the factor levels given, with each grade group appearing prior to the first level in its group.

Usage

tbl_hierarchical_rate_by_grade(
  data,
  variables,
  denominator,
  by = NULL,
  id = "USUBJID",
  include_overall = everything(),
  statistic = everything() ~ "{n} ({p}%)",
  label = NULL,
  digits = NULL,
  sort = "alphanumeric",
  filter = NULL,
  grade_groups = list(),
  grades_exclude = NULL,
  keep_zero_rows = FALSE
)

## S3 method for class 'tbl_hierarchical_rate_by_grade'
add_overall(
  x,
  last = FALSE,
  col_label = "**Overall**  \nN = {style_number(N)}",
  statistic = NULL,
  digits = NULL,
  ...
)

Arguments

data	(data.frame) a data frame.
variables	(tidy-select) A character vector or tidy-selector of 3 columns in data specifying a system organ class variable, an adverse event terms variable, and a toxicity grade level variable, respectively.
denominator	(data.frame, integer) used to define the denominator and enhance the output. The argument is required for tbl_hierarchical() and optional for tbl_hierarchical_count(). The denominator argument must be specified when id is used to calculate event rates.
by	(tidy-select) a single column from data. Summary statistics will be stratified by this variable. Default is NULL.
id	(tidy-select) argument used to subset data to identify rows in data to calculate event rates in tbl_hierarchical().
include_overall	(tidy-select) Variables from variables for which an overall section at that hierarchy level should be computed. An overall section at the SOC variable level will have label "- Any adverse events -". An overall section at the AE term variable level will have label "- Overall -". If the grade level variable is included it has no effect. The default is everything().
statistic	(formula-list-selector) used to specify the summary statistics to display for all variables in tbl_hierarchical(). The default is everything() ~ "{n} ({p})".
label	(formula-list-selector) used to override default labels in hierarchical table, e.g. list(AESOC = "System Organ Class"). The default for each variable is the column label attribute, attr(., 'label'). If no label has been set, the column name is used.
digits	(formula-list-selector) specifies how summary statistics are rounded. Values may be either integer(s) or function(s). If not specified, default formatting is assigned via label_style_number() for statistics n and N, and label_style_percent(digits=1) for statistic p.
sort	(formula-list-selector, string) a named list, a list of formulas, a single formula where the list element is a named list of functions (or the RHS of a formula), or a string specifying the types of sorting to perform at each hierarchy level. If the sort method for any variable is not specified then the method will default to "descending". If a single unnamed string is supplied it is applied to all hierarchy levels. For each variable, the value specified must be one of: "alphanumeric" - at the specified hierarchy level, groups are ordered alphanumerically (i.e. A to Z) by variable_level text. "descending" - at the specified hierarchy level, count sums are calculated for each row and rows are sorted in descending order by sum. If sort is "descending" for a given variable and n is included in statistic for the variable then n is used to calculate row sums, otherwise p is used. If neither n nor p are present in x for the variable, an error will occur. Defaults to everything() ~ "descending".
filter	(expression) An expression that is used to filter rows of the table. Filter will be applied to the second variable (adverse event terms) specified via variables. See the Details section below for more information.
grade_groups	(⁠named list⁠) A named list of grade groups for which rates should be calculated. Grade groups must be mutually exclusive, i.e. each grade cannot be assigned to more than one grade group. Each grade group must be specified in the list as a character vector of the grades included in the grade group, named with the corresponding name of the grade group, e.g. "Grade 1-2" = c("1", "2").
grades_exclude	(character) A vector of grades to omit individual rows for when printing the table. These grades will still be used when computing overall totals and grade group totals. For example, to avoid duplication, if a grade group is defined as "Grade 5" = "5", the individual rows corresponding to grade 5 can be excluded by setting grades_exclude = "5".
keep_zero_rows	(logical) Whether rows containing zero rates across all columns should be kept. If FALSE, this filter will be applied prior to any filters specified via the filter argument which may still remove these rows. Defaults to FALSE.
x	(tbl_hierarchical_rate_by_grade) A gtsummary table of class 'tbl_hierarchical_rate_by_grade'.
last	(scalar logical) Logical indicator to display overall column last in table. Default is FALSE, which will display overall column first.
col_label	(string) String indicating the column label. Default is "**Overall** \nN = {style_number(N)}"
...	These dots are for future extensions and must be empty.

Details

When using the filter argument, the filter will be applied to the second variable from variables, i.e. the adverse event terms variable. If an AE does not meet the filtering criteria, the AE overall row as well as all grade and grade group rows within an AE section will be excluded from the table. Filtering out AEs does not exclude the records corresponding to these filtered out rows from being included in rate calculations for overall sections. If all AEs for a given SOC have been filtered out, the SOC will be excluded from the table. If all AEs are filtered out and the SOC variable is included in include_overall the ⁠- Any adverse events -⁠ section will still be kept.

See gtsummary::filter_hierarchical() for more details and examples.

Value

a gtsummary table of class "tbl_hierarchical_rate_by_grade".

Examples

theme_gtsummary_roche()
ADSL <- cards::ADSL
ADAE_subset <- cards::ADAE |>
  dplyr::filter(
    AESOC %in% unique(cards::ADAE$AESOC)[1:5],
    AETERM %in% unique(cards::ADAE$AETERM)[1:10]
  )

grade_groups <- list(
  "Grade 1-2" = c("1", "2"),
  "Grade 3-4" = c("3", "4"),
  "Grade 5" = "5"
)

# Example 1 ----------------------------------
tbl_hierarchical_rate_by_grade(
  ADAE_subset,
  variables = c(AEBODSYS, AEDECOD, AETOXGR),
  denominator = ADSL,
  by = TRTA,
  label = list(
    AEBODSYS = "MedDRA System Organ Class",
    AEDECOD = "MedDRA Preferred Term",
    AETOXGR = "Grade"
  ),
  grade_groups = grade_groups,
  grades_exclude = "5"
)

# Example 2 ----------------------------------
# Filter: Keep AEs with an overall prevalence of greater than 10%
tbl_hierarchical_rate_by_grade(
  ADAE_subset,
  variables = c(AEBODSYS, AEDECOD, AETOXGR),
  denominator = ADSL,
  by = TRTA,
  grade_groups = list("Grades 1-2" = c("1", "2"), "Grades 3-5" = c("3", "4", "5")),
  filter = sum(n) / sum(N) > 0.10
) |>
  add_overall(last = TRUE)

crane documentation built on Dec. 6, 2025, 5:08 p.m.