Getting Started

Environment Setup and Package Installation

Environment Setup

Please ensure that R version 3.6 or higher is installed on your computer. This is required to install the cardinal package and its dependencies. You can check your current version of R by running sessionInfo() within the R console.

Installing Package Dependencies

The cardinal package requires several packages available on CRAN.

To use the cardinal package, ensure you have these necessary package dependencies installed by running the following code:

if (!require("formatters")) install.packages("formatters")
if (!require("rtables")) install.packages("rtables")
if (!require("rlistings")) install.packages("rlistings")
if (!require("tern")) install.packages("tern")

Optionally, to run the examples provided within the cardinal package and on this site you can also install the random CDISC data package, which contains example datasets, by running the following:

if (!require("random.cdisc.data")) install.packages("random.cdisc.data")

For more information on these packages, see the Additional Resources section below.

Installing the cardinal Package

To install the cardinal package, run the following line of code:

if (!require("cardinal")) remotes::install_github("pharmaverse/cardinal")

Loading Data

The table functions provided by cardinal are designed to work with any datasets which adhere to CDISC standards. If you have access to CDISC data, load this into your R environment as usual to use when generating tables.

If you do not have access to CDISC data, or want to run the examples provided within the package, you can use the random.cdisc.data package to load a selection of datasets containing example synthetic randomized CDISC data. Datasets are stored in the package by name, prefixed by the letter "c" (for “cached”). For example, after loading the random.cdisc.data package you can access an ADSL dataset by running cadsl, or ADAE with cadae. This data is loaded in where necessary as part of the provided examples.

Template Navigation

A list of all templates currently available in cardinal is provided in the Template Library Index, with tables designed based on the FDA Standard Safety Tables and Figures: Integrated Guide.

Each template provided is associated with a function available within the cardinal package, and contains 4 sections:

  • Spec. Screenshot: This tab provides a screenshot of the given table coming from the FDA Standard Safety Table and Figures document.

  • Table: This tab displays the output table corresponding to the screenshot in the previous tab, generated using the associated cardinal table function. You can expect a similar output table when using the table function with your own data, depending on pre-processing and the customizations that you apply via the table function parameters.

  • Table Setup: This tab provides the code used to generate the example table displayed in the previous tab, including the loading of necessary libraries and example datasets, and any pre-processing steps applied prior to generating the table.

  • Function Details: This tab includes details on the table-generating function used for this template. Table functions use the naming convention make_table_XX() where XX is the table number taken from the FDA Standard Safety Table and Figures document (preceded by a 0 if the number is a single digit). Any required variables for the input datasets are listed along with a description of all function arguments. This information is mirrored by the function’s help page accessible within R (i.e. ?make_table_XX).

          A link to the function’s source code can be found at the bottom of the page in this tab:

Creating Tables

There are many table-generating functions available within the cardinal package, each of which is used to generate a different FDA standard safety table using R. These functions create rtables table objects which can then be further customized, paginated, etc. if required using functions from the rtables package.

Using the Table Functions

To use the table functions you will need to load the cardinal package and then call the appropriate table function. For example, to create FDA Safety Table 2, you can run the following code:

library(dplyr)
library(cardinal)

# Data pre-processing - ensure all necessary variables are present in the data
adsl <- random.cdisc.data::cadsl %>%
  mutate(AGEGR1 = as.factor(case_when(
    AGE >= 17 & AGE < 65 ~ ">=17 to <65",
    AGE >= 65 ~ ">=65",
    AGE >= 65 & AGE < 75 ~ ">=65 to <75",
    AGE >= 75 ~ ">=75"
  )) %>% formatters::with_label("Age Group, years")) %>%
  formatters::var_relabel(AGE = "Age, years")

# Create table
tbl <- make_table_02(df = adsl)
tbl
                                                  A: Drug X            B: Placebo         C: Combination      Total Population 
Characteristic                                     (N=134)              (N=134)              (N=132)              (N=400)      
———————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
Sex                                                                                                                            
  F                                                79 (59%)            82 (61.2%)            70 (53%)           231 (57.8%)    
  M                                                55 (41%)            52 (38.8%)            62 (47%)           169 (42.2%)    
Age, years                                                                                                                     
  Mean (SD)                                       33.8 (6.6)           35.4 (7.9)           35.4 (7.7)           34.9 (7.4)    
  Median (Min - Max)                          33.0 (21.0 - 50.0)   35.0 (21.0 - 62.0)   35.0 (20.0 - 69.0)   34.0 (20.0 - 69.0)
