Introduction

The chevron R package provides functions to produce standard tables, listings and graphs (TLGs) used to analyze and report clinical trials data. We refer to these functions as tlg-functions. The tlg-functions in chevron use other packages to produce the final outputs, for example rtables and tern are used to create listings and tables, and ggplot2, lattice, and grid are used to create graphs.

tlg-functions in chevron such as dmt01_1, aet02_1, aet02_2 have the following properties:

  1. they produce a narrow defined output (currently standards in Roche GDS). Note, that the naming convention <gds template id>_<i> indicates that a Roche GDS defined standard may have different implementations. Or, alternatively, a GDS template id can be regarded as a guideline and the function name in chevron as a standard.
  2. have very few arguments to modify the standard. Generally, arguments may change the structure of the table (arm variable, which variables are summarized) but not parameterize the cell content (i.e. alpha-level for p-value).
  3. have always the first argument adam_db which is the collection of ADaM datasets (ADSL, ADAE, ADRS, etc.). Please read the The adam_db Argument vignette in this package for more details.
  4. have a .study argument, read the The .study argument vignette for more detail.

Example AET02

For example, the GDS template aet02 is implemented in chevron with tlg-functions that have the name aet02_*. The function documentation which is accessible with the help function, e.g. help('aet02_1') documents what is particular in the _1 implementation.

We first define the data and put it in a dm object, you can find more details about this in the adam_db vignette.

library(dm)
#> 
#> Attaching package: 'dm'
#> The following object is masked from 'package:stats':
#> 
#>     filter
library(scda)
#> 

syn_data <- synthetic_cdisc_data("latest")

adam_study_data <- dm(adsl = syn_data$adsl, adae = syn_data$adae) %>%
  dm_add_pk(adsl, c("USUBJID", "STUDYID")) %>%
  dm_add_fk(adae, c("USUBJID", "STUDYID"), ref_table = "adsl") %>%
  dm_add_pk(adae, c("USUBJID", "STUDYID", "ASTDTM", "AETERM", "AESEQ"))

validate_dm(adam_study_data)

A the aet02_1 output is then created as follows:

library(chevron)
#> Registered S3 method overwritten by 'tern':
#>   method   from 
#>   tidy.glm broom

db <- adam_study_data %>%
  preprocess_data("aet02_1")

