Title:	Analysis Results Data
Version:	0.6.1
Description:	Construct CDISC (Clinical Data Interchange Standards Consortium) compliant Analysis Results Data objects. These objects are used and re-used to construct summary tables, visualizations, and written reports. The package also exports utilities for working with these objects and creating new Analysis Results Data objects.
License:	Apache License 2.0
URL:	https://github.com/insightsengineering/cards, https://insightsengineering.github.io/cards/
BugReports:	https://github.com/insightsengineering/cards/issues
Depends:	R (≥ 4.1)
Imports:	cli (≥ 3.6.1), dplyr (≥ 1.1.2), glue (≥ 1.6.2), lifecycle (≥ 1.0.3), rlang (≥ 1.1.1), tidyr (≥ 1.3.0), tidyselect (≥ 1.2.0)
Suggests:	testthat (≥ 3.2.0), withr (≥ 3.0.0)
Config/Needs/coverage:	hms
Config/Needs/website:	rmarkdown, jsonlite, yaml, ddsjoberg/gtsummary, tfrmt, cardx, gt, fontawesome, insightsengineering/nesttemplate
Config/testthat/edition:	3
Config/testthat/parallel:	true
Encoding:	UTF-8
Language:	en-US
LazyData:	true
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-07-03 03:22:47 UTC; sjobergd
Author:	Daniel D. Sjoberg [aut, cre], Becca Krouse [aut], Emily de la Rua [aut], F. Hoffmann-La Roche AG [cph, fnd], GlaxoSmithKline Research & Development Limited [cph]
Maintainer:	Daniel D. Sjoberg <danield.sjoberg@gmail.com>
Repository:	CRAN
Date/Publication:	2025-07-03 12:50:09 UTC

cards: Analysis Results Data

Description

Construct CDISC (Clinical Data Interchange Standards Consortium) compliant Analysis Results Data objects. These objects are used and re-used to construct summary tables, visualizations, and written reports. The package also exports utilities for working with these objects and creating new Analysis Results Data objects.

Author(s)

Maintainer: Daniel D. Sjoberg danield.sjoberg@gmail.com (ORCID)

Authors:

• Becca Krouse becca.z.krouse@gsk.com

• Emily de la Rua emily.de_la_rua@contractors.roche.com

Other contributors:

• F. Hoffmann-La Roche AG [copyright holder, funder]

• GlaxoSmithKline Research & Development Limited [copyright holder]

See Also

Useful links:

• https://github.com/insightsengineering/cards

• https://insightsengineering.github.io/cards/

• Report bugs at https://github.com/insightsengineering/cards/issues

Calculate Continuous Statistics

Description

Calculate statistics and return in an ARD format

Usage

.calculate_stats_as_ard(
  df_nested,
  variables,
  statistic,
  by,
  strata,
  data,
  new_col_name = "...ard_all_stats..."
)

Arguments

Value

an ARD data frame of class 'card'

Examples

data_nested <- ADSL |>
  nest_for_ard(
    by = "ARM",
    strata = NULL,
    key = "...ard_nested_data..."
  )

cards:::.calculate_stats_as_ard(
  df_nested = data_nested,
  variables = "AGE",
  statistic = list(mean = "mean"),
  by = "ARM",
  strata = NULL,
  data = ADSL
)

Calculate Tabulation Statistics

Description

Function takes the summary instructions from the statistic = list(variable_name = list(tabulation=c("n", "N", "p"))) argument, and returns the tabulations in an ARD structure.

Usage

.calculate_tabulation_statistics(
  data,
  variables,
  by,
  strata,
  denominator,
  statistic
)

Arguments

Value

an ARD data frame of class 'card'

Examples

cards:::.calculate_tabulation_statistics(
  ADSL,
  variables = "ARM",
  by = NULL,
  strata = NULL,
  denominator = "cell",
  statistic = list(ARM = list(tabulation = c("N")))
)

Perform Value Checks

Description

Check the validity of the values passed in ard_dichotomous(value).

Usage

.check_dichotomous_value(data, value)

Arguments

Value

returns invisible if check is successful, throws an error message if not.

Examples

cards:::.check_dichotomous_value(mtcars, list(cyl = 4))

Check 'xx' Format Structure

Description

A function that checks a single string for consistency. String must begin with 'x' and only consist of x's, a single period or none, and may end with a percent symbol.

If string is consistent, TRUE is returned. Otherwise an error.

Usage

.check_fmt_string(x, variable, stat_name)

Arguments

Value

a logical

Examples

cards:::.check_fmt_string("xx.x") # TRUE
cards:::.check_fmt_string("xx.x%") # TRUE

Check for Missing Levels in denominator

Description

When a user passes a data frame in the denominator argument, this function checks that the data frame contains all the same levels of the by and strata variables that appear in data.

Usage

.check_for_missing_combos_in_denom(data, denominator, by, strata)

Arguments

Value

returns invisible if check is successful, throws an error message if not.

Examples

cards:::.check_for_missing_combos_in_denom(ADSL, denominator = "col", by = "ARM", strata = "AGEGR1")

Check Protected Column Names

Description

Checks that column names in a passed data frame are not protected, that is, they do not begin with "...ard_" and end with "...".

Usage

.check_no_ard_columns(x, exceptions = "...ard_dummy_for_counting...")

Arguments

Value

returns invisible if check is successful, throws an error message if not.

Examples

data <- data.frame("ard_x" = 1)

cards:::.check_no_ard_columns(data)

Check Variable Names

Description

Checks variable names in a data frame against protected names and modifies them if needed

Usage

.check_var_nms(x, vars_protected)

Arguments

Value

a data frame

Examples

data <- data.frame(a = "x", b = "y", c = "z", ..cards_idx.. = 1)

cards:::.check_var_nms(data, vars_protected = c("x", "z"))

Print Condition Messages Saved in an ARD

Description

Print Condition Messages Saved in an ARD

Usage

.cli_condition_messaging(x, msg_type, condition_type)

Arguments

Value

returns invisible if check is successful, throws warning/error messages if not.

Examples

ard <- ard_continuous(
  ADSL,
  by = ARM,
  variables = AGE
)

cards:::.cli_condition_messaging(ard, msg_type = "error")

Locate Condition Messages in an ARD

Description

Prints a string of all group##/group##_level column values and variable column values where condition messages occur, formatted using glue syntax.

Usage

.cli_groups_and_variable(x)

Arguments

Value

a string

Examples

ard <- ard_continuous(
  ADSL,
  by = ARM,
  variables = AGE,
  statistic = ~ list(
    mean = \(x) mean(x),
    mean_warning = \(x) {
      warning("warn1")
      warning("warn2")
      mean(x)
    },
    err_fn = \(x) stop("'tis an error")
  )
)

cards:::.cli_groups_and_variable(ard)

