Package {cardinalfda}

Type: Package
Title: FDA Safety Tables and Figures
Version: 0.3.0
Date: 2026-09-04
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: cards (≥ 0.8.1), cardx (≥ 0.3.4), crane (≥ 0.3.1), gtsummary (≥ 2.5.1), R (≥ 4.2)
Imports: dplyr (≥ 1.2.0)
Suggests: cowplot (≥ 1.2.0), 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), svglite (≥ 2.2.2), tern (≥ 0.9.8), testthat (≥ 3.3.1), tidyr (≥ 1.3.1), withr (≥ 3.0.2)
Config/roxygen2/version: 8.1.0
Config/testthat/edition: 3
Encoding: UTF-8
Language: en-US
NeedsCompilation: no
Packaged: 2026-09-04 16:03:33 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], Davide Garolini 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-09-04 16:30:08 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 cardinalfda 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.

Run a Table or Figure Template Script

Description

Source one of the self-contained template scripts shipped in inst/templates and return the object it builds. Each template is a plain R script that produces a tbl object (and, where relevant, an ard), so the same script can be run here for testing, copied into the catalog, or handed to a user as a starting point.

Keeping the full script as the single source of truth avoids drifting between what is tested and what is published in the catalog.

Usage

run_template(name, envir = new.env(parent = parent.frame()))

Arguments

name

(character(1))
template name without extension, e.g. "fda-table_07". Must match a file ⁠inst/templates/<name>.R⁠.

envir

(environment)
environment in which the script is evaluated. A fresh child of the caller is used by default so template objects do not leak into the caller.

Value

the environment the template was evaluated in, invisibly. Template objects (such as tbl and ard) are available as bindings in it.

Examples

## Not run: 
env <- run_template("fda-table_07")
env$tbl

## End(Not run)

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.