Introduction to Chevron"

In chevron: Standard TLGs for Clinical Trials Reporting

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Introduction

The chevron R package provides functions to produce standard tables, listings and graphs (TLGs) used to analyze and report clinical trials data. The ensemble of function used to produce a particular output are stored in an S4 object of virtual class chevron_tlg. Each type of output are associated with a specific class: chevron_t for tables, chevron_l for listings and chevron_g for graphs.

Each standard output is associated with one chevron_tlg object. They contain the following objects in separate slots:

• A main function also refereed to as TLG-function.
• A preprocess function.
• A postprocess function

TLG-functions

The TLG-functions in chevron use other packages to produce the final outputs, for example rtables and tern are used to create tables, ggplot2, lattice, and grid are used to create graphs, rlistings to create listings.

TLG-functions in chevron such as dmt01_main, aet02_main, aet02_main have the following properties:

1. they produce a narrow defined output (currently standards in Roche GDS). Note, that the naming convention <gds template id>_main 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, if possible, few arguments to modify the standard. Generally, arguments may change the structure of the table (arm variable, which variables are summarized) and also 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.

preprocessing

The preprocess functions in chevron use base, dplyr and dunlin packages to process input data object and turn them into a suitable input for TLG-functions.

preprocess in chevron such as dmt01_pre, aet02_pre, aet02_pre have the following properties:

1. they return a list of data.frame object amenable to processing by a TLG-functions. message.
2. have very few arguments to modify the standard.
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.

Please note that the ultimate responsible person of the preprocessing functions is the end user. The provided preprocessing function is only a template and users could modify depending on their need/data. This preprocessing function will be printed to allow modification in script generated in citril.

postprocessing

By default, the Postprocessing function returns its input or a null report if the input has no rows. postprocessing function of a chevron_tlg object must have at least tlg as formal arguments.

Example AET02

For example, the GDS template aet02 is implemented in chevron with the chevropn_tlg objects that have the name aet02.

We first load the data as a list of data.frame, where each table represents a domain.

library(chevron)
data(syn_data, package = "chevron")

A the aet02 output is then created as follows:

run(aet02, syn_data)

The function associated with a particular slot can be retrieved with the corresponding method: main, lyt, preprocess postprocess and datasets.

main(aet02)

These are standard functions that can be used on their own.

res <- preprocess(aet02)(syn_data)

# or
foo <- aet02@preprocess
res <- foo(syn_data)

str(res, max.level = 0)

chevron_tlg object customization

In some instances it is useful to customize the chevron_tlg object, for example by changing the pre processing functions in script generated. Please modify the code directly inside the pre_fun, and make sure the function returns a named list of data frames. Please be careful about the argument names. The default argument of pre functions will be override by the argument in spec.

Custom chevron_tlg object creation

In some cases, you may want to create a new chevron_tlg template. To create a chevron_tlg object from scratch, use the provided constructors corresponding to the desired output:

• chevron_t() for tables.
• chevron_l() for listings.
• chevron_g() for graphs.

library(rtables)
library(tern)
my_template <- chevron_t(
  main = "<your main function to build the table>",
  preprocess = "<your pre function to process the data>",
  postprocess = "<your post function to add custom sorting>"
)

run(my_template, syn_data)

Note that to ensure the correct execution of the run function, the name of the first argument of the main function must be adam_db; the input list of data.frame object to pre-process. The name of the first argument of the preprocess function must be adam_db; the input list object to create TLG output and finally, the name of the first argument of the postprocess function must be tlg, the input TableTree object to post-process. Validation criteria enforce these rules upon creation of a chevron_tlg object.

chevron documentation built on June 20, 2025, 5:08 p.m.