ARD to Calculate Categorical Occurrence Rates by Maximum Level Per Unique ID

Function calculates categorical variable level occurrences rates by maximum level per unique ID. Each variable in variables is evaluated independently and then results for all variables are stacked. Only the highest-ordered level will be counted for each unique ID. Unordered, non-numeric variables will be converted to factor and the default level order used for ordering.

ard_categorical_max(
  data,
  variables,
  id,
  by = dplyr::group_vars(data),
  statistic = everything() ~ c("n", "p", "N"),
  denominator = NULL,
  fmt_fn = NULL,
  stat_label = everything() ~ cards::default_stat_labels(),
  quiet = FALSE,
  ...
)

Arguments

data: (data.frame)
a data frame
variables: (tidy-select)
The categorical variables for which occurrence rates per unique ID (by maximum level) will be calculated.
id: (tidy-select)
Argument used to subset data to identify rows in data to calculate categorical variable level occurrence rates.
by: (tidy-select)
columns to tabulate by in the series of ARD function calls. Any rows with NA or NaN values are removed from all calculations.
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: (data.frame, integer)
An optional argument to change the denominator used for "N" and "p" statistic calculations. Defaults to NULL, in which case dplyr::distinct(data, dplyr::pick(all_of(c(id, by)))) is used for these calculations. See cards::ard_categorical() for more details on specifying denominators.
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").
quiet: (scalar logical)
Logical indicating whether to suppress additional messaging. Default is FALSE.
...: Arguments passed to methods.

Value

an ARD data frame of class 'card'

Examples

# Occurrence Rates by Max Level (Highest Severity) --------------------------
ard_categorical_max(
  cards::ADAE,
  variables = c(AESER, AESEV),
  id = USUBJID,
  by = TRTA,
  denominator = cards::ADSL |> dplyr::rename(TRTA = ARM)
)
#> `AESER`: "N" < "Y"
#> `AESEV`: "MILD" < "MODERATE" < "SEVERE"
#> {cards} data frame: 45 x 11
#>    group1 group1_level variable variable_level stat_name stat_label  stat
#> 1    TRTA      Placebo    AESER              N         n          n    69
#> 2    TRTA      Placebo    AESER              N         N          N    86
#> 3    TRTA      Placebo    AESER              N         p          % 0.802
#> 4    TRTA      Placebo    AESER              Y         n          n     0
#> 5    TRTA      Placebo    AESER              Y         N          N    86
#> 6    TRTA      Placebo    AESER              Y         p          %     0
#> 7    TRTA      Placebo    AESEV           MILD         n          n    36
#> 8    TRTA      Placebo    AESEV           MILD         N          N    86
#> 9    TRTA      Placebo    AESEV           MILD         p          % 0.419
#> 10   TRTA      Placebo    AESEV       MODERATE         n          n    26
#> ℹ 35 more rows
#> ℹ Use `print(n = ...)` to see more rows
#> ℹ 4 more variables: context, fmt_fn, warning, error