Create List for Attributes

Description

Create List for Attributes

Usage

.create_list_for_attributes(ard_subset, attributes, i)

Arguments

Value

a named list

Examples

ard <- ard_categorical(ADSL, by = "ARM", variables = "AGEGR1")

cards:::.create_list_for_attributes(ard, c("group1", "group1_level"), 1)

Add Default Formatting Functions

Description

Add Default Formatting Functions

Usage

.default_fmt_fun(x)

Arguments

Value

a data frame

Examples

ard <- ard_categorical(ADSL, by = "ARM", variables = "AGEGR1") |>
  dplyr::mutate(fmt_fun = NA)

cards:::.default_fmt_fun(ard)

Detect Columns with Non-Null Contents

Description

Function looks for non-null contents in requested columns and notifies user before removal. Specifically used for detecting messages.

Usage

.detect_msgs(x, ...)

Arguments

Examples

ard <- ard_continuous(
  ADSL,
  by = ARM,
  variables = AGE,
  statistic = ~ list(
    mean = \(x) mean(x),
    mean_warning = \(x) {
      warning("warn1")
      warning("warn2")
      mean(x)
    },
    err_fn = \(x) stop("'tis an error")
  )
)

cards:::.detect_msgs(ard, "warning", "error")

Evaluate the ⁠ard_*()⁠ function calls

Description

Evaluate the ⁠ard_*()⁠ function calls

Usage

.eval_ard_calls(data, .by, ...)

Arguments

Value

list of ARD data frames of class 'card'

Examples

cards:::.eval_ard_calls(
  data = ADSL,
  .by = "ARM",
  ard_categorical(variables = "AGEGR1"),
  ard_continuous(variables = "AGE")
)

Back Fill Group Variables

Description

This function back fills the values of group variables using variable/variable_levels. The back filling will occur if the value of the variable column matches the name of a grouping variable, and the grouping variable's value is NA.

Usage

.fill_grps_from_variables(x)

Arguments

Value

data frame

Examples

data <- data.frame(
  variable = c(rep("A", 3), rep("B", 2)),
  variable_level = 1:5,
  A = rep(NA, 5),
  B = rep(NA, 5)
)

cards:::.fill_grps_from_variables(data)

Fill Overall Group Variables

Description

This function fills the missing values of grouping variables with "Overall ⁠variable name⁠" where relevant. Specifically it will modify grouping values from rows with likely overall calculations present (e.g. non-missing variable/variable_level, missing group variables, and evidence that the variable has been computed by group in other rows). "Overall" values will be populated only for grouping variables that have been used in other calculations of the same variable and statistics.

Usage

.fill_overall_grp_values(x, vars_protected)

Arguments

Value

data frame

Examples

data <- dplyr::tibble(
  grp = c("AA", "AA", NA, "BB", NA),
  variable = c("A", "B", "A", "C", "C"),
  variable_level = c(1, 2, 1, 3, 3),
  A = rep(NA, 5),
  B = rep(NA, 5),
  ..cards_idx.. = c(1:5)
)

cards:::.fill_overall_grp_values(data, vars_protected = "..cards_idx..")

Named List Predicate

Description

A predicate function to check whether input is a named list and not a data frame.

Usage

.is_named_list(x, allow_df = FALSE)

Arguments

Value

a logical

Examples

cards:::.is_named_list(list(a = 1:3))

Prepare Results as Data Frame

Description

Function takes the results from eval_capture_conditions(), which is a named list, e.g. list(result=, warning=, error=), and converts it to a data frame.

Usage

.lst_results_as_df(x, variable, fun_name, fun)

Arguments

Value

a data frame

Examples

msgs <- eval_capture_conditions({
  warning("Warning 1")
  warning("Warning 2")
  letters[1:2]
})

cards:::.lst_results_as_df(msgs, "result", "mean")

Rename ARD Columns

Description

If variable is provided, adds the standard variable column to x. If by/strata are provided, adds the standard group## column(s) to x and renames the provided columns to group##_level in x, where ⁠##⁠ is determined by the column's position in c(by, strata).

Usage

.nesting_rename_ard_columns(x, variable = NULL, by = NULL, strata = NULL)

Arguments

Value

a tibble

Examples

ard <- nest_for_ard(
  data =
    ADAE |>
      dplyr::left_join(ADSL[c("USUBJID", "ARM")], by = "USUBJID") |>
      dplyr::filter(AOCCSFL %in% "Y"),
  by = "ARM",
  strata = "AESOC",
  rename_columns = FALSE
)

cards:::.nesting_rename_ard_columns(ard, by = "ARM", strata = "AESOC")

Convert One Row to Nested List

Description

Convert One Row to Nested List

Usage

.one_row_ard_to_nested_list(x)

Arguments

Value

an expression that represents an element of a nested list

Examples

ard_continuous(mtcars, variables = mpg) |>
  dplyr::filter(dplyr::row_number() %in% 1L) |>
  apply_fmt_fun() |>
  cards:::.one_row_ard_to_nested_list()

Process denominator Argument

Description

Function takes the ard_categorical(denominator) argument and returns a structured data frame that is merged with the count data and used as the denominator in percentage calculations.

Usage

.process_denominator(data, variables, denominator, by, strata)

Arguments

Value

a data frame

Examples

cards:::.process_denominator(mtcars, denominator = 1000, variables = "cyl", by = "gear")

Convert Nested Lists to Column

Description

Some arguments, such as stat_label, are passed as nested lists. This function properly unnests these lists and adds them to the results data frame.

Usage

.process_nested_list_as_df(x, arg, new_column, unlist = FALSE)

Arguments

Value

a data frame

Examples

ard <- ard_categorical(ADSL, by = "ARM", variables = "AGEGR1")

cards:::.process_nested_list_as_df(ard, NULL, "new_col")

A list_flatten()-like Function

Description

Function operates similarly to purrr::list_flatten(x, name_spec = "{inner}").

Usage

.purrr_list_flatten(x)

Arguments

Value

a named list

Examples

x <- list(a = 1, b = list(b1 = 2, b2 = 3), c = list(c1 = 4, c2 = list(c2a = 5)))

cards:::.purrr_list_flatten(x)

Rename Last Group to Variable

Description

In the ⁠ard_hierarchical*()⁠ functions, the last grouping variable is renamed to variable and variable_level before being returned.

Usage

.rename_last_group_as_variable(df_result, by, variables)

Arguments

Value

an ARD data frame of class 'card'

Examples

data <- data.frame(x = 1, y = 2, group1 = 3, group2 = 4)

cards:::.rename_last_group_as_variable(data, by = "ARM", variables = "AESOC")

Results from table() as Data Frame

Description

Takes the results from table() and returns them as a data frame. After the table() results are made into a data frame, all the variables are made into character columns, and the function also restores the column types to their original classes. For strata columns, only observed combinations are returned.