aet02_1(adam_db = db)
#> Adverse Events: {Specify Population}
#> Protocol: {{protocol}}
#> 
#> ——————————————————————————————————————————————————————————————————————————————————————————————————————
#> Body System or Organ Class                                   A: Drug X    B: Placebo    C: Combination
#>   Dictionary-Derived Term                                     (N=134)       (N=134)        (N=132)    
#> ——————————————————————————————————————————————————————————————————————————————————————————————————————
#> Total number of patients with at least one adverse event     97 (72.4%)   103 (76.9%)    102 (77.3%)  
#> Overall total number of events                                  469           513            599      
#> cl A.1                                                                                                
#>   Total number of patients with at least one adverse event   62 (46.3%)   64 (47.8%)      77 (58.3%)  
#>   Total number of events                                        107           109            140      
#>   dcd A.1.1.1.1                                              42 (31.3%)   36 (26.9%)      54 (40.9%)  
#>   dcd A.1.1.1.2                                              37 (27.6%)   44 (32.8%)      43 (32.6%)  
#> cl B.2                                                                                                
#>   Total number of patients with at least one adverse event    59 (44%)     59 (44%)       73 (55.3%)  
#>   Total number of events                                         95           110            125      
#>   dcd B.2.2.3.1                                              38 (28.4%)   42 (31.3%)      42 (31.8%)  
#>   dcd B.2.1.2.1                                              36 (26.9%)   37 (27.6%)      45 (34.1%)  
#> cl D.1                                                                                                
#>   Total number of patients with at least one adverse event   60 (44.8%)   56 (41.8%)      67 (50.8%)  
#>   Total number of events                                        100           88             110      
#>   dcd D.1.1.1.1                                              40 (29.9%)   32 (23.9%)      43 (32.6%)  
#>   dcd D.1.1.4.2                                              37 (27.6%)   37 (27.6%)      41 (31.1%)  
#> cl C.2                                                                                                
#>   Total number of patients with at least one adverse event   26 (19.4%)   38 (28.4%)      49 (37.1%)  
#>   Total number of events                                         36           43              57      
#>   dcd C.2.1.2.1                                              26 (19.4%)   38 (28.4%)      49 (37.1%)  
#> cl D.2                                                                                                
#>   Total number of patients with at least one adverse event   35 (26.1%)   50 (37.3%)      49 (37.1%)  
#>   Total number of events                                         45           62              63      
#>   dcd D.2.1.5.3                                              35 (26.1%)   50 (37.3%)      49 (37.1%)  
#> cl B.1                                                                                                
#>   Total number of patients with at least one adverse event   37 (27.6%)   40 (29.9%)      36 (27.3%)  
#>   Total number of events                                         43           46              51      
#>   dcd B.1.1.1.1                                              37 (27.6%)   40 (29.9%)      36 (27.3%)  
#> cl C.1                                                                                                
#>   Total number of patients with at least one adverse event   32 (23.9%)   38 (28.4%)      35 (26.5%)  
#>   Total number of events                                         43           55              53      
#>   dcd C.1.1.1.3                                              32 (23.9%)   38 (28.4%)      35 (26.5%)  
#> ——————————————————————————————————————————————————————————————————————————————————————————————————————
#> 
#> Investigator text for AEs encoded using MedDRA version xx.x.  Percentages are based on N in the column headings. For frequency counts by preferred term, multiple occurrences of the same AE in an individual are counted only once.  For frequency counts of "Total number of events" rows, multiple occurrences of the same AE in an individual are counted separately. Standard footnote defining AEs included in table (e.g., includes AEs with onset from first dose of study drug through 7 days after last dose of study drug).

More on preprocess_data and processing map

The preprocess_data function determines the the preprocessing using a processing map which is referred to in chevron as pmap.

The standard preprocessing map that comes with the tlg-functions in chevron can be access via std_pmap

head(std_pmap)
#> # A tibble: 6 × 4
#>   tlgfname filter_fname        mutate_fname     req_data 
#>   <chr>    <chr>               <chr>            <list>   
#> 1 aet01_1  filter_adae_anl01fl mutate_for_aet01 <chr [2]>
#> 2 aet01_2  filter_adae_anl01fl mutate_for_aet01 <chr [2]>
#> 3 aet02_1  filter_adae_anl01fl NA               <chr [2]>
#> 4 aet02_2  filter_adae_anl01fl NA               <chr [2]>
#> 5 aet02_3  filter_adae_anl01fl NA               <chr [2]>
#> 6 aet03_1  filter_adae_anl01fl NA               <chr [2]>

For example, for aet02_1:

  1. the adam_db data gets filtered by the function filter_adae_anl01fl
  2. the adam_db does not get mutated (NA maps to identity)
  3. and the required data are in the req_data column accessible by
unlist(std_pmap[std_pmap$tlgfname == "aet02_1", "req_data", drop = TRUE])
#> [1] "adsl" "adae"

Note that you can access the explicit functions with std_filter_fun and std_mutate_fun

std_filter_fun("aet02_1")
#> function (adam_db) 
#> {
#>     checkmate::assert_class(adam_db, "dm")
#>     adam_db %>% dm_zoom_to("adae") %>% filter(.data$ANL01FL == 
#>         "Y") %>% dm_update_zoomed()
#> }
#> <bytecode: 0x557e165477b8>
#> <environment: namespace:chevron>

and

std_mutate_fun("aet02_1")
#> function (x) 
#> x
#> <bytecode: 0x557e03e7a488>
#> <environment: namespace:base>

