cards (version 0.3.0)

ard_complex: Complex ARD Summaries

Description

Function is similar to ard_continuous(), but allows for more complex summaries. While ard_continuous(statistic) only allows for a univariable function, ard_complex(statistic) can handle more complex data summaries.

Usage

ard_complex(data, ...)
# S3 method for data.frame
ard_complex(
  data,
  variables,
  by = dplyr::group_vars(data),
  strata = NULL,
  statistic,
  fmt_fn = NULL,
  stat_label = everything() ~ default_stat_labels(),
  ...
)

Value

an ARD data frame of class 'card'

Arguments

data

(data.frame)
a data frame

...

Arguments passed to methods.

variables

(tidy-select)
columns to include in summaries. Default is everything().

by, strata

(tidy-select)
columns to tabulate by/stratify by for summary statistic calculation. Arguments are similar, but with an important distinction:

by: results are calculated for all combinations of the columns specified, including unobserved combinations and unobserved factor levels.

strata: results are calculated for all observed combinations of the columns specified.

Arguments may be used in conjunction with one another.

statistic

(formula-list-selector)
The form of the statistics argument is identical to ard_continuous(statistic) argument, except the summary function must accept the following arguments:

• x: a vector

• data: the data frame that has been subset such that the by/strata columns and rows in which "variable" is NA have been removed.

• full_data: the full data frame

• by: character vector of the by variables

• strata: character vector of the strata variables It is unlikely any one function will need all of the above elements, and it's recommended the function passed accepts ... so that any unused arguments will be properly ignored. The ... also allows this function to perhaps be updated in the future with more passed arguments. For example, if one needs a second variable from the data frame, the function inputs may look like: foo(x, data, ...)

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(mean = "Mean", sd = "SD") or everything() ~ list(mean ~ "Mean", sd ~ "SD").

Examples

# example how to mimic behavior of `ard_continuous()`
ard_complex(
  ADSL,
  by = "ARM",
  variables = "AGE",
  statistic = list(AGE = list(mean = \(x, ...) mean(x)))
)

# return the grand mean and the mean within the `by` group
grand_mean <- function(data, full_data, variable, ...) {
  list(
    mean = mean(data[[variable]], na.rm = TRUE),
    grand_mean = mean(full_data[[variable]], na.rm = TRUE)
  )
}

ADSL |>
  dplyr::group_by(ARM) |>
  ard_complex(
    variables = "AGE",
    statistic = list(AGE = list(means = grand_mean))
  )