Usage

.table_as_df(
  data,
  variable = NULL,
  by = NULL,
  strata = NULL,
  useNA = c("no", "always"),
  count_column = "...ard_n..."
)

Arguments

Value

data frame

Examples

cards:::.table_as_df(ADSL, variable = "ARM", by = "AGEGR1", strata = NULL)

Trim ARD

Description

This function ingests an ARD object and trims columns and rows for downstream use in displays. The resulting data frame contains only numeric results, no supplemental information about errors/warnings, and unnested list columns.

Usage

.trim_ard(x)

Arguments

Value

a tibble

Examples

ard <- bind_ard(
  ard_categorical(ADSL, by = "ARM", variables = "AGEGR1"),
  ard_categorical(ADSL, variables = "ARM")
) |>
  shuffle_ard(trim = FALSE)

ard |> cards:::.trim_ard()

ARD-flavor of unique()

Description

Essentially a wrapper for unique(x) |> sort() with NA levels removed. For factors, all levels are returned even if they are unobserved. Similarly, logical vectors always return c(TRUE, FALSE), even if both levels are not observed.

Usage

.unique_and_sorted(x, useNA = c("no", "always"))

Arguments

Value

a vector

Examples

cards:::.unique_and_sorted(factor(letters[c(5, 5:1)], levels = letters))

cards:::.unique_and_sorted(c(FALSE, TRUE, TRUE, FALSE))

cards:::.unique_and_sorted(c(5, 5:1))

Example ADaM Data

Description

Data frame imported from the CDISC SDTM/ADaM Pilot Project

Usage

ADSL

ADAE

ADTTE

Format

An object of class tbl_df (inherits from tbl, data.frame) with 254 rows and 49 columns.

An object of class tbl_df (inherits from tbl, data.frame) with 1191 rows and 56 columns.

An object of class tbl_df (inherits from tbl, data.frame) with 254 rows and 26 columns.

Add Calculated Row

Description

Use this function to add a new statistic row that is a function of the other statistics in an ARD.

Usage

add_calculated_row(
  x,
  expr,
  stat_name,
  by = c(all_ard_groups(), all_ard_variables(), any_of("context")),
  stat_label = stat_name,
  fmt_fun = NULL,
  fmt_fn = deprecated()
)

Arguments

Value

an ARD data frame of class 'card'

Examples

ard_continuous(mtcars, variables = mpg) |>
  add_calculated_row(expr = max - min, stat_name = "range")

ard_continuous(mtcars, variables = mpg) |>
  add_calculated_row(
    expr =
      dplyr::case_when(
        mean > median ~ "Right Skew",
        mean < median ~ "Left Skew",
        .default = "Symmetric"
      ),
    stat_name = "skew"
  )

Convert Alias to Function

Description

Accepted aliases are non-negative integers and strings.

The integers are converted to functions that round the statistics to the number of decimal places to match the integer.

The formatting strings come in the form "xx", "xx.x", "xx.x%", etc. The number of xs that appear after the decimal place indicate the number of decimal places the statistics will be rounded to. The number of xs that appear before the decimal place indicate the leading spaces that are added to the result. If the string ends in "%", results are scaled by 100 before rounding.

Usage

alias_as_fmt_fun(x, variable, stat_name)

Arguments

Value

a function

Examples

alias_as_fmt_fun(1)
alias_as_fmt_fun("xx.x")

Apply Formatting Functions

Description

Apply the formatting functions to each of the raw statistics. Function aliases are converted to functions using alias_as_fmt_fun().

Usage

apply_fmt_fun(x, replace = FALSE)

Arguments

Value

an ARD data frame of class 'card'

Examples

ard_continuous(ADSL, variables = "AGE") |>
  apply_fmt_fun()

ARD Attributes

Description

Add variable attributes to an ARD data frame.

• The label attribute will be added for all columns, and when no label is specified and no label has been set for a column using the ⁠label=⁠ argument, the column name will be placed in the label statistic.

• The class attribute will also be returned for all columns.

• Any other attribute returned by attributes() will also be added, e.g. factor levels.

Usage

ard_attributes(data, ...)

## S3 method for class 'data.frame'
ard_attributes(data, variables = everything(), label = NULL, ...)

## Default S3 method:
ard_attributes(data, ...)

Arguments

Value

an ARD data frame of class 'card'

Examples

df <- dplyr::tibble(var1 = letters, var2 = LETTERS)
attr(df$var1, "label") <- "Lowercase Letters"

ard_attributes(df, variables = everything())

Categorical ARD Statistics

Description

Compute Analysis Results Data (ARD) for categorical summary statistics.

Usage

ard_categorical(data, ...)

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

Arguments

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.

Lastly, when the p statistic is returned, the proportion is returned—bounded by ⁠[0, 1]⁠. However, the default function to format the statistic scales the proportion by 100 and the percentage is returned which matches the default statistic label of '%'. To get the formatted values, pass the ARD to apply_fmt_fun().

Other Statistics

In some cases, you may need other kinds of statistics for categorical variables. Despite the name, ard_continuous() can be used to obtain these statistics.

In the example below, we calculate the mode of a categorical variable.

get_mode <- function(x) {
  table(x) |> sort(decreasing = TRUE) |> names() |> getElement(1L)
}

ADSL |>
  ard_continuous(
    variables = AGEGR1,
    statistic = list(AGEGR1 = list(mode = get_mode))
  )
#> {cards} data frame: 1 x 8
#>   variable   context stat_name stat_label  stat fmt_fun
#> 1   AGEGR1 continuo…      mode       mode 65-80    <fn>
#> i 2 more variables: warning, error

Examples

ard_categorical(ADSL, by = "ARM", variables = "AGEGR1")

ADSL |>
  dplyr::group_by(ARM) |>
  ard_categorical(
    variables = "AGEGR1",
    statistic = everything() ~ "n"
  )

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 class 'data.frame'
ard_complex(
  data,
  variables,
  by = dplyr::group_vars(data),
  strata = NULL,
  statistic,
  fmt_fun = NULL,
  stat_label = everything() ~ default_stat_labels(),
  fmt_fn = deprecated(),
  ...
)

Arguments

Value

an ARD data frame of class 'card'

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))
  )

Continuous ARD Statistics

Description

Compute Analysis Results Data (ARD) for simple continuous summary statistics.

Usage

ard_continuous(data, ...)

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

Arguments

Value

an ARD data frame of class 'card'

Examples

ard_continuous(ADSL, by = "ARM", variables = "AGE")

# if a single function returns a named list, the named
# results will be placed in the resulting ARD
ADSL |>
  dplyr::group_by(ARM) |>
  ard_continuous(
    variables = "AGE",
    statistic =
      ~ list(conf.int = \(x) t.test(x)[["conf.int"]] |>
        as.list() |>
        setNames(c("conf.low", "conf.high")))
  )