so alternatively one can also create the output above with

db <- adam_study_data %>%
  (std_filter_fun("aet02_1"))() %>%
  (std_mutate_fun("aet02_1"))()

aet02_1(adam_db = db)
#> Adverse Events: {Specify Population}
#> Protocol: {{protocol}}
#> 
#> ——————————————————————————————————————————————————————————————————————————————————————————————————————
#> Body System or Organ Class                                   A: Drug X    B: Placebo    C: Combination
#>   Dictionary-Derived Term                                     (N=134)       (N=134)        (N=132)    
#> ——————————————————————————————————————————————————————————————————————————————————————————————————————
#> Total number of patients with at least one adverse event     97 (72.4%)   103 (76.9%)    102 (77.3%)  
#> Overall total number of events                                  469           513            599      
#> cl A.1                                                                                                
#>   Total number of patients with at least one adverse event   62 (46.3%)   64 (47.8%)      77 (58.3%)  
#>   Total number of events                                        107           109            140      
#>   dcd A.1.1.1.1                                              42 (31.3%)   36 (26.9%)      54 (40.9%)  
#>   dcd A.1.1.1.2                                              37 (27.6%)   44 (32.8%)      43 (32.6%)  
#> cl B.2                                                                                                
#>   Total number of patients with at least one adverse event    59 (44%)     59 (44%)       73 (55.3%)  
#>   Total number of events                                         95           110            125      
#>   dcd B.2.2.3.1                                              38 (28.4%)   42 (31.3%)      42 (31.8%)  
#>   dcd B.2.1.2.1                                              36 (26.9%)   37 (27.6%)      45 (34.1%)  
#> cl D.1                                                                                                
#>   Total number of patients with at least one adverse event   60 (44.8%)   56 (41.8%)      67 (50.8%)  
#>   Total number of events                                        100           88             110      
#>   dcd D.1.1.1.1                                              40 (29.9%)   32 (23.9%)      43 (32.6%)  
#>   dcd D.1.1.4.2                                              37 (27.6%)   37 (27.6%)      41 (31.1%)  
#> cl C.2                                                                                                
#>   Total number of patients with at least one adverse event   26 (19.4%)   38 (28.4%)      49 (37.1%)  
#>   Total number of events                                         36           43              57      
#>   dcd C.2.1.2.1                                              26 (19.4%)   38 (28.4%)      49 (37.1%)  
#> cl D.2                                                                                                
#>   Total number of patients with at least one adverse event   35 (26.1%)   50 (37.3%)      49 (37.1%)  
#>   Total number of events                                         45           62              63      
#>   dcd D.2.1.5.3                                              35 (26.1%)   50 (37.3%)      49 (37.1%)  
#> cl B.1                                                                                                
#>   Total number of patients with at least one adverse event   37 (27.6%)   40 (29.9%)      36 (27.3%)  
#>   Total number of events                                         43           46              51      
#>   dcd B.1.1.1.1                                              37 (27.6%)   40 (29.9%)      36 (27.3%)  
#> cl C.1                                                                                                
#>   Total number of patients with at least one adverse event   32 (23.9%)   38 (28.4%)      35 (26.5%)  
#>   Total number of events                                         43           55              53      
#>   dcd C.1.1.1.3                                              32 (23.9%)   38 (28.4%)      35 (26.5%)  
#> ——————————————————————————————————————————————————————————————————————————————————————————————————————
#> 
#> Investigator text for AEs encoded using MedDRA version xx.x.  Percentages are based on N in the column headings. For frequency counts by preferred term, multiple occurrences of the same AE in an individual are counted only once.  For frequency counts of "Total number of events" rows, multiple occurrences of the same AE in an individual are counted separately. Standard footnote defining AEs included in table (e.g., includes AEs with onset from first dose of study drug through 7 days after last dose of study drug).