Filter Stacked Hierarchical ARDs

This function is used to filter stacked hierarchical ARDs.

For the purposes of this function, we define a "variable group" as a combination of ARD rows grouped by the combination of all their variable levels, but excluding any by variables.

Usage

filter_ard_hierarchical(x, filter, keep_empty = FALSE)

Arguments

x: (card)
a stacked hierarchical ARD of class 'card' created using ard_stack_hierarchical() or ard_stack_hierarchical_count().
filter: (expression)
an expression that is used to filter variable groups of the hierarchical ARD. See the Details section below.
keep_empty: (scalar logical)
Logical argument indicating whether to retain summary rows corresponding to hierarchy sections that have had all rows filtered out. Default is FALSE.

Value

an ARD data frame of class 'card'

Details

The filter argument can be used to filter out variable groups of a hierarchical ARD which do not meet the requirements provided as an expression. Variable groups can be filtered on the values of any of the possible statistics (n, p, and N) provided they are included at least once in the ARD, as well as the values of any by variables.

To illustrate how the function works, consider the typical example below where the AE summaries are provided by treatment group.

ADAE |>
  dplyr::filter(AESOC == "GASTROINTESTINAL DISORDERS",
                AEDECOD %in% c("VOMITING", "DIARRHOEA")) |>
  ard_stack_hierarchical(
    variables = c(AESOC, AEDECOD),
    by = TRTA,
    denominator = ADSL |> dplyr::rename(TRTA = ARM),
    id = USUBJID
  )

SOC / AE	Placebo	Xanomeline High Dose	Xanomeline Low Dose
GASTROINTESTINAL DISORDERS	11 (13%)	10 (12%)	8 (9.5%)
DIARRHOEA	9 (10%)	4 (4.8%)	5 (6.0%)
VOMITING	3 (3.5%)	7 (8.3%)	3 (3.6%)

Filters are applied to the summary statistics of the innermost variable in the hierarchy—AEDECOD in this case. If any of the summary statistics meet the filter requirement for any of the treatment groups, the entire row is retained. For example, if filter = n >= 9 were passed, the criteria would be met for DIARRHOEA as the Placebo group observed 9 AEs and as a result the summary statistics for the other treatment groups would be retained as well. Conversely, no treatment groups' summary statistics satisfy the filter requirement for VOMITING so all rows associated with this AE would be removed.

In addition to filtering on individual statistic values, filters can be applied across the treatment groups (i.e. across all by variable values) by using aggregate functions such as sum() and mean(). A value of filter = sum(n) >= 18 retains AEs where the sum of the number of AEs across the treatment groups is greater than or equal to 18.

If ard_stack_hierarchical(overall=TRUE) was run, the overall column is not considered in any filtering.

If ard_stack_hierarchical(over_variables=TRUE) was run, any overall statistics are kept regardless of filtering.

Some examples of possible filters:

filter = n > 5: keep AEs where one of the treatment groups observed more than 5 AEs
filter = n == 2 & p < 0.05: keep AEs where one of the treatment groups observed exactly 2 AEs and one of the treatment groups observed a proportion less than 5%
filter = sum(n) >= 4: keep AEs where there were 4 or more AEs observed across the treatment groups
filter = mean(n) > 4 | n > 3: keep AEs where the mean number of AEs is 4 or more across the treatment groups or one of the treatment groups observed more than 3 AEs
filter = any(n > 2 & TRTA == "Xanomeline High Dose"): keep AEs where the "Xanomeline High Dose" treatment group observed more than 2 AEs

Examples

# create a base AE ARD
ard <- ard_stack_hierarchical(
  ADAE,
  variables = c(AESOC, AEDECOD),
  by = TRTA,
  denominator = ADSL |> dplyr::rename(TRTA = ARM),
  id = USUBJID
)