Dichotomous ARD Statistics

Description

Compute Analysis Results Data (ARD) for dichotomous summary statistics.

Usage

ard_dichotomous(data, ...)

## S3 method for class 'data.frame'
ard_dichotomous(
  data,
  variables,
  by = dplyr::group_vars(data),
  strata = NULL,
  value = maximum_variable_value(data[variables]),
  statistic = everything() ~ c("n", "N", "p"),
  denominator = NULL,
  fmt_fun = NULL,
  stat_label = everything() ~ default_stat_labels(),
  fmt_fn = deprecated(),
  ...
)

Arguments

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.

Lastly, when the p statistic is returned, the proportion is returned—bounded by ⁠[0, 1]⁠. However, the default function to format the statistic scales the proportion by 100 and the percentage is returned which matches the default statistic label of '%'. To get the formatted values, pass the ARD to apply_fmt_fun().

Examples

ard_dichotomous(mtcars, by = vs, variables = c(cyl, am), value = list(cyl = 4))

mtcars |>
  dplyr::group_by(vs) |>
  ard_dichotomous(
    variables = c(cyl, am),
    value = list(cyl = 4),
    statistic = ~"p"
  )

Argument Values ARD

Description

Place default and passed argument values to a function into an ARD structure.

Usage

ard_formals(fun, arg_names, passed_args = list(), envir = parent.frame())

Arguments

Value

an partial ARD data frame of class 'card'

Examples

# Example 1 ----------------------------------
# add the `mcnemar.test(correct)` argument to an ARD structure
ard_formals(fun = mcnemar.test, arg_names = "correct")

# Example 2 ----------------------------------
# S3 Methods need special handling to access the underlying method
ard_formals(
  fun = asNamespace("stats")[["t.test.default"]],
  arg_names = c("mu", "paired", "var.equal", "conf.level"),
  passed_args = list(conf.level = 0.90)
)

Hierarchical ARD Statistics

Description

Functions ard_hierarchical() and ard_hierarchical_count() are primarily helper functions for ard_stack_hierarchical() and ard_stack_hierarchical_count(), meaning that it will be rare a user needs to call ard_hierarchical()/ard_hierarchical_count() directly.

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_fun = NULL,
  stat_label = everything() ~ default_stat_labels(),
  id = NULL,
  fmt_fn = deprecated(),
  ...
)

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

Arguments

Value

an ARD data frame of class 'card'

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
)

ard_hierarchical_count(
  data = ADAE,
  variables = c(AESOC, AEDECOD),
  by = TRTA
)

ARD Identity

Description

Function ingests pre-calculated statistics and returns the identical results, but in an ARD format.

Usage

ard_identity(x, variable, context = "identity")

Arguments

Value

a ARD

Examples

t.test(formula = AGE ~ 1, data = ADSL)[c("statistic", "parameter", "p.value")] |>
  ard_identity(variable = "AGE", context = "onesample_t_test")

Missing ARD Statistics

Description

Compute Analysis Results Data (ARD) for statistics related to data missingness.

Usage

ard_missing(data, ...)

## S3 method for class 'data.frame'
ard_missing(
  data,
  variables,
  by = dplyr::group_vars(data),
  statistic = everything() ~ c("N_obs", "N_miss", "N_nonmiss", "p_miss", "p_nonmiss"),
  fmt_fun = NULL,
  stat_label = everything() ~ default_stat_labels(),
  fmt_fn = deprecated(),
  ...
)

Arguments

Value

an ARD data frame of class 'card'

Examples

ard_missing(ADSL, by = "ARM", variables = "AGE")

ADSL |>
  dplyr::group_by(ARM) |>
  ard_missing(
    variables = "AGE",
    statistic = ~"N_miss"
  )

Pairwise ARD

Description

Utility to perform pairwise comparisons.

Usage

ard_pairwise(data, variable, .f, include = NULL)

Arguments

Value

list of ARDs

Examples

ard_pairwise(
  ADSL,
  variable = ARM,
  .f = \(df) {
    ard_complex(
      df,
      variables = AGE,
      statistic = ~ list(ttest = \(x, data, ...) t.test(x ~ data$ARM)[c("statistic", "p.value")])
    )
  },
  include = "Placebo" # only include comparisons to the "Placebo" group
)

Stack ARDs

Description

Stack multiple ARD calls sharing common input data and by variables. Optionally incorporate additional information on represented variables, e.g. overall calculations, rates of missingness, attributes, or transform results with shuffle_ard().

If the ard_stack(by) argument is specified, a univariate tabulation of the by variable will also be returned.

Usage

ard_stack(
  data,
  ...,
  .by = NULL,
  .overall = FALSE,
  .missing = FALSE,
  .attributes = FALSE,
  .total_n = FALSE,
  .shuffle = FALSE
)

Arguments

Value

an ARD data frame of class 'card'

Examples

ard_stack(
  data = ADSL,
  ard_categorical(variables = "AGEGR1"),
  ard_continuous(variables = "AGE"),
  .by = "ARM",
  .overall = TRUE,
  .attributes = TRUE
)

ard_stack(
  data = ADSL,
  ard_categorical(variables = "AGEGR1"),
  ard_continuous(variables = "AGE"),
  .by = "ARM",
  .shuffle = TRUE
)

Stacked Hierarchical ARD Statistics

Description

Use these functions to calculate multiple summaries of nested or hierarchical data in a single call.

• ard_stack_hierarchical(): Calculates rates of events (e.g. adverse events) utilizing the denominator and id arguments to identify the rows in data to include in each rate calculation.

• ard_stack_hierarchical_count(): Calculates counts of events utilizing all rows for each tabulation.

Usage

ard_stack_hierarchical(
  data,
  variables,
  by = dplyr::group_vars(data),
  id,
  denominator,
  include = everything(),
  statistic = everything() ~ c("n", "N", "p"),
  overall = FALSE,
  over_variables = FALSE,
  attributes = FALSE,
  total_n = FALSE,
  shuffle = FALSE
)

ard_stack_hierarchical_count(
  data,
  variables,
  by = dplyr::group_vars(data),
  denominator = NULL,
  include = everything(),
  overall = FALSE,
  over_variables = FALSE,
  attributes = FALSE,
  total_n = FALSE,
  shuffle = FALSE
)

Arguments

Value

an ARD data frame of class 'card'

Subsetting Data for Rate Calculations

To calculate event rates, the ard_stack_hierarchical() function identifies rows to include in the calculation. First, the primary data frame is sorted by the columns identified in the id, by, and variables arguments.

As the function cycles over the variables specified in the variables argument, the data frame is grouped by id, intersect(by, names(denominator)), and variables utilizing the last row within each of the groups.

