Skip to contents

Hierarchical ARD Statistics

Source: R/ard_hierarchical.R
ard_hierarchical.Rd

[Experimental]
Performs hierarchical or nested tabulations, e.g. tabulates AE terms nested within AE system organ class.

  • ard_hierarchical() includes summaries for the last variable listed in the variables argument, nested within the other variables included.

  • ard_hierarchical_count() includes summaries for all variables listed in the variables argument each summary nested within the preceding variables, e.g. variables=c(AESOC, AEDECOD) summarizes AEDECOD nested in AESOC, and also summarizes the counts of AESOC.

Usage 

ard_hierarchical(data, ...)

ard_hierarchical_count(data, ...)

# S3 method for class 'data.frame'
ard_hierarchical(
  data,
  variables,
  by = dplyr::group_vars(data),
  statistic = everything() ~ c("n", "N", "p"),
  denominator = NULL,
  fmt_fn = NULL,
  stat_label = everything() ~ default_stat_labels(),
  id = NULL,
  ...
)

# S3 method for class 'data.frame'
ard_hierarchical_count(
  data,
  variables,
  by = dplyr::group_vars(data),
  fmt_fn = NULL,
  stat_label = everything() ~ default_stat_labels(),
  ...
)

Arguments

data

(data.frame)
a data frame

...

Arguments passed to methods.

variables

(tidy-select)
variables to perform the nested/hierarchical tabulations within.

by

(tidy-select)
variables to perform tabulations by. All combinations of the variables specified here appear in results. Default is dplyr::group_vars(data).

statistic

(formula-list-selector)
a named list, a list of formulas, or a single formula where the list element one or more of c("n", "N", "p", "n_cum", "p_cum") (on the RHS of a formula).

denominator

(string, data.frame, integer)
Specify this argument to change the denominator, e.g. the "N" statistic. Default is 'column'. See below for details.

fmt_fn

(formula-list-selector)
a named list, a list of formulas, or a single formula where the list element is a named list of functions (or the RHS of a formula), e.g. list(mpg = list(mean = \(x) round(x, digits = 2) |> as.character())).

stat_label

(formula-list-selector)
a named list, a list of formulas, or a single formula where the list element is either a named list or a list of formulas defining the statistic labels, e.g. everything() ~ list(n = "n", p = "pct") or everything() ~ list(n ~ "n", p ~ "pct").

id

(tidy-select)
an optional argument used to assert there are no duplicates within the c(id, variables) columns.

Value

an ARD data frame of class 'card'

Denominators

By default, the ard_categorical() function returns the statistics "n", "N", and "p", where little "n" are the counts for the variable levels, and big "N" is the number of non-missing observations. The default calculation for the percentage is merely p = n/N.

However, it is sometimes necessary to provide a different "N" to use as the denominator in this calculation. For example, in a calculation of the rates of various observed adverse events, you may need to update the denominator to the number of enrolled subjects.

In such cases, use the denominator argument to specify a new definition of "N", and subsequently "p". The argument expects one of the following inputs:

  • a string: one of "column", "row", or "cell".

    • "column", the default, returns percentages where the sum is equal to one within the variable after the data frame has been subset with by/strata.

    • "row" gives 'row' percentages where by/strata columns are the 'top' of a cross table, and the variables are the rows. This is well-defined for a single by or strata variable, and care must be taken when there are more to ensure the the results are as you expect.

    • "cell" gives percentages where the denominator is the number of non-missing rows in the source data frame.

  • a data frame. Any columns in the data frame that overlap with the by/strata columns will be used to calculate the new "N".

  • an integer. This single integer will be used as the new "N"

  • a structured data frame. The data frame will include columns from by/strata. The last column must be named "...ard_N...". The integers in this column will be used as the updated "N" in the calculations.

Examples 

ard_hierarchical(
  data = ADAE |>
    dplyr::slice_tail(n = 1L, by = c(USUBJID, TRTA, AESOC, AEDECOD)),
  variables = c(AESOC, AEDECOD),
  by = TRTA,
  id = USUBJID,
  denominator = ADSL |> dplyr::rename(TRTA = ARM)
)
#> {cards} data frame: 2178 x 13
#>    group1 group1_level group2 group2_level variable variable_level stat_name
#> 1    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL F…         n
#> 2    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL F…         N
#> 3    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL F…         p
#> 4    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL F…         n
#> 5    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL F…         N
#> 6    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL F…         p
#> 7    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL H…         n
#> 8    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL H…         N
#> 9    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL H…         p
#> 10   TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIOVEN…         n
#>    stat_label  stat
#> 1           n     1
#> 2           N    86
#> 3           % 0.012
#> 4           n     0
#> 5           N    86
#> 6           %     0
#> 7           n     1
#> 8           N    86
#> 9           % 0.012
#> 10          n     1
#> ℹ 2168 more rows
#> ℹ Use `print(n = ...)` to see more rows
#> ℹ 4 more variables: context, fmt_fn, warning, error

ard_hierarchical_count(
  data = ADAE,
  variables = c(AESOC, AEDECOD),
  by = TRTA
)
#> {cards} data frame: 726 x 13
#>    group1 group1_level group2 group2_level variable variable_level stat_name
#> 1    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL F…         n
#> 2    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL F…         n
#> 3    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIAL H…         n
#> 4    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIOVEN…         n
#> 5    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      ATRIOVEN…         n
#> 6    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      BRADYCAR…         n
#> 7    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      BUNDLE B…         n
#> 8    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      BUNDLE B…         n
#> 9    TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      CARDIAC …         n
#> 10   TRTA      Placebo  AESOC    CARDIAC …  AEDECOD      CARDIAC …         n
#>    stat_label stat
#> 1           n    1
#> 2           n    0
#> 3           n    2
#> 4           n    1
#> 5           n    2
#> 6           n    4
#> 7           n    1
#> 8           n    2
#> 9           n    0
#> 10          n    1
#> ℹ 716 more rows
#> ℹ Use `print(n = ...)` to see more rows
#> ℹ 4 more variables: context, fmt_fn, warning, error