ard_mvsummary: Multivariate ARD Summaries

In cards: Analysis Results Data

Multivariate ARD Summaries

Description

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

Usage

ard_mvsummary(data, ...)

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

Arguments

data	(data.frame) a data frame
...	Arguments passed to methods.
variables	(tidy-select) columns to include in summaries.
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_summary(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_fun	(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").
fmt_fn

Value

an ARD data frame of class 'card'

Examples

# example how to mimic behavior of `ard_summary()`
ard_mvsummary(
  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_mvsummary(
    variables = "AGE",
    statistic = list(AGE = list(means = grand_mean))
  )

cards documentation built on Dec. 2, 2025, 9:07 a.m.