For example, if the call is ard_stack_hierarchical(data = ADAE, variables = c(AESOC, AEDECOD), id = USUBJID), then we'd first subset ADAE to be one row within the grouping c(USUBJID, AESOC, AEDECOD) to calculate the event rates in 'AEDECOD'. We'd then repeat and subset ADAE to be one row within the grouping c(USUBJID, AESOC) to calculate the event rates in 'AESOC'.

Overall Argument

When we set overall=TRUE, we wish to re-run our calculations removing the stratifying columns. For example, if we ran the code below, we results would include results with the code chunk being re-run with by=NULL.

ard_stack_hierarchical(
  data = ADAE,
  variables = c(AESOC, AEDECOD),
  by = TRTA,
  denominator = ADSL,
  id = USUBJID,
  overall = TRUE
)

But there is another case to be aware of: when the by argument includes columns that are not present in the denominator, for example when tabulating results by AE grade or severity in addition to treatment assignment. In the example below, we're tabulating results by treatment assignment and AE severity. By specifying overall=TRUE, we will re-run the to get results with by = AESEV and again with by = NULL.

ard_stack_hierarchical(
  data = ADAE,
  variables = c(AESOC, AEDECOD),
  by = c(TRTA, AESEV),
  denominator = ADSL,
  id = USUBJID,
  overall = TRUE
)

Examples

ard_stack_hierarchical(
  ADAE,
  variables = c(AESOC, AEDECOD),
  by = TRTA,
  denominator = ADSL,
  id = USUBJID
)

ard_stack_hierarchical_count(
  ADAE,
  variables = c(AESOC, AEDECOD),
  by = TRTA,
  denominator = ADSL
)

Stratified ARD

Description

General function for calculating ARD results within subgroups.

While the examples below show use with other functions from the cards package, this function would primarily be used with the statistical functions in the cardx functions.

Usage

ard_strata(.data, .by = NULL, .strata = NULL, .f, ...)

Arguments

Value

an ARD data frame of class 'card'

Examples

ard_strata(
  ADSL,
  .by = ARM,
  .f = ~ ard_continuous(.x, variables = AGE)
)

ARD Total N

Description

Returns the total N for the data frame. The placeholder variable name returned in the object is "..ard_total_n.."

Usage

ard_total_n(data, ...)

## S3 method for class 'data.frame'
ard_total_n(data, ...)

Arguments

Value

an ARD data frame of class 'card'

Examples

ard_total_n(ADSL)

Data Frame as ARD

Description

Convert data frames to ARDs of class 'card'.

Usage

as_card(x)

Arguments

Value

an ARD data frame of class 'card'

Examples

data.frame(
  stat_name = c("N", "mean"),
  stat_label = c("N", "Mean"),
  stat = c(10, 0.5)
) |>
  as_card()

As card function

Description

Add attributes to a function that specify the expected results. It is used when ard_continuous() or ard_complex() errors and constructs an ARD with the correct structure when the results cannot be calculated.

Usage

as_cards_fn(f, stat_names)

is_cards_fn(f)

get_cards_fn_stat_names(f)

Arguments

Value

an ARD data frame of class 'card'

Examples

# When there is no error, everything works as if we hadn't used `as_card_fn()`
ttest_works <-
  as_cards_fn(
    \(x) t.test(x)[c("statistic", "p.value")],
    stat_names = c("statistic", "p.value")
  )
ard_continuous(
  mtcars,
  variables = mpg,
  statistic = ~ list(ttest = ttest_works)
)

# When there is an error and we use `as_card_fn()`,
#   we will see the same structure as when there is no error
ttest_error <-
  as_cards_fn(
    \(x) {
      t.test(x)[c("statistic", "p.value")]
      stop("Intentional Error")
    },
    stat_names = c("statistic", "p.value")
  )
ard_continuous(
  mtcars,
  variables = mpg,
  statistic = ~ list(ttest = ttest_error)
)

# if we don't use `as_card_fn()` and there is an error,
#   the returned result is only one row
ard_continuous(
  mtcars,
  variables = mpg,
  statistic = ~ list(ttest = \(x) {
    t.test(x)[c("statistic", "p.value")]
    stop("Intentional Error")
  })
)

ARD as Nested List

Description

Convert ARDs to nested lists.

Usage

as_nested_list(x)

Arguments

Value

a nested list

Examples

ard_continuous(mtcars, by = "cyl", variables = c("mpg", "hp")) |>
  as_nested_list()

Bind ARDs

Description

Wrapper for dplyr::bind_rows() with additional checks for duplicated statistics.

Usage

bind_ard(
  ...,
  .distinct = TRUE,
  .update = FALSE,
  .order = FALSE,
  .quiet = FALSE
)

Arguments

Value

an ARD data frame of class 'card'

Examples

ard <- ard_categorical(ADSL, by = "ARM", variables = "AGEGR1")

bind_ard(ard, ard, .update = TRUE)

Options in {cards}

Description

See below for options available in the {cards} package

cards.round_type

There are two types of rounding types in the {cards} package that are implemented in label_round(), alias_as_fmt_fun(), and apply_fmt_fun() functions.

• 'round-half-up' (default): rounding method where values exactly halfway between two numbers are rounded to the larger in magnitude number. Rounding is implemented via round5().

• 'round-to-even': base R's default IEC 60559 rounding standard. See round() for details.

To change the default rounding to use IEC 60559, this option must be set both when the ARDs are created and when apply_fmt_fun() is run. This ensures that any default formatting functions created with label_round() utilize the specified rounding method and the method is used what aliases are converted into functions (which occurs in apply_fmt_fun() when it calls alias_as_fmt_fun()).

Check ARD Structure

Description

Function tests the structure and returns notes when object does not conform to expected structure.

Usage

check_ard_structure(x, column_order = TRUE, method = TRUE)

Arguments

Value

an ARD data frame of class 'card' (invisible)

Examples

ard_continuous(ADSL, variables = "AGE") |>
  dplyr::select(-warning, -error) |>
  check_ard_structure()

Defaults for Statistical Arguments

Description

Returns a named list of statistics labels

Usage

default_stat_labels()

Value

named list

Examples

# stat labels
default_stat_labels()

Deprecated functions

Description

Some functions have been deprecated and are no longer being actively supported.

Usage

apply_fmt_fn(...)

alias_as_fmt_fn(...)

update_ard_fmt_fn(...)

label_cards(...)

Evaluate and Capture Conditions

Description

eval_capture_conditions()

Evaluates an expression while also capturing error and warning conditions. Function always returns a named list list(result=, warning=, error=). If there are no errors or warnings, those elements will be NULL. If there is an error, the result element will be NULL.

Messages are neither saved nor printed to the console.