# Example 1 ----------------------------------
# Keep AEs from TRTA groups where more than 3 AEs are observed across the group
filter_ard_hierarchical(ard, sum(n) > 3)
#> {cards} data frame: 477 x 13
#>    group1 group1_level group2 group2_level variable variable_level stat_name
#> 1    TRTA      Placebo   <NA>                 AESOC      CARDIAC …         n
#> 2    TRTA      Placebo   <NA>                 AESOC      CARDIAC …         N
#> 3    TRTA      Placebo   <NA>                 AESOC      CARDIAC …         p
#> 4    TRTA      Placebo   <NA>                 AESOC      GASTROIN…         n
#> 5    TRTA      Placebo   <NA>                 AESOC      GASTROIN…         N
#> 6    TRTA      Placebo   <NA>                 AESOC      GASTROIN…         p
#> 7    TRTA      Placebo   <NA>                 AESOC      GENERAL …         n
#> 8    TRTA      Placebo   <NA>                 AESOC      GENERAL …         N
#> 9    TRTA      Placebo   <NA>                 AESOC      GENERAL …         p
#> 10   TRTA      Placebo   <NA>                 AESOC      INFECTIO…         n
#>    stat_label  stat
#> 1           n    13
#> 2           N    86
#> 3           % 0.151
#> 4           n    17
#> 5           N    86
#> 6           % 0.198
#> 7           n    21
#> 8           N    86
#> 9           % 0.244
#> 10          n    16
#> ℹ 467 more rows
#> ℹ Use `print(n = ...)` to see more rows
#> ℹ 4 more variables: context, fmt_fn, warning, error

# Example 2 ----------------------------------
# Keep AEs where at least one level in the TRTA group has more than 3 AEs observed
filter_ard_hierarchical(ard, n > 3)
#> {cards} data frame: 228 x 13
#>    group1 group1_level group2 group2_level variable variable_level stat_name
#> 1    TRTA      Placebo   <NA>                 AESOC      CARDIAC …         n
#> 2    TRTA      Placebo   <NA>                 AESOC      CARDIAC …         N
#> 3    TRTA      Placebo   <NA>                 AESOC      CARDIAC …         p
#> 4    TRTA      Placebo   <NA>                 AESOC      GASTROIN…         n
#> 5    TRTA      Placebo   <NA>                 AESOC      GASTROIN…         N
#> 6    TRTA      Placebo   <NA>                 AESOC      GASTROIN…         p
#> 7    TRTA      Placebo   <NA>                 AESOC      GENERAL …         n
#> 8    TRTA      Placebo   <NA>                 AESOC      GENERAL …         N
#> 9    TRTA      Placebo   <NA>                 AESOC      GENERAL …         p
#> 10   TRTA      Placebo   <NA>                 AESOC      INFECTIO…         n
#>    stat_label  stat
#> 1           n    13
#> 2           N    86
#> 3           % 0.151
#> 4           n    17
#> 5           N    86
#> 6           % 0.198
#> 7           n    21
#> 8           N    86
#> 9           % 0.244
#> 10          n    16
#> ℹ 218 more rows
#> ℹ Use `print(n = ...)` to see more rows
#> ℹ 4 more variables: context, fmt_fn, warning, error

# Example 3 ----------------------------------
# Keep AEs that have an overall prevalence of greater than 5%
filter_ard_hierarchical(ard, sum(n) / sum(N) > 0.05)
#> {cards} data frame: 198 x 13
#>    group1 group1_level group2 group2_level variable variable_level stat_name
#> 1    TRTA      Placebo   <NA>                 AESOC      CARDIAC …         n
#> 2    TRTA      Placebo   <NA>                 AESOC      CARDIAC …         N
#> 3    TRTA      Placebo   <NA>                 AESOC      CARDIAC …         p
#> 4    TRTA      Placebo   <NA>                 AESOC      GASTROIN…         n
#> 5    TRTA      Placebo   <NA>                 AESOC      GASTROIN…         N
#> 6    TRTA      Placebo   <NA>                 AESOC      GASTROIN…         p
#> 7    TRTA      Placebo   <NA>                 AESOC      GENERAL …         n
#> 8    TRTA      Placebo   <NA>                 AESOC      GENERAL …         N
#> 9    TRTA      Placebo   <NA>                 AESOC      GENERAL …         p
#> 10   TRTA      Placebo   <NA>                 AESOC      NERVOUS …         n
#>    stat_label  stat
#> 1           n    13
#> 2           N    86
#> 3           % 0.151
#> 4           n    17
#> 5           N    86
#> 6           % 0.198
#> 7           n    21
#> 8           N    86
#> 9           % 0.244
#> 10          n    12
#> ℹ 188 more rows
#> ℹ Use `print(n = ...)` to see more rows
#> ℹ 4 more variables: context, fmt_fn, warning, error

Usage

Arguments

Value

Details

See also

Examples