Adding_new_TLGs_to_Chevron.Rmd
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
.
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. AET02URL
Link to an external file describing the table
Description
Details on the generic purpose of the table
ex. This is an adverse event tableAnalysis dataset
Name of the standard dataset input
ex. ADAEAnalysis filtering
Filtering criteria of the input
ex. ANL01FL = “Y”Analysis population
The selected population, typically SE, AP or IT
ex. SEColumn Variable
Names of the columns splitting variables in hierarchical order
ex. ACTARMAnalysis variables
Names of the rows splitting variables in hierarchical order
ex. AEBODSYS, AEDECOD, ASEV
ex.
1. AEBODSYS
2. AEDECOD
3. ASEVAnalysis concept
Alternative table description for summary tables similar to AET01
ex.
- Serious AE
- Related AE
- Total number of AEsStatistics
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
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 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.
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.
.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 AESEV
in
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: ARM
or ACTARM
. - Actually
received variable - format
: of percentages etc…