Evaluation is done via rlang::eval_tidy(). If errors and warnings are produced using the {cli} package, the messages are processed with cli::ansi_strip() to remove styling from the message.

captured_condition_as_message()/captured_condition_as_error()

These functions take the result from eval_capture_conditions() and return errors or warnings as either messages (via cli::cli_inform()) or errors (via cli::cli_abort()). These functions handle cases where the condition messages may include curly brackets, which would typically cause issues when processed with the ⁠cli::cli_*()⁠ functions.

Functions return the "result" from eval_capture_conditions().

Usage

eval_capture_conditions(expr, data = NULL, env = caller_env())

captured_condition_as_message(
  x,
  message = c("The following {type} occured:", x = "{condition}"),
  type = c("error", "warning"),
  envir = rlang::current_env()
)

captured_condition_as_error(
  x,
  message = c("The following {type} occured:", x = "{condition}"),
  type = c("error", "warning"),
  call = get_cli_abort_call(),
  envir = rlang::current_env()
)

Arguments

Value

a named list

Examples

# function executes without error or warning
eval_capture_conditions(letters[1:2])

# an error is thrown
res <- eval_capture_conditions(stop("Example Error!"))
res
captured_condition_as_message(res)

# if more than one warning is returned, all are saved
eval_capture_conditions({
  warning("Warning 1")
  warning("Warning 2")
  letters[1:2]
})

# messages are not printed to the console
eval_capture_conditions({
  message("A message!")
  letters[1:2]
})

Filter Stacked Hierarchical ARDs

Description

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

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,
    id = USUBJID
  )

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

Value

an ARD data frame of class 'card'

See Also

sort_ard_hierarchical()

Examples

# create a base AE ARD
ard <- ard_stack_hierarchical(
  ADAE,
  variables = c(AESOC, AEDECOD),
  by = TRTA,
  denominator = ADSL,
  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)

# 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)

# Example 3 ----------------------------------
# Keep AEs that have an overall prevalence of greater than 5%
filter_ard_hierarchical(ard, sum(n) / sum(N) > 0.05)

ARD Statistics as List

Description

Returns the statistics from an ARD as a named list.

Usage

get_ard_statistics(x, ..., .column = "stat", .attributes = NULL)

Arguments

Value

named list

Examples

ard <- ard_categorical(ADSL, by = "ARM", variables = "AGEGR1")

get_ard_statistics(
  ard,
  group1_level %in% "Placebo",
  variable_level %in% "65-80",
  .attributes = "stat_label"
)

Generate Formatting Function

Description

Returns a function with the requested rounding and scaling schema.

Usage

label_round(digits = 1, scale = 1, width = NULL)

Arguments

Value

a function

Examples

label_round(2)(pi)
label_round(1, scale = 100)(pi)
label_round(2, width = 5)(pi)

Maximum Value

Description

For each column in the passed data frame, the function returns a named list with the value being the largest/last element after a sort. For factors, the last level is returned, and for logical vectors TRUE is returned. This is used as the default value in ard_dichotomous(value) if not specified by the user.

Usage

maximum_variable_value(data)

Arguments

Value

a named list

Examples

ADSL[c("AGEGR1", "BMIBLGR1")] |> maximum_variable_value()

Mock ARDs

Description

Create empty ARDs used to create mock tables or table shells. Where applicable, the formatting functions are set to return 'xx' or 'xx.x'.

Usage

mock_categorical(
  variables,
  statistic = everything() ~ c("n", "p", "N"),
  by = NULL
)

mock_continuous(
  variables,
  statistic = everything() ~ c("N", "mean", "sd", "median", "p25", "p75", "min", "max"),
  by = NULL
)

mock_dichotomous(
  variables,
  statistic = everything() ~ c("n", "p", "N"),
  by = NULL
)

mock_missing(
  variables,
  statistic = everything() ~ c("N_obs", "N_miss", "N_nonmiss", "p_miss", "p_nonmiss"),
  by = NULL
)

mock_attributes(label)

mock_total_n()

Arguments

Value

an ARD data frame of class 'card'

Examples

mock_categorical(
  variables =
    list(
      AGEGR1 = factor(c("<65", "65-80", ">80"), levels = c("<65", "65-80", ">80"))
    ),
  by = list(TRTA = c("Placebo", "Xanomeline High Dose", "Xanomeline Low Dose"))
) |>
  apply_fmt_fun()

mock_continuous(
  variables = c("AGE", "BMIBL"),
  by = list(TRTA = c("Placebo", "Xanomeline High Dose", "Xanomeline Low Dose"))
) |>
  # update the mock to report 'xx.xx' for standard deviations
  update_ard_fmt_fun(variables = c("AGE", "BMIBL"), stat_names = "sd", fmt_fun = \(x) "xx.xx") |>
  apply_fmt_fun()

ARD Nesting

Description

This function is similar to tidyr::nest(), except that it retains rows for unobserved combinations (and unobserved factor levels) of by variables, and unobserved combinations of stratifying variables.

The levels are wrapped in lists so they can be stacked with other types of different classes.

Usage

nest_for_ard(
  data,
  by = NULL,
  strata = NULL,
  key = "data",
  rename_columns = TRUE,
  list_columns = TRUE,
  include_data = TRUE
)

Arguments

Value

a nested tibble

Examples

nest_for_ard(
  data =
    ADAE |>
      dplyr::left_join(ADSL[c("USUBJID", "ARM")], by = "USUBJID") |>
      dplyr::filter(AOCCSFL %in% "Y"),
  by = "ARM",
  strata = "AESOC"
)

Print

Description

Print method for objects of class 'card'

Usage

## S3 method for class 'card'
print(x, n = NULL, columns = c("auto", "all"), n_col = 6L, ...)

Arguments

Value

an ARD data frame of class 'card' (invisibly)

Examples

ard_categorical(ADSL, variables = AGEGR1) |>
  print()

Print ARD Condition Messages

Description

Function parses the errors and warnings observed while calculating the statistics requested in the ARD and prints them to the console as messages.

Usage

print_ard_conditions(x, condition_type = c("inform", "identity"))

Arguments

Value

returns invisible if check is successful, throws all condition messages if not.

Examples

# passing a character variable for numeric summary
ard_continuous(ADSL, variables = AGEGR1) |>
  print_ard_conditions()

Process tidyselectors

Description

Functions process tidyselect arguments passed to functions in the cards package. The processed values are saved to the calling environment, by default.

• process_selectors(): the arguments will be processed with tidyselect and converted to a vector of character column names.

• process_formula_selectors(): for arguments that expect named lists or lists of formulas (where the LHS of the formula is a tidyselector). This function processes these inputs and returns a named list. If a name is repeated, the last entry is kept.