Age Group, years                                                                                                               
  >=17 to <65                                     134 (100%)           134 (100%)          131 (99.2%)          399 (99.8%)    
  >=65                                                0                    0                 1 (0.8%)             1 (0.2%)     
Race                                                                                                                           
  ASIAN                                           68 (50.7%)            67 (50%)            73 (55.3%)           208 (52%)     
  BLACK OR AFRICAN AMERICAN                       31 (23.1%)           28 (20.9%)           32 (24.2%)           91 (22.8%)    
  WHITE                                           27 (20.1%)           26 (19.4%)           21 (15.9%)           74 (18.5%)    
  AMERICAN INDIAN OR ALASKA NATIVE                  8 (6%)             11 (8.2%)             6 (4.5%)            25 (6.2%)     
  MULTIPLE                                            0                 1 (0.7%)                0                 1 (0.2%)     
  NATIVE HAWAIIAN OR OTHER PACIFIC ISLANDER           0                 1 (0.7%)                0                 1 (0.2%)     
Ethnicity                                                                                                                      
  HISPANIC OR LATINO                              15 (11.2%)           18 (13.4%)           15 (11.4%)            48 (12%)     
  NOT HISPANIC OR LATINO                         104 (77.6%)          103 (76.9%)          101 (76.5%)           308 (77%)     
  NOT REPORTED                                     6 (4.5%)            10 (7.5%)            11 (8.3%)            27 (6.8%)     
  UNKNOWN                                          9 (6.7%)             3 (2.2%)             5 (3.8%)            17 (4.2%)     
Country                                                                                                                        
  CHN                                             74 (55.2%)           81 (60.4%)           64 (48.5%)          219 (54.8%)    
  USA                                             10 (7.5%)            13 (9.7%)            17 (12.9%)            40 (10%)     
  BRA                                             13 (9.7%)             7 (5.2%)            10 (7.6%)            30 (7.5%)     
  PAK                                              12 (9%)              9 (6.7%)            10 (7.6%)            31 (7.8%)     
  NGA                                               8 (6%)              7 (5.2%)            11 (8.3%)            26 (6.5%)     
  RUS                                              5 (3.7%)              8 (6%)              6 (4.5%)            19 (4.8%)     
  JPN                                              5 (3.7%)              4 (3%)              9 (6.8%)            18 (4.5%)     
  GBR                                               4 (3%)              3 (2.2%)             2 (1.5%)             9 (2.2%)     
  CAN                                              3 (2.2%)             2 (1.5%)             3 (2.3%)              8 (2%)

The above table is created using the default settings. You can customize tables by specifying function parameter values to set input data, variables to include in the table, table annotations, etc.

Table Customization

Each template takes several arguments that can be set to generate a table that meets your requirements. A brief overview of the parameters for each template is provided in the Function Details section of each table template page (see the Function Details section above) and the function’s help page within R (i.e. ?make_table_XX), with many of these parameters being standard across table functions.

To customize the output table, you can modify the values of these arguments as per your requirements. For example, table 2 can be customized as follows:

advs <- random.cdisc.data::cadvs %>%
  filter(AVISIT == "BASELINE", VSTESTCD == "TEMP") %>%
  select("USUBJID", "AVAL")

anl <- left_join(adsl, advs, by = "USUBJID") %>% tern::df_explicit_na()

tbl <- make_table_02(
  df = anl,
  vars = c("SEX", "AGE", "RACE", "COUNTRY", "AVAL"),
  lbl_vars = c("Sex", "Age, years", "Race", "Country of Participation", "Baseline Temperature (C)"),
  lbl_overall = "Total\nPopulation",
  na_rm = TRUE,
  annotations = list(
    title = "Table 2. Baseline Demographic and Clinical Characteristics Safety Population, Pooled Analyses",
    main_footer = "Source: [include Applicant source, datasets and/or software tools used].",
    prov_footer = paste(
      "Abbreviations: N, number of patients in treatment arm;",
      "n, number of patients with given characteristic; SD, standard deviation"
    )
  )
)
tbl
Table 2. Baseline Demographic and Clinical Characteristics Safety Population, Pooled Analyses

———————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
                                                                                                                   Total       
                                                  A: Drug X            B: Placebo         C: Combination         Population    
Characteristic                                     (N=134)              (N=134)              (N=132)              (N=400)      
———————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————
Sex                                                                                                                            
  F                                                79 (59%)            82 (61.2%)            70 (53%)           231 (57.8%)    
  M                                                55 (41%)            52 (38.8%)            62 (47%)           169 (42.2%)    
