Package {cardinalfda}

Type: Package
Title: FDA Safety Tables and Figures
Version: 0.2.0
Date: 2026-07-09
Description: Provides implementations of safety tables and figures recommended by the FDA (U.S. Food and Drug Administration) for clinical trial reporting. Functions generate standard outputs for adverse events, laboratory abnormalities, vital signs, exposure, and other safety domains following the FDA's Safety Reporting guidelines. Outputs are built on the 'gtsummary', 'cards', and 'cardx' frameworks, enabling reproducible and submission-ready clinical trial safety summaries.
License: Apache License (≥ 2)
URL: https://github.com/pharmaverse/cardinal/, https://pharmaverse.github.io/cardinal/
BugReports: https://github.com/pharmaverse/cardinal/issues
Depends: R (≥ 4.2), cards (≥ 0.8.1), cardx (≥ 0.3.4), gtsummary (≥ 2.5.1)
Imports: dplyr (≥ 1.2.1)
Suggests: cowplot (≥ 1.2.0), crane (≥ 0.3.1), forcats (≥ 1.0.1), ggplot2 (≥ 4.0), ggsurvfit (≥ 1.2.0), gt (≥ 1.3.0), knitr (≥ 1.50), labelled (≥ 2.16.0), lubridate (≥ 1.9), pharmaverseadam (≥ 1.3.0), purrr (≥ 1.2), random.cdisc.data (≥ 0.3.16), rlang (≥ 1.1.7), rtables (≥ 0.6.11), tern (≥ 0.9.8), svglite (≥ 2.2.2), testthat (≥ 3.3.1), tidyr (≥ 1.3.1), withr (≥ 3.0.2)
Config/testthat/edition: 3
Encoding: UTF-8
Language: en-US
RoxygenNote: 8.0.0
NeedsCompilation: no
Packaged: 2026-07-24 08:50:51 UTC; zhus31
Author: Pawel Rucki [ctb], Abinaya Yogasekaram ORCID iD [aut], Joe Zhu ORCID iD [cre], Daniel D. Sjoberg ORCID iD [ctb], Emily de la Rua ORCID iD [aut], Vincent Shen [aut], Benoit Falquet ORCID iD [ctb], Lluís Revilla Sancho ORCID iD [ctb], Huan Lu [ctb], Alex Assuied [ctb], Yoshito Koujin [ctb], Korbinian Matthias [ctb], Jessica Knizia [ctb], Freeman Wang [ctb]
Maintainer: Joe Zhu <joe.zhu@roche.com>
Repository: CRAN
Date/Publication: 2026-08-04 09:50:02 UTC

cardinalfda

Description

Implementation of FDA Safety Tables and Figures

Author(s)

Maintainer: Joe Zhu joe.zhu@roche.com (ORCID)

Authors:

Other contributors:

See Also

Useful links:

Pre-Process alt_counts_df for Safety Population

Description

If alt_counts_df is not NULL, will check for required variables (arm_var) and filter to include only safety population (saffl_var, if specified), then apply tern::df_explicit_na().

Usage

alt_counts_df_preproc(
  alt_counts_df,
  id_var = "USUBJID",
  arm_var = "ARM",
  saffl_var = NULL
)

Arguments

alt_counts_df

(character)
alternative dataset (typically ADSL) used only to calculate column counts.

id_var

(character)
Name of the unique subject identifiers variable.

arm_var

(character)
Name of the treatment arm variable used to split table into columns.

saffl_var

(character)
Name of the safety flag variable which must contain at least "Y" for "Yes".

Value

A data.frame (modified alt_counts_df) or NULL.

Standard Arguments

Description

This documentation lists all the arguments in cardinal that are used repeatedly by functions to output tables.

Arguments

show_colcounts

(flag)
Whether column counts should be printed. Boolean.

arm_var

(character)
Name of the treatment arm variable used to split table into columns.

id_var

(character)
Name of the unique subject identifiers variable.

saffl_var

(character)
Name of the safety flag variable which must contain at least "Y" for "Yes".

ser_var

(character)
Name of the serious adverse event flag variable which must contain at least "Y" for "Yes".

lbl_overall

(character)
Optional. If specified, an overall column will be added to the table with the given value as the column label.

vars

(vector of character)
Variables from df to include in the table.

lbl_vars

(vector of character)
Labels corresponding to variables in vars to print in the table. Labels should be ordered according to the order of variables in vars.

pref_var

(character)
Name of the preferred term variable from adae to include in the table.

soc_var

(character)
Name of the system organ class variable from adae to include in the table.

lbl_pref_var

(character)
Label corresponding to preferred term variable pref_var to print in the table.

lbl_soc_var

(character)
Label corresponding to system organ class variable soc_var to print in the table.

.stats

(character)
Statistics to include in the table. Includes statistics for all variable types (only the statistics that are valid for a given variable's type will be printed). See tern::analyze_vars() for options.

.formats

(named list of character)
List of formats corresponding to each value in .stats. Each name is a value in .stats and the corresponding value is the format that should be applied to that statistic. See formatters::list_valid_format_labels() for a list of valid formats.

na_rm

(flag)
Whether NA levels should be removed from the table.

prune_0

(flag)
Whether all-zero rows should be removed from the table. Boolean.

na_level

(character)
String to represent missing values.

adae

(data.frame)
dataset (typically ADAE) required to build table.

adex

(data.frame)
dataset (typically ADEX) required to build table.

advs

(data.frame)
dataset (typically ADVS) required to build table.

adsl

(data.frame)
dataset (typically ADSL) required to build table.

alt_counts_df

(character)
alternative dataset (typically ADSL) used only to calculate column counts.

annotations

(named list of character)
list of annotations to add to the table. Valid annotation types are title, subtitles, main_footer, and prov_footer. Each name-value pair should use the annotation type as name and the desired string as value.

ard

(cards::card)
an ARD.

denominator

(data.frame)
alternative dataset (typically ADSL) used only to calculate denominator counts.

df

(data.frame)
dataset required to build table.

eosdy_var

(character)
variable denoting last recorded (relative) study day.

fmqsc_var

(character)
FMQ scope variable to use in table.

fmqnam_var

(character)
FMQ reference name variable to use in table.

fmq_scope

(character)
FMQ scope ("NARROW" or "BROAD") to output in table.

ggtheme

(theme)
a graphical theme as provided by ggplot2 to control styling of the ggplot object.

return_ard

(flag)
whether an ARD should be returned. Defaults to TRUE.

risk_diff

(named list)
list of settings to apply to add one or more risk difference columns to the table. Defaults to NULL (no risk difference column added). See tern::add_riskdiff() for more details. List should contain the following elements:

  • arm_x: (required) the name of reference arm.

  • arm_y: (required) the names of the arms to compare to the reference arm. A new column will be added for each element of arm_y.

  • col_label: (optional) labels to use for the risk difference columns. Defaults to "Risk Difference (%) (95% CI)". For more than one risk difference column, "arm x vs. arm y" text will also be included in the column labels by default. The length of col_label must be equal to the length of arm_y.

  • pct: (optional) whether the output should be returned as percentages. Defaults to TRUE.

sex_scope

(character)
Level of SEX to output in table.

table_engine

(string)
table engine used to generate the table. If NULL, no table is returned. If the given engine is not available for the table, no table is created and a warning is returned.

trtedtm_var

(character)
treatment end datetime variable.

trtemfl_var

(character)
flag variable used to identify Treatment-emergent AE.

trtsdtm_var

(character)
treatment start datetime variable.

u_trtdur

(character)
unit for duration of treatment. Options are "days", "weeks", "months", and "years".

xticks

(vector of numeric)
x-axis tick positions. If NA (default), tick mark positions are automatically calculated.

x_lab

(character)
x-axis label.

yticks

(vector of numeric)
y-axis tick positions. If NA (default), tick mark positions are automatically calculated.

y_lab

(character)
y-axis label.

Check Values of Flag Variables

Description

Flag variables are expected to take one of two values: "Y" (yes/true) or "N" (no/false). Missing values are also accepted and treated as "N".

Usage

assert_flag_variables(df, flag_vars, na_level = "<Missing>")

Arguments

df

(data.frame)
dataset required to build table.

flag_vars

(vector of character)
names of flag variables within df to check.

na_level

(character)
String to represent missing values.

Value

Invisibly returns TRUE if all flag variables are valid; otherwise stops with an error.

Initialize Table Layout with Annotations

Description

Initializes a table layout via rtables::basic_table() and applies show_colcounts argument. Adds any annotations supplied via the annotations argument.

Usage

basic_table_annot(show_colcounts = TRUE, annotations = NULL)

Arguments

show_colcounts

(flag)
Whether column counts should be printed. Boolean.

annotations

(named list of character)
list of annotations to add to the table. Valid annotation types are title, subtitles, main_footer, and prov_footer. Each name-value pair should use the annotation type as name and the desired string as value.

Value

An rtables PreDataTableLayouts object suitable for passing to further layout functions, and to build_table.

FDA Table 2: Baseline Demographic and Clinical Characteristics, Safety Population, Pooled Analyses

Description

Creates FDA Table 2 showing baseline demographic and clinical characteristics for the safety population.

Usage

make_table_02(
  df,
  return_ard = TRUE,
  arm_var = "TRT01A",
  saffl_var = "SAFFL",
  vars = c("SEX", "AGE", "AGEGR1", "ETHNIC", "RACE"),
  label = list()
)

Arguments

df

(data.frame)
dataset (typically ADSL) required to build the table.

return_ard

(flag)
whether an ARD should be returned. Defaults to TRUE.

arm_var

(character)
name of the treatment arm variable used to split table into columns. Defaults to "TRT01A".

saffl_var

(character)
name of the safety flag variable. Defaults to "SAFFL".

vars

(character)
variables from df to include in the table. Defaults to c("SEX", "AGE", "AGEGR1", "ETHNIC", "RACE").

label

(named list)
variable labels passed to gtsummary::tbl_summary(). Defaults to list().

Details

Value

A gtsummary table, or if return_ard = TRUE, a named list with elements table and ard.

Examples


library(dplyr)

adsl <- pharmaverseadam::adsl |>
  filter(TRT01A != "Screen Failure")

result <- make_table_02(df = adsl)
result$table

Split Columns by Arm Variable

Description

Splits rtables layout into columns by arm variable. Appends an "overall" column as the rightmost column if lbl_overall is supplied.

Usage

split_cols_by_arm(lyt, arm_var = "ARM", lbl_overall = NULL, risk_diff = NULL)

Arguments

lyt

(rtables layout object)
Layout object pre-data used for tabulation.

arm_var

(character)
Name of the treatment arm variable used to split table into columns.

lbl_overall

(character)
Optional. If specified, an overall column will be added to the table with the given value as the column label.

risk_diff

(named list)
list of settings to apply to add one or more risk difference columns to the table. Defaults to NULL (no risk difference column added). See tern::add_riskdiff() for more details. List should contain the following elements:

  • arm_x: (required) the name of reference arm.

  • arm_y: (required) the names of the arms to compare to the reference arm. A new column will be added for each element of arm_y.

  • col_label: (optional) labels to use for the risk difference columns. Defaults to "Risk Difference (%) (95% CI)". For more than one risk difference column, "arm x vs. arm y" text will also be included in the column labels by default. The length of col_label must be equal to the length of arm_y.

  • pct: (optional) whether the output should be returned as percentages. Defaults to TRUE.

Value

An rtables PreDataTableLayouts object suitable for passing to further layout functions, and to build_table.