• fill_formula_selectors(): when users override the default argument values, it can be important to ensure that each column from a data frame is assigned a value. This function checks that each column in data has an assigned value, and if not, fills the value in with the default value passed here.

• compute_formula_selector(): used in process_formula_selectors() to evaluate a single argument.

• check_list_elements(): used to check the class/type/values of the list elements, primarily those processed with process_formula_selectors().

• cards_select(): wraps tidyselect::eval_select() |> names(), and returns better contextual messaging when errors occur.

Usage

process_selectors(data, ...)

process_formula_selectors(data, ...)

fill_formula_selectors(data, ...)

## S3 method for class 'data.frame'
process_selectors(data, ..., env = caller_env())

## S3 method for class 'data.frame'
process_formula_selectors(
  data,
  ...,
  env = caller_env(),
  include_env = FALSE,
  allow_empty = TRUE
)

## S3 method for class 'data.frame'
fill_formula_selectors(data, ..., env = caller_env())

compute_formula_selector(
  data,
  x,
  arg_name = caller_arg(x),
  env = caller_env(),
  strict = TRUE,
  include_env = FALSE,
  allow_empty = TRUE
)

check_list_elements(
  x,
  predicate,
  error_msg = NULL,
  arg_name = rlang::caller_arg(x)
)

cards_select(expr, data, ..., arg_name = NULL)

Arguments

Value

process_selectors(), fill_formula_selectors(), process_formula_selectors() and check_list_elements() return NULL. compute_formula_selector() returns a named list.

Examples

example_env <- rlang::new_environment()

process_selectors(ADSL, variables = starts_with("TRT"), env = example_env)
get(x = "variables", envir = example_env)

fill_formula_selectors(ADSL, env = example_env)

process_formula_selectors(
  ADSL,
  statistic = list(starts_with("TRT") ~ mean, TRTSDT = min),
  env = example_env
)
get(x = "statistic", envir = example_env)

check_list_elements(
  get(x = "statistic", envir = example_env),
  predicate = function(x) !is.null(x),
  error_msg = c(
    "Error in the argument {.arg {arg_name}} for variable {.val {variable}}.",
    "i" = "Value must be a named list of functions."
  )
)

# process one list
compute_formula_selector(ADSL, x = starts_with("U") ~ 1L)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

dplyr

%>%, all_of, any_of, contains, ends_with, everything, last_col, matches, num_range, one_of, starts_with, vars, where

Rename ARD Variables

Description

Rename the grouping and variable columns to their original column names.

Usage

rename_ard_columns(
  x,
  columns = c(all_ard_groups("names"), all_ard_variables("names")),
  fill = "{colname}",
  unlist = NULL
)

Arguments

Value

data frame

Examples

# Example 1 ----------------------------------
ADSL |>
  ard_categorical(by = ARM, variables = AGEGR1) |>
  apply_fmt_fun() |>
  rename_ard_columns() |>
  unlist_ard_columns()

# Example 2 ----------------------------------
ADSL |>
  ard_continuous(by = ARM, variables = AGE) |>
  apply_fmt_fun() |>
  rename_ard_columns(fill = "Overall {colname}") |>
  unlist_ard_columns()

Rename ARD Group Columns

Description

Functions for renaming group columns names in ARDs.

Usage

rename_ard_groups_shift(x, shift = -1)

rename_ard_groups_reverse(x)

Arguments

Value

an ARD data frame of class 'card'

Examples

ard <- ard_continuous(ADSL, by = c(SEX, ARM), variables = AGE)

# Example 1 ----------------------------------
rename_ard_groups_shift(ard, shift = -1)

# Example 2 ----------------------------------
rename_ard_groups_reverse(ard)

Replace NULL Statistics with Specified Value

Description

When a statistical summary function errors, the "stat" column will be NULL. It is, however, sometimes useful to replace these values with a non-NULL value, e.g. NA.

Usage

replace_null_statistic(x, value = NA, rows = TRUE)

Arguments

Value

an ARD data frame of class 'card'

Examples

# the quantile functions error because the input is character, while the median function returns NA
data.frame(x = rep_len(NA_character_, 10)) |>
  ard_continuous(
    variables = x,
    statistic = ~ continuous_summary_fns(c("median", "p25", "p75"))
  ) |>
  replace_null_statistic(rows = !is.null(error))

Rounding of Numbers

Description

Rounds the values in its first argument to the specified number of decimal places (default 0). Importantly, round5() does not use Base R's "round to even" default. Standard rounding methods are implemented, for example, cards::round5(0.5) = 1, whereas base::round(0.5) = 0.

Usage

round5(x, digits = 0)

Arguments

Details

Function inspired by janitor::round_half_up().

Value

a numeric vector

Examples

x <- 0:4 / 2
round5(x) |> setNames(x)

# compare results to Base R
round(x) |> setNames(x)

ARD Selectors

Description

These selection helpers match variables according to a given pattern.

• all_ard_groups(): Function selects grouping columns, e.g. columns named "group##" or "group##_level".

• all_ard_variables(): Function selects variables columns, e.g. columns named "variable" or "variable_level".

• all_ard_group_n(): Function selects n grouping columns.

• all_missing_columns(): Function selects columns that are all NA or empty.

Usage

all_ard_groups(types = c("names", "levels"))

all_ard_variables(types = c("names", "levels"))

all_ard_group_n(n, types = c("names", "levels"))

all_missing_columns()

Arguments

Value

tidyselect output

Examples

ard <- ard_categorical(ADSL, by = "ARM", variables = "AGEGR1")

ard |> dplyr::select(all_ard_groups())
ard |> dplyr::select(all_ard_variables())

Shuffle ARD

Description

This function ingests an ARD object and shuffles the information to prepare for analysis. Helpful for streamlining across multiple ARDs. Combines each group/group_level into 1 column, back fills missing grouping values from the variable levels where possible, and optionally trims statistics-level metadata.

Usage

shuffle_ard(x, trim = TRUE)

Arguments

Value

a tibble

Examples

bind_ard(
  ard_categorical(ADSL, by = "ARM", variables = "AGEGR1"),
  ard_categorical(ADSL, variables = "ARM")
) |>
  shuffle_ard()

Sort Stacked Hierarchical ARDs

Description

This function is used to sort 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

sort_ard_hierarchical(x, sort = c("descending", "alphanumeric"))

Arguments

Value

an ARD data frame of class 'card'

Note

If overall data is present in x (i.e. the ARD was created with ard_stack_hierarchical(overall=TRUE)), the overall data will be sorted last within each variable group (i.e. after any other rows with the same combination of variable levels).

See Also

filter_ard_hierarchical()

Examples

ard_stack_hierarchical(
  ADAE,
  variables = c(AESOC, AEDECOD),
  by = TRTA,
  denominator = ADSL,
  id = USUBJID
) |>
  sort_ard_hierarchical("alphanumeric")