Age, years                                                                                                                     
  Mean (SD)                                       33.8 (6.6)           35.4 (7.9)           35.4 (7.7)           34.9 (7.4)    
  Median (Min - Max)                          33.0 (21.0 - 50.0)   35.0 (21.0 - 62.0)   35.0 (20.0 - 69.0)   34.0 (20.0 - 69.0)
Race                                                                                                                           
  ASIAN                                           68 (50.7%)            67 (50%)            73 (55.3%)           208 (52%)     
  BLACK OR AFRICAN AMERICAN                       31 (23.1%)           28 (20.9%)           32 (24.2%)           91 (22.8%)    
  WHITE                                           27 (20.1%)           26 (19.4%)           21 (15.9%)           74 (18.5%)    
  AMERICAN INDIAN OR ALASKA NATIVE                  8 (6%)             11 (8.2%)             6 (4.5%)            25 (6.2%)     
  MULTIPLE                                            0                 1 (0.7%)                0                 1 (0.2%)     
  NATIVE HAWAIIAN OR OTHER PACIFIC ISLANDER           0                 1 (0.7%)                0                 1 (0.2%)     
Country of Participation                                                                                                       
  CHN                                             74 (55.2%)           81 (60.4%)           64 (48.5%)          219 (54.8%)    
  USA                                             10 (7.5%)            13 (9.7%)            17 (12.9%)            40 (10%)     
  BRA                                             13 (9.7%)             7 (5.2%)            10 (7.6%)            30 (7.5%)     
  PAK                                              12 (9%)              9 (6.7%)            10 (7.6%)            31 (7.8%)     
  NGA                                               8 (6%)              7 (5.2%)            11 (8.3%)            26 (6.5%)     
  RUS                                              5 (3.7%)              8 (6%)              6 (4.5%)            19 (4.8%)     
  JPN                                              5 (3.7%)              4 (3%)              9 (6.8%)            18 (4.5%)     
  GBR                                               4 (3%)              3 (2.2%)             2 (1.5%)             9 (2.2%)     
  CAN                                              3 (2.2%)             2 (1.5%)             3 (2.3%)              8 (2%)      
Baseline Temperature (C)                                                                                                       
  Mean (SD)                                       36.7 (1.0)           36.6 (1.1)           36.5 (1.0)           36.6 (1.0)    
  Median (Min - Max)                          36.7 (34.0 - 39.3)   36.6 (33.6 - 38.9)   36.5 (34.2 - 38.9)   36.6 (33.6 - 39.3)
———————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————

Source: [include Applicant source, datasets and/or software tools used].

Abbreviations: N, number of patients in treatment arm; n, number of patients with given characteristic; SD, standard deviation

Note that the prune_0 argument can be set to specify whether all-zero rows should be included in a table. For example, see that the demographics table below includes rows for OTHER and UNKNOWN for which all values are zero, whereas these two rows were excluded from the previous tables (prune_0 defaults to TRUE in make_table_02()).

make_table_02(df = anl, vars = "RACE", prune_0 = FALSE)
                                              A: Drug X    B: Placebo   C: Combination   Total Population
Characteristic                                 (N=134)      (N=134)        (N=132)           (N=400)     
—————————————————————————————————————————————————————————————————————————————————————————————————————————
Race                                                                                                     
  ASIAN                                       68 (50.7%)    67 (50%)      73 (55.3%)        208 (52%)    
  BLACK OR AFRICAN AMERICAN                   31 (23.1%)   28 (20.9%)     32 (24.2%)        91 (22.8%)   
  WHITE                                       27 (20.1%)   26 (19.4%)     21 (15.9%)        74 (18.5%)   
  AMERICAN INDIAN OR ALASKA NATIVE              8 (6%)     11 (8.2%)       6 (4.5%)         25 (6.2%)    
  MULTIPLE                                        0         1 (0.7%)          0              1 (0.2%)    
  NATIVE HAWAIIAN OR OTHER PACIFIC ISLANDER       0         1 (0.7%)          0              1 (0.2%)    
  OTHER                                           0            0              0                 0        
  UNKNOWN                                         0            0              0                 0

Feature Requests

If you would like to request the addition of a new feature to a pre-existing function within cardinal, or would like a specific table template to be added, please file an issue on GitHub here or reach out to the cardinal team directly via our Slack channel here.

You can access the source code for all currently available functions in the cardinal GitHub repository here.

Additional Resources

See the following packages used by cardinal for more information: