Adding new TLGs to Chevron

2022-06-09

Acknowledgments

Introduction

The chevron package is a collection of function to create standard tables, listings, and graphs for clinical trials reporting. Here we present the logic to request new tables for the end users and how to construct new table functions for the programmers. The list of the already available functions is available here. The naming convention for table functions is <table name>_<design number>. ex: aet02_2. The default design number is by convention the number 1. Layouts are internal functions that determine the underlying structure of a table. One table function is generally associated with one layout function. The naming convention for layout is <table name>_<design number>_lyt. ex: aet02_2_lyt.

How to request a table

In order to request a function that will generate a new table, please create an issue in the “TLG (ordered priority)” of the chevron backlog. Private repositories on GitHub do not support yaml issue templates but you can use the format below to accurately describe your requirements. Adding images of the required table (without confidential information) is also very useful. Several designs of the same table can be (should be) requested in a same issue.

ex: AET02

Table Name

Standard name of the table. [see GDSR template]
ex. AET02

URL

Link to an external file describing the table

Description

Details on the generic purpose of the table
ex. This is an adverse event table

Analysis dataset

Name of the standard dataset input
ex. ADAE

Analysis filtering

Filtering criteria of the input
ex. ANL01FL = “Y”

Analysis population

The selected population, typically SE, AP or IT
ex. SE

Column Variable

Names of the columns splitting variables in hierarchical order
ex. ACTARM

Analysis variables

Names of the rows splitting variables in hierarchical order
ex. AEBODSYS, AEDECOD, ASEV
ex.
1. AEBODSYS
2. AEDECOD
3. ASEV

Analysis concept

Alternative table description for summary tables similar to AET01
ex.
- Serious AE
- Related AE
- Total number of AEs

Statistics

Description of the statistical procedure
ex. Frequency count and % (based on N)

Default treatment of zero count rows

Choose one option:
- “Remove zero count rows by default”
- “Keep zero count rows by default”
- “Always ask for user input”
- “Not applicable / Other”

Comments

ex. Some additional details

How to create a new table function for developers

The current practice is to use the body of the table-creating function to isolate the variable names that are used to construct the table layout. The function then calls the corresponding layout function to create the structure of the table. It then builds the table by combining the clinical data and the layout. Finally, it modifies the table based on the aggregated results, for instance removing the rows with no counts, and returns the table.

Data preprocessing

Data processing and standardization should be performed before feeding the data to chevron. Beware of levels that are not present in the test data but could appear in real datasets.

Arguments

To enhance the reproducibility, it is advised to reduce the parametrization of the table-constructing function. Some arguments are specific to an entire study and used in multiple tables, for instance the choice of the variable used to specify the arm of the study (should it be ARM or ACTARM?). Such arguments should be defined in the .study object, which is then passed to the function. The list of argument accepted by the study object is defined below. Other arguments are more specific to a particular table (e.g Should zero count rows be removed?) and should be accessible to the end-user insofar as it cannot compromise the accuracy of the report. Appropriate default values should be provided.

The .study object

The following variables are best hard coded in the table-generating functions (with the possibility to the user to override some of these choices.): - evo_vars (used in LBT01, which variables capture status and the evolution of the analysis): generally c("AVAL", "CNG") - severity_grade (internal, used in AET03, capture the levels of severity of adverse events): generally corresponds to the levels of AESEVin adae. - lbl_overall (used everywhere, the label associated with the overall column) - reason (used in DST01, the name of the column specifying study withdrawal): generally DCSREAS. - status (used in DST01, the name of the column specifying study status): generally: EOSSTT. - summaryvars (used in DMT01, the list of variables to be summarized):

The .study object contains information relative to the way the study is analyzed. - “Patient” or “Subject” (the designation of the person depends on the study) - armvar (Randomized arm variable): generally: ARMor ACTARM. - Actually received variable - format: of percentages etc…

Tests

TODO