ard_stack_hierarchical_count(
  ADAE,
  variables = c(AESOC, AEDECOD),
  by = TRTA,
  denominator = ADSL
) |>
  sort_ard_hierarchical("descending")

Summary Functions

Description

• continuous_summary_fns() returns a named list of summary functions for continuous variables. Some functions include slight modifications to their base equivalents. For example, the min() and max() functions return NA instead of Inf when an empty vector is passed. Statistics "p25" and "p75" are calculated with quantile(type = 2), which matches SAS's default value.

Usage

continuous_summary_fns(
  summaries = c("N", "mean", "sd", "median", "p25", "p75", "min", "max"),
  other_stats = NULL
)

Arguments

Value

named list of summary statistics

Examples

# continuous variable summaries
ard_continuous(
  ADSL,
  variables = "AGE",
  statistic = ~ continuous_summary_fns(c("N", "median"))
)

Selecting Syntax

Description

Selecting Syntax

Selectors

The cards package also utilizes selectors: selectors from the tidyselect package and custom selectors. Review their help files for details.

• tidy selectors

  everything(), all_of(), any_of(), starts_with(), ends_with(), contains(), matches(), num_range(), last_col()

• cards selectors

  all_ard_groups(), all_ard_variables()

Formula and List Selectors

Some arguments in the cards package accept list and formula notation, e.g. ard_continuous(statistic=). Below enumerates a few tips and shortcuts for using the list and formulas.

1. List of Formulas

   Typical usage includes a list of formulas, where the LHS is a variable name or a selector.

   ard_continuous(statistic = list(age ~ list(N = \(x) length(x)), starts_with("a") ~ list(mean = mean)))
   

2. Named List

   You may also pass a named list; however, the tidyselect selectors are not supported with this syntax.

   ard_continuous(statistic = list(age = list(N = \(x) length(x))))
   

3. Hybrid Named List/List of Formulas

   You can pass a combination of formulas and named elements.

   ard_continuous(statistic = list(age = list(N = \(x) length(x)), starts_with("a") ~ list(mean = mean)))
   

4. Shortcuts

   You can pass a single formula, which is equivalent to passing the formula in a list.

   ard_continuous(statistic = starts_with("a") ~ list(mean = mean)
   

   As a shortcut to select all variables, you can omit the LHS of the formula. The two calls below are equivalent.

   ard_continuous(statistic = ~list(N = \(x) length(x)))
   ard_continuous(statistic = everything() ~ list(N = \(x) length(x)))
   

5. Combination Selectors

   Selectors can be combined using the c() function.

   ard_continuous(statistic = c(everything(), -age) ~ list(N = \(x) length(x)))
   

Standard Order of ARD

Description

ARD functions for relocating columns and rows to the standard order.

• tidy_ard_column_order() relocates columns of the ARD to the standard order.

• tidy_ard_row_order() orders rows of ARD according to groups and strata (group 1, then group2, etc), while retaining the column order of the input ARD.

Usage

tidy_ard_column_order(x, group_order = c("ascending", "descending"))

tidy_ard_row_order(x)

Arguments

Value

an ARD data frame of class 'card'

Examples

# order columns
ard <-
  dplyr::bind_rows(
    ard_continuous(mtcars, variables = "mpg"),
    ard_continuous(mtcars, variables = "mpg", by = "cyl")
  )

tidy_ard_column_order(ard) |>
  tidy_ard_row_order()

Build ARD from Tidier

Description

Function is questioning because we think a better solution may be ard_continuous() + ard_formals().

Function converts a model's one-row tidy data frame into an ARD structure. The tidied data frame must have been constructed with eval_capture_conditions().

This function is primarily for developers and few consistency checks have been included.

Usage

tidy_as_ard(
  lst_tidy,
  tidy_result_names,
  fun_args_to_record = character(0L),
  formals = list(),
  passed_args = list(),
  lst_ard_columns
)

Arguments

Value

an ARD data frame of class 'card'

Examples

# example how one may create a fisher.test() ARD function
my_ard_fishertest <- function(data, by, variable, ...) {
  # perform fisher test and format results -----------------------------------
  lst_tidy_fisher <-
    eval_capture_conditions(
      # this manipulation is similar to `fisher.test(...) |> broom::tidy()`
      stats::fisher.test(x = data[[variable]], y = data[[by]], ...)[c("p.value", "method")] |>
        as.data.frame()
    )

  # build ARD ------------------------------------------------------------------
  tidy_as_ard(
    lst_tidy = lst_tidy_fisher,
    tidy_result_names = c("p.value", "method"),
    fun_args_to_record =
      c(
        "workspace", "hybrid", "hybridPars", "control", "or",
        "conf.int", "conf.level", "simulate.p.value", "B"
      ),
    formals = formals(stats::fisher.test),
    passed_args = dots_list(...),
    lst_ard_columns = list(group1 = by, variable = variable, context = "fishertest")
  )
}

my_ard_fishertest(mtcars, by = "am", variable = "vs")

Unlist ARD Columns

Description

Unlist ARD Columns

Usage

unlist_ard_columns(
  x,
  columns = c(where(is.list), -any_of(c("warning", "error", "fmt_fun"))),
  fill = NA,
  fct_as_chr = TRUE
)

Arguments

Value

a data frame

Examples

ADSL |>
  ard_categorical(by = ARM, variables = AGEGR1) |>
  apply_fmt_fun() |>
  unlist_ard_columns()

ADSL |>
  ard_continuous(by = ARM, variables = AGE) |>
  apply_fmt_fun() |>
  unlist_ard_columns()

Update ARDs

Description

Functions used to update ARD formatting functions and statistic labels.

This is a helper function to streamline the update process. If it does not exactly meet your needs, recall that an ARD is just a data frame and it can be modified directly.

Usage

update_ard_fmt_fun(
  x,
  variables = everything(),
  stat_names,
  fmt_fun,
  filter = TRUE,
  fmt_fn = deprecated()
)

update_ard_stat_label(
  x,
  variables = everything(),
  stat_names,
  stat_label,
  filter = TRUE
)

Arguments

Value

an ARD data frame of class 'card'

Examples

ard_continuous(ADSL, variables = AGE) |>
  update_ard_fmt_fun(stat_names = c("mean", "sd"), fmt_fun = 8L) |>
  update_ard_stat_label(stat_names = c("mean", "sd"), stat_label = "Mean (SD)") |>
  apply_fmt_fun()

# same as above, but only apply update to the Placebo level
ard_continuous(
  ADSL,
  by = ARM,
  variables = AGE,
  statistic = ~ continuous_summary_fns(c("N", "mean"))
) |>
  update_ard_fmt_fun(stat_names = "mean", fmt_fun = 8L, filter = group1_level == "Placebo") |>
  apply_fmt_fun()