Title:	Analysis Results Data
Version:	0.4.0
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), rlang (≥ 1.1.1), tidyr (≥ 1.3.0), tidyselect (≥ 1.2.0)
Suggests:	spelling (≥ 2.2.0), testthat (≥ 3.2.0), withr (≥ 3.0.0)
Config/Needs/check:	hms
Config/Needs/website:	rmarkdown, jsonlite, yaml, gtsummary, tfrmt, 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:	2024-11-27 04:52:57 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:	2024-11-27 06:50:02 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)

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_fn(x)

Arguments

Value

a data frame

Examples

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

cards:::.default_fmt_fn(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

Value

a data frame

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, 100 percent 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")

List Column as a Vector Predicate

Description

A predicate function to check whether a column is a list and can be represented as a vector.

Usage

.is_list_column_of_scalars(x)

Arguments

Value

a logical

Examples

cards:::.is_list_column_of_scalars(as.list(1:5))

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_fn() |>
  cards:::.one_row_ard_to_nested_list()

Pair columns

Description

This function ingests an ARD object and finds pairs of columns based on those requested for coalescing/renaming

Usage

.pair_columns(x, columns)

Arguments

Value

a list of column pairs (as character vectors)

Examples

ard_categorical(ADSL, by = "ARM", variables = "AGEGR1") |>
  cards:::.pair_columns(columns = c("group1", "group1_level", "variable", "variable_level"))

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)

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)

Shift column pair

Description

This function ingests an ARD object and coalesces/renames a given pair of columns (variable and levels)

Usage

.shift_column_pair(x, col_pair)

Arguments

Value

a tibble

Examples

ard_categorical(ADSL, by = "ARM", variables = "AGEGR1") |>
  cards:::.shift_column_pair(col_pair = c("group1", "group1_level"))

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 48 columns.

An object of class tbl_df (inherits from tbl, data.frame) with 1191 rows and 55 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_fn = NULL
)

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_fn(x, variable, stat_name)

Arguments

Value

a function

Examples

alias_as_fmt_fn(1)
alias_as_fmt_fn("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_fn().

Usage

apply_fmt_fn(x, replace = FALSE)

Arguments

Value

an ARD data frame of class 'card'

Examples

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

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

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 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 string: one of "column", "row", or "cell". "column" is equivalent to denominator=NULL. "row" gives 'row' percentages where by/strata columns are the 'top' of a cross table, and the variables are the rows. "cell" gives percentages where the denominator is the number of non-missing rows in the source data frame.

• 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.

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_fn
#> 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_fn = NULL,
  stat_label = everything() ~ default_stat_labels(),
  ...
)

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_fn = NULL,
  stat_label = everything() ~ default_stat_labels(),
  ...
)

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_fn = NULL,
  stat_label = everything() ~ default_stat_labels(),
  ...
)

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 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 string: one of "column", "row", or "cell". "column" is equivalent to denominator=NULL. "row" gives 'row' percentages where by/strata columns are the 'top' of a cross table, and the variables are the rows. "cell" gives percentages where the denominator is the number of non-missing rows in the source data frame.

• 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_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"
  )

Hierarchical ARD Statistics

Description

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

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 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 string: one of "column", "row", or "cell". "column" is equivalent to denominator=NULL. "row" gives 'row' percentages where by/strata columns are the 'top' of a cross table, and the variables are the rows. "cell" gives percentages where the denominator is the number of non-missing rows in the source data frame.

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

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

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_fn = NULL,
  stat_label = everything() ~ default_stat_labels(),
  ...
)

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 |> dplyr::rename(TRTA = ARM),
  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 |> dplyr::rename(TRTA = ARM),
  overall = TRUE
)

Examples

ard_stack_hierarchical(
  ADAE,
  variables = c(AESOC, AEDECOD),
  by = TRTA,
  denominator = ADSL |> dplyr::rename(TRTA = ARM),
  id = USUBJID
)

ard_stack_hierarchical_count(
  ADAE,
  variables = c(AESOC, AEDECOD),
  by = TRTA,
  denominator = ADSL |> dplyr::rename(TRTA = ARM)
)

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)

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

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

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_cards(digits = 1, scale = 1, width = NULL)

Arguments

Value

a function

Examples

label_cards(2)(pi)
label_cards(1, scale = 100)(pi)
label_cards(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_fn()

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_fn(variables = c("AGE", "BMIBL"), stat_names = "sd", fmt_fn = \(x) "xx.xx") |>
  apply_fmt_fn()

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

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

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

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 Columns

Description

This function combines a pair of group/group_level or variable/variable_level columns into a single column. The group_level or variable_level column is renamed according to the value of the group or variable column, respectively.

Usage

rename_ard_columns(
  x,
  columns = c(all_ard_groups(), all_ard_variables()),
  unlist = NULL
)

Arguments

Value

data frame

Examples

ADSL |>
  ard_categorical(by = ARM, variables = AGEGR1) |>
  apply_fmt_fn() |>
  rename_ard_columns(unlist = c(stat, stat_fmt))

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, round5(0.5) = 1.

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)

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

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 variables, groups, and strata, while retaining the order of the input ARD.

Usage

tidy_ard_column_order(x)

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

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_fn(
  x,
  variables = everything(),
  stat_names,
  fmt_fn,
  filter = TRUE
)

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_fn(stat_names = c("mean", "sd"), fmt_fn = 8L) |>
  update_ard_stat_label(stat_names = c("mean", "sd"), stat_label = "Mean (SD)") |>
  apply_fmt_fn()

# 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_fn(stat_names = "mean", fmt_fn = 8L, filter = group1_level == "Placebo") |>
  apply_fmt_fn()