Hierarchical Table

Source: R/tbl_hierarchical.R

[Experimental]
This is an preview of this function. There will be changes in the coming releases, and changes will not undergo a formal deprecation cycle.

Use these functions to generate hierarchical tables.

  • tbl_hierarchical(): Calculates rates of events (e.g. adverse events) utilizing the denominator and id arguments to identify the rows in data to include in each rate calculation. If variables contains more than one variable and the last variable in variables is an ordered factor, then rates of events by highest level will be calculated.

  • tbl_hierarchical_count(): Calculates counts of events utilizing all rows for each tabulation.

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.

variables

(tidy-select)
character vector or tidy-selector of columns in data used to create a hierarchy. Hierarchy will be built with variables in the order given.

id

(tidy-select)
argument used to subset data to identify rows in data to calculate event rates in tbl_hierarchical().

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.

include

(tidy-select)
variables from hierarchy for which summary statistics should be returned (on the variable label rows) Including the last element of hierarchy has no effect since each level has its own row for this variable. 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})".

overall_row

(scalar logical)
whether an overall summary row should be included at the top of the table. The default is FALSE.

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.

Value

a gtsummary table of class "tbl_hierarchical" (for tbl_hierarchical()) or "tbl_hierarchical_count" (for tbl_hierarchical_count()).

Overall Row

An overall row can be added to the table as the first row by specifying overall_row = TRUE. Assuming that each row in data corresponds to one event record, this row will count the overall number of events recorded when used in tbl_hierarchical_count(), or the overall number of patients recorded with any event when used in tbl_hierarchical().

A label for this overall row can be specified by passing an '..ard_hierarchical_overall..' element in label. Similarly, the rounding for statistics in the overall row can be modified using the digits argument, again referencing the '..ard_hierarchical_overall..' name.

Examples

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

# Example 1 - Event Rates --------------------
tbl_hierarchical(
  data = ADAE_subset,
  variables = c(AESOC, AETERM),
  by = TRTA,
  denominator = cards::ADSL |> mutate(TRTA = ARM),
  id = USUBJID,
  digits = everything() ~ list(p = 1),
  overall_row = TRUE,
  label = list(..ard_hierarchical_overall.. = "Any Adverse Event")
)



  
Primary System Organ Class

    Reported Term for the Adverse Event		
      Placebo

N = 861		
      Xanomeline High Dose

N = 841		
      Xanomeline Low Dose

N = 841		
    
Any Adverse Event
26 (30.2%)
42 (50.0%)
40 (47.6%)
CARDIAC DISORDERS
2 (2.3%)
3 (3.6%)
0 (0.0%)
    ATRIOVENTRICULAR BLOCK SECOND DEGREE
2 (2.3%)
3 (3.6%)
0 (0.0%)
GASTROINTESTINAL DISORDERS
9 (10.5%)
4 (4.8%)
5 (6.0%)
    DIARRHOEA
9 (10.5%)
4 (4.8%)
5 (6.0%)
GENERAL DISORDERS AND ADMINISTRATION SITE CONDITIONS
8 (9.3%)
25 (29.8%)
24 (28.6%)
    APPLICATION SITE ERYTHEMA
3 (3.5%)
15 (17.9%)
12 (14.3%)
    APPLICATION SITE PRURITUS
6 (7.0%)
22 (26.2%)
22 (26.2%)
SKIN AND SUBCUTANEOUS TISSUE DISORDERS
9 (10.5%)
14 (16.7%)
15 (17.9%)
    ERYTHEMA
9 (10.5%)
14 (16.7%)
15 (17.9%)
1 n (%)
    

# Example 2 - Rates by Highest Severity ------
tbl_hierarchical(
  data = ADAE_subset |> mutate(AESEV = factor(AESEV, ordered = TRUE)),
  variables = c(AESOC, AESEV),
  by = TRTA,
  id = USUBJID,
  denominator = cards::ADSL |> mutate(TRTA = ARM),
  include = AESEV,
  label = list(AESEV = "Highest Severity")
)
#> ℹ Denominator set by "TRTA" column in `denominator` data frame.



  
Primary System Organ Class

    Highest Severity		
      Placebo

N = 861		
      Xanomeline High Dose

N = 841		
      Xanomeline Low Dose

N = 841		
    
CARDIAC DISORDERS





    MILD
1 (1.2%)
1 (1.2%)
0 (0%)
    MODERATE
0 (0%)
2 (2.4%)
0 (0%)
    SEVERE
1 (1.2%)
0 (0%)
0 (0%)
GASTROINTESTINAL DISORDERS





    MILD
9 (10%)
2 (2.4%)
5 (6.0%)
    MODERATE
0 (0%)
2 (2.4%)
0 (0%)
    SEVERE
0 (0%)
0 (0%)
0 (0%)
GENERAL DISORDERS AND ADMINISTRATION SITE CONDITIONS





    MILD
7 (8.1%)
12 (14%)
12 (14%)
    MODERATE
1 (1.2%)
13 (15%)
10 (12%)
    SEVERE
0 (0%)
0 (0%)
2 (2.4%)
SKIN AND SUBCUTANEOUS TISSUE DISORDERS





    MILD
5 (5.8%)
10 (12%)
7 (8.3%)
    MODERATE
4 (4.7%)
4 (4.8%)
8 (9.5%)
    SEVERE
0 (0%)
0 (0%)
0 (0%)
1 n (%)
    

# Example 3 - Event Counts -------------------
tbl_hierarchical_count(
  data = ADAE_subset,
  variables = c(AESOC, AETERM, AESEV),
  by = TRTA,
  overall_row = TRUE,
  label = list(..ard_hierarchical_overall.. = "Total Number of AEs")
)



  
Primary System Organ Class

    Reported Term for the Adverse Event

        Severity/Intensity		
      Placebo1
      Xanomeline High Dose1
      Xanomeline Low Dose1
    
Total Number of AEs
38
88
84
CARDIAC DISORDERS
2
4
0
    ATRIOVENTRICULAR BLOCK SECOND DEGREE
2
4
0
        MILD
1
2
0
        MODERATE
0
2
0
        SEVERE
1
0
0
GASTROINTESTINAL DISORDERS
10
4
7
    DIARRHOEA
10
4
7
        MILD
10
2
7
        MODERATE
0
2
0
GENERAL DISORDERS AND ADMINISTRATION SITE CONDITIONS
13
58
53
    APPLICATION SITE ERYTHEMA
3
23
20
        MILD
3
16
9
        MODERATE
0
7
8
        SEVERE
0
0
3
    APPLICATION SITE PRURITUS
10
35
33
        MILD
8
21
21
        MODERATE
2
14
11
        SEVERE
0
0
1
SKIN AND SUBCUTANEOUS TISSUE DISORDERS
13
22
24
    ERYTHEMA
13
22
24
        MILD
8
16
12
        MODERATE
5
6
12
1 n