chevron_catalog.rmd

---
title: "Chevron Catalog"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Chevron Catalog}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options:
  chunk_output_type: console
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

library(dplyr)
library(dunlin)
library(chevron)
```

## **GENERAL**

### **General Concepts**

`chevron` is a collection of functions to creates tables, listings, and graphs following Roche standards for clinical trials reporting. After loading the R packages and the trial data, the output is to be created by the main function `run(...)` . Two arguments `object=` and `adam_db=` are always expected in the function. `object=` specifies which Roche Standard Template ID to use. `adam_db=` specifies the input dataset. Other mandatory and optional arguments within the `run` function vary depending on which template ID is called. To access which arguments are required and what functions are used in each template, simply try `?template` (e.g. `?aet01`) to see more detailed descriptions and instructions.

#### **1. Input dataset and dataset names**

The input dataset expected by the argument `adam_db=` in the `run(...)` function is a collection of `ADaM` datasets as a list object. Each `ADaM` dataset is expected to be an object of data frame. If the `ADaM` datasets are read in individually, user will need to combine them into a list object and provide the name of the list to `adam_db=`. Also, each element in the list are expected to have corresponding `ADaM` dataset names. Conventional `ADaM` dataset names, including `adsl`,`adex`, `adae`, `adlb`,`advs`,`adeg`,`adcm`,`admh`,`adrs`, and `adtte`, can be picked up by `chevron` with one exception.

```{r eval=FALSE}
std_data <- list(adsl = adsl, adae = adae)
run(object = aet01_nollt, adam_db = std_data)
```

#### **2. Expected variables in input analysis dataset**

By default, `chevron` does not pull any subject-level information from either `adsl` or `adsub` and merge into the analysis dataset in the underlying preprocessing steps. The analysis dataset fed into `adam_db=` is expected to have all variables required for analysis available.

#### **3. Character vs Factor**

In the output generation, we often need to specify a particular sorting order of a variable at the time of display. In `chevron`, a character variable needs to be factorized with pre-specified levels to display in order. When encountering cases, for instance, `"ARM A"` has an Asian group only while `"ARM B"` has both Asian and White groups, it is not able to produce outputs like the demographic table unless `"RACE"` is factorized to provide access to the same level attribute of the variable `"RACE"` after the arm split. It is noted that the feature comes from `rtables` instead of `chevron`.

```{r}
proc_data <- syn_data
proc_data$adsl <- proc_data$adsl %>%
  mutate(RACE = case_when(
    ARMCD == "ARM A" ~ "ASIAN",
    ARMCD == "ARM B" & !.data$RACE %in% c("WHITE", "ASIAN") ~ "ASIAN",
    TRUE ~ RACE
  ))
```

Having `"RACE"` as a character variable rather than a factor leads to error message showing up as "Error: Error applying analysis function (var - RACE): Number of rows generated by analysis function do not match across all columns," and it is recommended to convert analysis variable `"RACE"` to a factor.

```{r eval=FALSE}
run(dmt01, proc_data)
```

To resolve this issue, simply try factorizing the variable `"RACE"`:

```{r}
proc_data$adsl$RACE <- as.factor(proc_data$adsl$RACE)
run(dmt01, proc_data)
```

#### **4. Testing the codes for plot generation**

The `run` function when calling a Graphics Template ID returns a `gTree` object which will be used in the downstream workflow for output generation. There are two alternative approaches to rendering the plot: (1) having `draw = TRUE` in the `run` function to enable the generated plot to be automatically created and viewed via the `Plots` tab, and (2) calling the function `grid.draw` from the package `grid` which can be utilized to render the plot for viewing and testing purpose. See example below:

```{r eval=FALSE}
proc_data <- log_filter(syn_data, PARAMCD == "OS", "adtte")

# method 1
run(kmg01, proc_data, dataset = "adtte", draw = TRUE)

# method 2
res <- run(kmg01, proc_data, dataset = "adtte")
grid::grid.newpage()
grid::grid.draw(res)
```

### **General Control Arguments**

#### **1. `lbl_overall`: Column of Total**

The generic argument `lbl_overall` controls whether the column of total will be produced or not. `lbl_overall = NULL` suppresses the total, `lbl_overall = "All Patients"` produces the total.

#### **2. Column counts: N=xxx**

Column counts are displayed by default. There is no generic argument controlling whether the count of unique number of subjects (N=xxx) will be displayed in the column header or not. Users are allowed to customize the display of N=xxx by forcing `display_columncounts = FALSE` to wipe column counts away during the postprocessing (with precautions and it is not recommended).

```{r}
tbl <- run(dmt01, syn_data) # table with column counts
tbl@col_info@display_columncounts <- FALSE
tbl # no column counts now
```

## **TABLES**

### **Safety Summary (`AET01`)**

#### **1. Safety Summary**

The **`aet01`** template produces the standard safety summary.

```{r}
run(aet01, syn_data, arm_var = "ARM")
```

#### **2. Safety Summary with Modified Rows**

Analyses under "Total number of patients with at least one" can be removed, added, or modified by editing the parameter `anl_vars`. An analysis here is an abbreviated name of the analysis of interest, and supported by a variable in `ADAE` derived under the condition of interest. The defined analyses currently include `"FATAL"`, `"SER"`, `"SERWD"`, `"SERDSM"`, `"RELSER"`, `"WD"`, `"DSM"`, `"REL"`, `"RELWD"`, `"RELDSM"`, and `"SEV"`. When modification is made, analyses must all be listed in the argument `anl_vars`. The example below shows adding the customized analysis `"RELCTC35"`.

```{r}
proc_data <- syn_data
proc_data$adae <- proc_data$adae %>%
  filter(.data$ANL01FL == "Y") %>%
  mutate(
    FATAL = with_label(.data$AESDTH == "Y", "AE with fatal outcome"),
    SER = with_label(.data$AESER == "Y", "Serious AE"),
    SEV = with_label(.data$ASEV == "SEVERE", "Severe AE (at greatest intensity)"),
    REL = with_label(.data$AREL == "Y", "Related AE"),
    WD = with_label(.data$AEACN == "DRUG WITHDRAWN", "AE leading to withdrawal from treatment"),
    DSM = with_label(
      .data$AEACN %in% c("DRUG INTERRUPTED", "DOSE INCREASED", "DOSE REDUCED"),
      "AE leading to dose modification/interruption"
    ),
    SERWD = with_label(.data$SER & .data$WD, "Serious AE leading to withdrawal from treatment"),
    SERDSM = with_label(.data$SER & .data$DSM, "Serious AE leading to dose modification/interruption"),
    RELSER = with_label(.data$SER & .data$REL, "Related Serious AE"),
    RELWD = with_label(.data$REL & .data$WD, "Related AE leading to withdrawal from treatment"),
    RELDSM = with_label(.data$REL & .data$DSM, "Related AE leading to dose modification/interruption"),
    CTC35 = with_label(.data$ATOXGR %in% c("3", "4", "5"), "Grade 3-5 AE"),
    CTC45 = with_label(.data$ATOXGR %in% c("4", "5"), "Grade 4/5 AE"),
    RELCTC35 = with_label(.data$ATOXGR %in% c("3", "4", "5") & .data$AEREL == "Y", "Related Grade 3-5")
  )

proc_data$adsl <- proc_data$adsl %>%
  mutate(DCSREAS = reformat(.data$DCSREAS, missing_rule))

run(aet01, proc_data, anl_vars = list(safety_var = c("FATAL", "SER", "RELSER", "RELCTC35")), auto_pre = FALSE)
```

### **Safety Summary (Adverse Events of Special Interest) (`AET01_AESI`)**

#### **1. Safety Summary (Adverse Events of Special Interest)**

The **`aet01_aesi`** template produces the standard safety summary for adverse events of special interest.

```{r}
run(aet01_aesi, syn_data)
```

#### **2. Safety Summary (Adverse Events of Special Interest) (optional lines)**

Additional analyses can be added with the argument `aesi_vars`, please type `?aet01_aesi` in console to find out the list of all pre-defined optional analyses in the HELP.

```{r}
run(aet01_aesi, syn_data, aesi_vars = c("RESLWD", "RELSER"))
```

#### **3. Safety Summary (Adverse Events of Special Interest) (for studies with multiple drugs)**

For studies with more than one study drug, users need to define the analyses in `adae` and add to the argument `aesi_vars` following the example above. No pre-defined analysis is available at this moment.

### **Adverse Events (`AET02`)**

#### **1. Adverse Events**

1) The template `aet02` produces the standard adverse event summary by MedDRA system organ class and preferred term.
2) The template does not include the column of total as default. The 'All Patients' column can be added with the argument `lbl_overall = "All Patients"`.
3) Missing values in `"AEBODSYS"`, and `"AEDECOD"` are labeled as `No Coding Available`.

```{r}
run(aet02, syn_data)
```

#### **2. Adverse Events (with High-level Term)**

The syntax below displays adverse events by MedDRA system organ class, high-level term and preferred term.

```{r}
run(aet02, syn_data, row_split_var = c("AEBODSYS", "AEHLT"))
```

#### **3. Adverse Events (Preferred Terms only)**

The syntax below displays adverse events by preferred term only.

```{r}
run(aet02, syn_data, row_split_var = NULL)
```

### **Adverse Events by Greatest Intensity(`AET03`)**

#### **1. Adverse Events by Greatest Intensity**

This **`aet03`** template produces the standard adverse event by greatest intensity summary

```{r}
run(aet03, syn_data)
```

### **Adverse Events by Highest `NCI CTCAE` Grade (`AET04`)**

#### **1. Adverse Events by Highest `NCI CTCAE` Grade**

1) The **`aet04`** template produces the standard adverse event by highest `NCI CTCAE` grade summary.
2) By default, this template includes the grouped grades of 'Grade 1-2' and 'Grade 3-4'.
3) By default this template removes the rows with 0 count.
4) If a treatment group does not have any adverse event, the treatment group is automatically displayed providing that it is defined in `ADSL`.

```{r}
run(aet04, syn_data)
```

#### **2. Adverse Events by Highest `NCI CTCAE` Grade (Fill in of Grades)**

If, for some preferred terms, not all grades occur but all grades should be displayed, this can be achieved by specifying the argument `prune_0 = FALSE`.

```{r}
run(aet04, syn_data, prune_0 = FALSE)
```

#### **3. Adverse Events by Highest `NCI CTCAE` Grade with modified grouping of grade**

Collapsing grade 3-4 with grade 5, can be achieved by modifying the definition of grade groups in the argument `grade_groups`.

```{r}
grade_groups <- list(
  "Grade 1-2" = c("1", "2"),
  "Grade 3-5" = c("3", "4", "5")
)

run(aet04, syn_data, grade_groups = grade_groups, prune_0 = FALSE)
```

### **Adverse Event Rate Adjusted for Patient-Years at Risk - First Occurrence (`AET05`)**

#### **1. Adverse Event Rate Adjusted for Patient-Years at Risk - First Occurrence**

1) The **`aet05`** template produces the standard adverse event rate adjusted for patient-years at risk summary considering first occurrence only.
2) By default, all `adsaftte` parameter codes containing the string `"TTE"` are included in the output. Users are expected to filter the parameter(s) of interest from input safety time-to-event dataset in pre-processing if needed.
3) In the input safety time-to-event dataset, in the censoring variable `CNSR`, `0` indicates the occurrence of an event of interest and `1` denotes censoring.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "AETTE1", "adsaftte")

run(aet05, proc_data)
```

#### **2. Adverse Event Rate Adjusted for Patient-Years at Risk - First Occurrence (setting type of confidence interval)**

1) The type of the confidence interval for rate can be specified by the argument `conf_type`. Options include `normal` (default), `normal_log` and `exact`.
2) The confidence interval can be adjusted by the argument `conf_level`.

```{r}
run(aet05, syn_data, conf_level = 0.90, conf_type = "exact")
```

### **Adverse Event Rate Adjusted for Patient-Years at Risk - All Occurrences (`AET05_ALL`)**

#### **1. Adverse Event Rate Adjusted for Patient-Years at Risk - All Occurrences**

1) The **`aet05_all`** template produces the standard adverse event rate adjusted for patient-years at risk summary considering all occurrences.
2) By default, all `adsaftte` parameter codes containing the string `"TOT"` and the parameter code `"AEREPTTE"` are required. `"TOT"` parameters store the number of occurrences of adverse event of interests. Parameter code `"AEREPTTE"` stores the time to end of adverse event reporting period in years that contribute to the summary of "total patient-years at risk" in the output. Users are expected to filter parameters of interest from input analysis dataset in pre-processing, if needed.
3) In the input safety time-to-event dataset, in the censoring variable `CNSR`, `0` indicates the occurrence of an event of interest and `1` denotes censoring.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "AETOT1" | PARAMCD == "AEREPTTE", "adsaftte")

run(aet05_all, proc_data)
```

#### **2. Adverse Event Rate Adjusted for Patient-Years at Risk - All Occurrences (setting type of confidence interval)**

1) The type of the confidence interval for rate can be specified by the argument `conf_type`. Options include `normal` (default), `normal_log`, `exact`, and `byar`.
2) The confidence interval can be adjusted by the argument `conf_level`.

```{r}
run(aet05_all, syn_data, conf_level = 0.90, conf_type = "exact")
```

### **Most Common (>=5%) Adverse Events (`AET10`)**

#### **1. Most Common (>=5%) Adverse Events**

1) The **`aet10`** template produces the standard most common adverse events occurring with relative frequency >=5% output.

```{r}
run(aet10, syn_data)
```

#### **2. Most Common (>=8%) Adverse Events (setting threshold)**

To modify the threshold for displaying preferred terms, this can be achieved by providing the threshold to the argument `atleast`.

```{r}
run(aet10, syn_data, atleast = 0.08)
```

### **Absolute Value and Change from Baseline by Visit (`CFBT01`)**

#### **1. Absolute Value and Change from Baseline by Visit**

1) By default, the `cfbt01` template displays analysis value (`AVAL`) and absolute change from baseline (`CHG`) for each visit.
2) The template does not include the column of total by default.
3) Each parameter is presented on a separate page.
4) The absolute change from baseline at baseline value is not displayed.

```{r}
proc_data <- log_filter(
  syn_data,
  PARAMCD %in% c("DIABP", "SYSBP"), "advs"
)
run(cfbt01, proc_data, dataset = "advs")
```

#### **2. Absolute Value and Change from Baseline by Visit without Screening**

The `skip` arguments controls which visit values should not be displayed. For instance, to mask the changes from baseline during the "SCREENING" and "BASELINE" visits.

```{r}
run(cfbt01, proc_data, dataset = "advs", skip = list(CHG = c("SCREENING", "BASELINE")))
```

### **3. Absolute Value by Visit**

To display only the absolute value, specify `summaryvars  = "AVAL"`.

```{r}
run(cfbt01, proc_data, dataset = "advs", summaryvars = "AVAL")
```

### **Concomitant Medications by Medication Class and Preferred Name (`CMT01A`)**

#### **1. Concomitant Medications by Medication Class and Preferred Name**

1) The **`cmt01a`** template displays concomitant medications by `ATC Level 2` and Preferred Name by default.
2) The template does not include the column of total by default.
3) The template sort medication class and preferred name by alphabetical order by default.

```{r}
run(cmt01a, syn_data)
```

#### **2. Concomitant Medications by Medication Class and Preferred Name (changing `ATC class level`)**

```{r}
run(cmt01a, syn_data, row_split_var = "ATC1")
```

#### **3. Concomitant Medications by Medication Class and Preferred Name (classes sorted by frequency)**

The argument `sort_by_freq = TRUE` sort medication class by frequency.

```{r}
run(cmt01a, syn_data, sort_by_freq = TRUE)
```

#### **4. Concomitant Medications by Medication Class and Preferred Name (total number of treatments per medication class suppressed)**

The **`cmt01a`** template includes the analysis of 'total number of treatments' by default, modify the argument `summary_labels` to change it.

```{r}
run(cmt01a, syn_data, summary_labels = list(TOTAL = cmt01_label, ATC2 = cmt01_label[1]))
```

### **Concomitant Medications by Preferred Name (`CMT02_PT`)**

#### **1. Concomitant Medications by Preferred Name**

1) The **`cmt02_pt`** template displays concomitant medications by Preferred Name by default.
2) The template does not include the column of total by default.
3) The template sorts preferred name by alphabetical order by default. Set the argument `sort_by_freq = TRUE` to sort preferred names by frequency.

```{r}
run(cmt02_pt, syn_data)
```

### **Cox Regression (`COXT01`)**

#### **1. Cox Regression**

1) The **`coxt01`** template produces the standard Cox regression output.
2) Users are expected to pre-process the input analysis data by selecting a time-to-event parameter to be analyzed. The example below is based on the time-to-event parameter "Duration of Confirmed Response by Investigator".
3) The time variable in the model is specified through the `time_var` argument. By default, `time_var` is set to `"AVAL"`, which comes from `ADTTE.AVAL`.
4) The event variable in the model is specified through the `event_var` argument. By default, `event_var` is set to `"EVENT"`, which is derived based on the censoring indicator `ADTTE.CNSR` in the pre-processing function `coxt01_pre`.
5) If there are more than two treatment groups present in the input analysis data, users are also expected to select only two treatment groups. The example below is based on treatment groups `"Arm A"` and `"Arm B"`.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "OS", "adtte")
proc_data <- log_filter(proc_data, ARMCD != "ARM C", "adsl")
run(coxt01, proc_data, time_var = "AVAL", event_var = "EVENT")
```

#### **2. Cox Regression (with interaction term)**

To add the interaction term to the model, `interaction = TRUE`, which is passed to `tern::control_coxreg()`, needs to be specified.

```{r}
run(coxt01, proc_data, covariates = "AAGE", interaction = TRUE)
```

#### **3. Cox Regression (specifying covariates)**

1) By default, `"SEX"`, `"RACE"` and `"AAGE"` are used as the covariates for the model.
2) Users can specify a different set of covariates through the `covariates` argument. In the example below, `"RACE"` and `"AAGE"` are used as covariates.

```{r}
run(coxt01, proc_data, covariates = c("RACE", "AAGE"))
```

#### **4. Cox Regression (setting strata, ties, and alpha level)**

1) By default, `strata = NULL` (no stratification), `ties = "exact"` (equivalent to `DISCRETE` in SAS), and `conf_level = 0.95` are applied.
2) Users can specify one or more stratification variables via the `strata` argument.
3) Other tie handling methods, i.e., `"efron"` or `"breslow"`, can be specified in the `tie` argument, which is passed to `tern::control_coxreg()`.
4) Users can also customize the alpha level for the confidence intervals through the `conf_level` argument, which is passed to `tern::control_coxreg()`.

```{r}
run(coxt01, proc_data, covariates = c("SEX", "AAGE"), strata = c("RACE"), conf_level = 0.90)
```

### **Multi-variable Cox Regression (`COXT02`)**

#### **1. Multi-variable Cox Regression**

1) The **`coxt02`** template produces the standard multi-variable cox regression output.
2) Users are expected to pre-process the input analysis data by selecting a time-to-event parameter to be analyzed. The example below is based on the time-to-event parameter "Duration of Confirmed Response by Investigator".
3) The time variable in the model is specified through the `time_var` argument. By default, `time_var` is set to `"AVAL"`, which comes from `ADTTE.AVAL`.
4) The event variable in the model is specified through the `event_var` argument. By default, `event_var` is set to `"EVENT"`, which is derived based on the censoring indicator `ADTTE.CNSR` in the pre-processing function `coxt01_pre`.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "OS", "adtte")
run(coxt02, proc_data, time_var = "AVAL", event_var = "EVENT")
```

#### **2. Multi-variable Cox Regression (specifying covariates)**

1) By default, `"SEX"`, `"RACE"` and `"AAGE"` are used as the covariates for the model.
2) Users can specify a different set of covariates through the `covariates` argument. In the example below, `"RACE"` and `"AAGE"` are used as covariates.

```{r}
run(coxt02, proc_data, covariates = c("RACE", "AAGE"))
```

#### **3. Multi-variable Cox Regression (setting strata, ties, and alpha level)**

1) By default, `strata = NULL` (no stratification), `ties = "exact"` (equivalent to `DISCRETE` in SAS), and `conf_level = 0.95` are applied.
2) Users can specify one or more stratification variables via the `strata` argument.
3) Other tie handling methods, i.e., `"efron"` or `"breslow"`, can be specified in the `tie` argument, which is passed to `tern::control_coxreg()`.
4) Users can also customize the alpha level for the confidence intervals through the `conf_level` argument, which is passed to `tern::control_coxreg()`.

```{r}
run(coxt02, proc_data, covariates = c("SEX", "AAGE"), strata = c("RACE"), conf_level = 0.90, ties = "efron")
```

### **Demographics and Baseline Characteristics (`DMT01`)**

#### **1. Demographics and Baseline Characteristics with All Patients**

1) The **`dmt01`** template produces the standard demographics and baseline characteristics summary.
2) This template includes the column of total by default.

```{r}
run(dmt01, syn_data)
```

#### **2. Demographics and Baseline Characteristics without All Patients**

To remove the column of total, set the argument `lbl_overall` to `NULL`.

```{r}
run(dmt01, syn_data, lbl_overall = NULL)
```

#### **3. Demographics and Baseline Characteristics with an additional study specific continuous variable**

1) Study specific continuous variables can be added to the standard demographics and baseline characteristics summary by editing the argument `summaryvars`. To add or remove analyses, you need to pass all variables you would like to include to the argument.
2) CHEVRON performs the analysis based on the type of variable as defined in the input data.

```{r}
run(dmt01, syn_data, summaryvars = c("AGE", "AGEGR1", "SEX", "ETHNIC", "RACE", "BBMISI"), lbl_overall = NULL)
```

#### **4. Demographics and Baseline Characteristics with an additional study specific categorical variable**

1) Study specific categorical variables can be added to the standard demographics and baseline characteristics summary by editing the argument `summaryvars`.
2) To display the values within a categorical variable in pre-specified order, the categorical variable need to be factorized with pre-specified order provided as levels.

```{r}
proc_data <- syn_data
proc_data$adsl <- proc_data$adsl %>%
  mutate(
    SEX = reformat(.data$SEX, rule(Male = "M", Female = "F")),
    BBMIGR1 = factor(case_when(
      BBMISI < 15 ~ "Very severely underweight",
      BBMISI >= 15 & BBMISI < 16 ~ "Severely underweight",
      BBMISI >= 16 & BBMISI < 18.5 ~ "Underweight",
      BBMISI >= 18.5 & BBMISI < 25 ~ "Normal (healthy weight)",
      BBMISI >= 25 & BBMISI < 30 ~ "Overweight",
      BBMISI >= 30 & BBMISI < 35 ~ "Obese Class I (Moderately obese)",
      BBMISI >= 35 & BBMISI < 40 ~ "Obese Class II (Severely obese)",
      BBMISI >= 40 ~ "Obese Class III (Very severely obese)"
    ), levels = c(
      "Very severely underweight",
      "Severely underweight",
      "Underweight",
      "Normal (healthy weight)",
      "Overweight",
      "Obese Class I (Moderately obese)",
      "Obese Class II (Severely obese)",
      "Obese Class III (Very severely obese)"
    ))
  )

run(dmt01, proc_data, summaryvars = c("AGE", "AGEGR1", "SEX", "ETHNIC", "RACE", "BBMIGR1"), auto_pre = FALSE)
```

#### **5. Demographics and Baseline Characteristics with additional vital signs baseline values from `ADVS` or `ADSUB`**

To add baseline vital signs or other baseline characteristics to the demographics and baseline characteristics summary, manual preprocess of input `adsl` dataset is expected and merge the vital signs baseline values from `advs` (where `ADVS.ABLFL == "Y"`) or `adsub` with `adsl` by unique subject identifier.

```{r}
proc_data <- syn_data
diabpbl <- proc_data$advs %>%
  filter(ABLFL == "Y" & PARAMCD == "DIABP") %>%
  mutate(DIABPBL = AVAL) %>%
  select("STUDYID", "USUBJID", "DIABPBL")

proc_data$adsl <- proc_data$adsl %>%
  mutate(SEX = reformat(.data$SEX, rule(Male = "M", Female = "F"))) %>%
  left_join(diabpbl, by = c("STUDYID", "USUBJID"))

run(dmt01, proc_data, summaryvars = c("AGE", "AGEGR1", "SEX", "ETHNIC", "RACE", "DIABPBL"), auto_pre = FALSE)
```

### **Patient Disposition (`DST01`)**

#### **1. Patient Disposition**

1) The **`dst01`** template produces the standard patient disposition summary.
2) The template includes the column of total by default. Use `lbl_overall = NULL` to suppress the default.

```{r}
run(dst01, syn_data, lbl_overall = NULL)
```

#### **2. Patient Disposition (with grouping of reasons)**

1) The syntax below produces the standard patient disposition summary with grouping of the discontinuation reasons.
2) The variable [`ADSL.DCSREASGP`] that groups the discontinuation reasons needs to be derived manually and provided in the input `adsl` dataset.

```{r}
run(dst01, syn_data, detail_vars = list(Discontinued = c("DCSREASGP", "DCSREAS")), lbl_overall = NULL)
```

#### **3. Patient Disposition (adding end of treatment status)**

The syntax below adds the end of treatment status to the standard patient disposition summary by providing the end of treatment status variable to the argument `trt_status_var`.

```{r}
run(dst01, syn_data, trt_status_var = "EOTSTT", lbl_overall = NULL)
```

#### **4. Patient Disposition (adding details of study ongoing status)**

The syntax adds the details of study ongoing/alive status to the standard patient disposition summary by modifying the argument `detail_vars`.

```{r}
run(dst01, syn_data, detail_vars = list(Discontinued = "DCSREAS", Ongoing = "STDONS"))
```

### **Deaths (`DTHT01`)**

#### **1. Deaths**

The **`dtht01`** template produces the standard deaths output.

```{r}
run(dst01, syn_data)
```

#### **2. Deaths (adding "Primary Cause of Death" details for 'Other' category)**

```{r}
run(dtht01, syn_data, other_category = TRUE)
```

NOTE: In order to avoid the warning above and display 'Other' as the last category under "Primary Cause of Death" right above the detailed reasons for "Other", the user is expected to manually provide levels to `ADSL.DTHCAT` based on categories available in the dataset.

#### **3. Deaths (adding summary by days from last study drug administration)**

Setting `time_since_last_dose` to `TRUE`, the syntax produces the count of deaths by days from last study drug administration as well as the count of deaths by primary cause and days from last study drug administration.

```{r}
run(dtht01, syn_data, time_since_last_dose = TRUE)
```

### **ECG Results and Change from Baseline by Visit (`EGT01`)**

#### **1. ECG Results and Change from Baseline by Visit**

The **`egt01`** template produces the standard ECG results and change from baseline by visit summary.

```{r}
run(egt01, syn_data)
```

### **ECG Abnormalities (Regardless of Abnormality at Baseline) (`EGT02_1`)**

#### **1. ECG Abnormalities (Regardless of Abnormality at Baseline)**

The **`egt02_1`** template produces the standard ECG abnormalities summary where the abnormalities are summarized regardless of the abnormality at baseline.

```{r}
run(egt02_1, syn_data)
```

### **ECG Abnormalities (Among Subject Without Abnormality at Baseline) (`EGT02_2`)**

#### **1. ECG Abnormalities (Among Subject Without Abnormality at Baseline)**

The **`egt02_2`** template produces the standard ECG abnormalities summary where the abnormalities are summarized among subject without abnormality at baseline.

```{r}
run(egt02_2, syn_data)
```

### **Shift Table of ECG Interval Data - Baseline versus Minimum/Maximum Post-Baseline (`EGT03`)**

#### **1. Shift Table of ECG Interval Data - Baseline versus Minimum Post-Baseline**

The **`egt03`** template produces the standard shift table of ECG interval data - baseline versus minimum post-baseline summary.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "HR", "adeg")
run(egt03, proc_data)
```

#### **2. Shift Table of ECG Interval Data - Baseline versus Maximum Post-Baseline**

To produce the standard shift table of ECG interval data - baseline versus maximum post-baseline summary....TBA

### **ECG Actual Values and Changes from Baseline by Visit (`EGT05_QTCAT`)**

#### **1. ECG Actual Values and Changes from Baseline by Visit**

The **`egt05_qtcat`** template produces the standard ECG actual values and changes from baseline by visit summary.

```{r}
run(egt05_qtcat, syn_data)
```

#### **2. ECG Actual Values and Changes from Baseline by Visit (removing default analyses)**

The template have two default analyses of `ADEG.AVALCAT1` and `ADEG.CHGCAT1`. To keep only the analyses needed, this can be achieved by modifying the parameter `summaryvars`.

```{r}
run(egt05_qtcat, syn_data, summaryvars = c("AVALCAT1"))
```

### **Study Drug Exposure (`EXT01`)**

#### **1. Study Drug Exposure**

1) The **`ext01`** template displays total number of doses administered and total dose administered by default
2) The template does not include the column of total by default

```{r}
run(ext01, syn_data)
```

### **Laboratory Test Results and Change from Baseline by Visit (`LBT01`)**

#### **1. Laboratory Test Results and Change from Baseline by Visit**

1) The **`lbt01`** template produces the standard laboratory test results and change from baseline by visit.
2) To select the SI/CV/LS results and the panel (chemistry/hematology/urinalysis/coagulation etc.) to display, user defines individual filters and apply to input datasets prior to running CHEVRON.

```{r}
t_lb_chg <- run(lbt01, syn_data)
head(t_lb_chg, 20)
```

#### **2. Laboratory Test Results and Change from Baseline by Visit (customized precision)**

TBA

### **Laboratory Abnormalities (`LBT04`)**

#### **1. Laboratory Abnormalities**

1) The **`lbt04`** template produces the standard laboratory abnormalities summary.
2) The template subsets to SI results by default.
3) The laboratory tests and directions of abnormality in this template is data-driven. Table entries provide the number of patients with a during treatment laboratory value abnormality in the direction specified among patients without this abnormality at baseline.

```{r}
run(lbt04, syn_data)
```

### **Laboratory Abnormalities with Single and Replicated Marked (`LBT05`)**

#### **1. Laboratory Abnormalities with Single and Replicated Marked**

1) The **`lbt05`** template produces the standard laboratory abnormalities summary for marked abnormalities.
2) The laboratory tests and directions of abnormality in this template is currently data-driven. The standard metadata for Safety Lab Standardization will be incorporated in future release.

```{r}
run(lbt05, syn_data)
```

#### **2. Laboratory Abnormalities with Single and Replicated Marked showing all categories**

#### **3. Laboratory Abnormalities with Single and Replicated Marked with study specific `MLAs`**

### **Laboratory Abnormalities by Visit and Baseline Status (`LBT06`)**

#### **1. Laboratory Abnormalities by Visit and Baseline Status**

1) The **`lbt06`** template produces the standard laboratory abnormalities by visit and baseline status summary.

```{r}
run(lbt06, syn_data)
```

### **Laboratory Test Results with Highest `NCI CTCAE` Grade Post-Baseline (`LBT07`)**

#### **1. Laboratory Test Results with Highest `NCI CTCAE` Grade Post-Baseline**

1) The **`lbt07`** template produces the standard laboratory test results with highest `NCI CTCAE` grade post-baseline summary.
2) The laboratory tests and grades in this template is currently data-driven. The standard metadata for possible lab tests and corresponding `NCI CTCAE` grade will be incorporated in future release.

```{r}
run(lbt07, syn_data)
```

### **Laboratory Test Results Shift Table - Highest `NCI-CTCAE` Grade Post-Baseline by Baseline `NCI-CTCAE` Grade (`LBT14`)**

#### **1. Laboratory Test Results Shift Table - Highest `NCI-CTCAE` Grade Post-Baseline by Baseline `NCI-CTCAE` Grade (High)**

To produce the standard laboratory test results shift table - highest `NCI-CTCAE` grade post-baseline by baseline `NCI-CTCAE` grade summary for high abnormalities, use the **`lbt14`** template and set the parameter *`direction`* to `high`.

```{r}
run(lbt14, syn_data, direction = "high")
```

#### **2. Laboratory Test Results Shift Table - Highest `NCI-CTCAE` Grade Post-Baseline by Baseline `NCI-CTCAE` Grade (Low)**

To produce the standard laboratory test results shift table - highest `NCI-CTCAE` grade post-baseline by baseline `NCI-CTCAE` grade summary for high abnormalities, use the **`lbt14`** template and the argument `direction` is `low` by default.

```{r}
run(lbt14, syn_data)
```

#### **3. Laboratory Test Results Shift Table - Highest `NCI-CTCAE` Grade Post-Baseline by Baseline `NCI-CTCAE` Grade (High) Without Patients with Missing Baseline**

To exclude patients with missing baseline grade, set the argument `gr_missing` to `excl`.

```{r}
run(lbt14, syn_data, direction = "high", gr_missing = "excl")
```

#### **4. Laboratory Test Results Shift Table - Highest `NCI-CTCAE` Grade Post-Baseline by Baseline `NCI-CTCAE` Grade (Low) with Missing Baseline Considered as Grade 0**

To count patients with missing baseline grade as grade 0, set the argument `gr_missing` to `gr_0`.

```{r}
run(lbt14, syn_data, gr_missing = "gr_0")
```

#### **4. Laboratory Test Results Shift Table - Highest `NCI-CTCAE` Grade Post-Baseline by Baseline `NCI-CTCAE` Grade (with fill in of grades)**

To display all possible grades even if they do not occur in the data, set the argument `prune_0` to `FALSE`.

```{r}
run(lbt14, syn_data, direction = "high", prune_0 = FALSE)
```


### **Laboratory Test Shifts to `NCI-CTCAE` Grade 3-4 Post-Baseline (`LBT15`)**

Please note that the following examples of summarizing lab grades using single and double grading approaches can be applied to other lab table templates beyond `LBT15`.

#### **1. Laboratory Test Shifts to `NCI-CTCAE` Grade 3-4 Post-Baseline (Single Grading Approach)**

In ADaM v1.1 or below, lab grade variables (`BTOXGR` and `ATOXGR`) in ADLB range from -4 to +4, with -/+ indicating the direction of lab abnormality. This is known as the single grading approach. 

To summarize patients shifting to post-baseline grade 3-4 based on ADLB with the single grading approach, simply run the default `lbt15` template shown below.

```{r}
run(lbt15, syn_data)
```

#### **2. Laboratory Test Shifts to `NCI-CTCAE` Grade 3-4 Post-Baseline (Double Grading Approach)**

In ADaM v1.2 or above, ADLB now has two sets of lab grade variables - the high-directional variables (`ATOXDSCH`/`ATOXGRH`/`BTOXGRH`) and the low-directional variables (`ATOXDSCL`/`BTOXGRL`/`ATOXGRL`), both ranging from 0 to 4. This is known as the double grading or the bi-directional approach, which is the default in `{admiral}`.

To summarize patients shifting to post-baseline grade 3-4 based on ADLB with the double grading approach, redefining `ANRIND` and `BNRIND` is needed in the pre-processing step shown below.

```{r}
proc_data <- syn_data
# Convert single grading variables to double ones for demo purpose only
# as the original syn_data is using single grading approach
hr <- rule("0" = c("-4", "-3", "-2", "-1", "0"))
lr <- rule(
  "0" = c("4", "3", "2", "1", "0"),
  "1" = "-1", "2" = "-2", "3" = "-3", "4" = "-4"
)
proc_data$adlb <- proc_data$adlb %>%
  mutate(
    BTOXGRH = reformat(.data$BTOXGR, hr),
    ATOXGRH = reformat(.data$ATOXGR, hr),
    BTOXGRL = reformat(.data$BTOXGR, lr),
    ATOXGRL = reformat(.data$ATOXGR, lr)
  )

# Redefine ANRIND and BNRIND to adopt double grading approach
preprocess(lbt15) <- function(adam_db, ...) {
  adam_db$adlb <- adam_db$adlb %>%
    filter(.data$ONTRTFL == "Y", .data$PARCAT2 == "SI") %>%
    mutate(
      PARAM = with_label(.data$PARAM, "Laboratory Test"),
      ANRIND = with_label(
        as.factor(
          case_when(
            ATOXGRH == "0" & ATOXGRL %in% c("3", "4") ~ "LOW",
            is.na(ATOXGRH) & ATOXGRL %in% c("3", "4") ~ "LOW",
            ATOXGRH %in% c("3", "4") & ATOXGRL == "0" ~ "HIGH",
            ATOXGRH %in% c("3", "4") & is.na(ATOXGRL) ~ "HIGH",
            is.na(ATOXGRH) & is.na(ATOXGRL) ~ NA_character_,
            TRUE ~ "MODERATE/NORMAL"
          )
        ), "Direction of Abnormality"
      ),
      BNRIND = as.factor(
        case_when(
          BTOXGRH == "0" & BTOXGRL %in% c("3", "4") ~ "LOW",
          is.na(BTOXGRH) & BTOXGRL %in% c("3", "4") ~ "LOW",
          BTOXGRH %in% c("3", "4") & BTOXGRL == "0" ~ "HIGH",
          BTOXGRH %in% c("3", "4") & is.na(BTOXGRL) ~ "HIGH",
          is.na(BTOXGRH) & is.na(BTOXGRL) ~ NA_character_,
          TRUE ~ "MODERATE/NORMAL"
        )
      )
    )
  adam_db
}

run(lbt15, proc_data)
```

### **Medical History (`MHT01`)**

#### **1. Medical History**

1) The **`mht01`** template displays medical conditions by MedDRA system organ class and Preferred Name by default.
2) The default treatment variable is `"ADSL.ARM"`.
3) The user is expected to use filter to subset medical conditions prior to or on entering study.
4) By default, the template produces the overall 'total number of conditions' as well as the 'total number of conditions' per body system after the summary of patients.
5）This template currently does not support sorting MedDRA system organ class and preferred names by order of frequency.

```{r}
run(mht01, syn_data)
```

#### **2. Medical History showing additional column 'All Patients'**

```{r}
run(mht01, syn_data, lbl_overall = "All Patients")
```

### **Major Protocol Deviations (`PDT01`)**

#### **1. Major Protocol Deviations**

1) The **`pdt01`** template produces the standard major protocol deviations output.
2) Users are expected to filter `addv` to only include records where `DVCAT == "MAJOR"` in pre-processing.

```{r}
proc_data <- syn_data
proc_data$addv <- proc_data$addv %>%
  filter(DVCAT == "MAJOR")

run(pdt01, proc_data)
```

### **Reasons for Major Protocol Deviations Related to Epidemic/Pandemic (`PDT02`)**

#### **1. Reasons for Major Protocol Deviations Related to Epidemic/Pandemic**

1) The **`pdt02`** template produces the reasons for major protocol deviations related to epidemic/pandemic summary.
2) By default, `ADDV.DVREAS` provides the reason and `ADDV.DVTERM` provides the description.
3) By default, `addv` has been filtered to include only records that meet the condition `AEPRELFL == "Y" & DVCAT == "MAJOR"`.

```{r}
run(pdt02, syn_data)
```

### **Duration of Exposure for Risk Management Plan (`RMPT01`)**

#### **1. Duration of Exposure for Risk Management Plan**

The **`rmpt01`** template produces the standard duration of exposure output for the Risk Management Plan (`RMP`).

Person time is the sum of exposure across all patients in days.

```{r}
run(rmpt01, syn_data)
```

### **Extent of Exposure by Age Group and Gender for Risk Management Plan (`RMPT03`)**

#### **1. Extent of Exposure by Age Group and Gender for Risk Management Plan**

The **`rmpt03`** template produces the standard extent of exposure by age group and gender output for the Risk Management Plan (`RMP`).

By default, the `AGEGR1` variable is used as the age group. If `AGEGR1` is available in `ADSL` only but not in `ADEX`, it needs to be added to `ADEX` first.

```{r}
proc_data <- syn_data
proc_data <- propagate(proc_data, "adsl", "AGEGR1", "USUBJID")
run(rmpt03, proc_data)
```

Any other study specific age group can be used by editing the parameter `summaryvars`. For all `RMP` tables, if the variable specified per `summaryvars` is unavailable in `ADEX`, it needs to be added to `ADEX` first.

```{r}
proc_data <- syn_data
proc_data$adsl <- proc_data$adsl %>%
  mutate(
    AGEGR2 = with_label(
      factor(case_when(
        AAGE < 18 ~ "<18",
        AAGE >= 18 & AAGE <= 65 ~ "18 - 65",
        AAGE > 65 ~ ">65",
      ), levels = c("<18", "18 - 65", ">65")),
      "Age Group 2"
    )
  )
proc_data <- propagate(proc_data, "adsl", "AGEGR2", "USUBJID")
run(rmpt03, proc_data, summaryvars = "AGEGR2")
```

### **Extent of Exposure by Ethnic Origin for Risk Management Plan (`RMPT04`)**

#### **1. Extent of Exposure by Ethnic Origin for Risk Management Plan**

The **`rmpt04`** template produces the standard extent of exposure by ethnic origin output for the Risk Management Plan (`RMP`).

```{r}
run(rmpt04, syn_data)
```

### **Extent of Exposure by Race for Risk Management Plan (`RMPT05`)**

#### **1. Extent of Exposure by Race for Risk Management Plan**

The **`rmpt05`** template produces the standard extent of exposure by race output for the Risk Management Plan (`RMP`).

```{r}
run(rmpt05, syn_data)
```

### **Best Overall Response (`RSPT01`)**

#### **1. Best Overall Response**

1) The **`rspt01`** template produces the standard best overall response output.
2) The template syntax is built based on `RECIST 1.1`. By default, the subjects with response results of `"CR"` or `"PR"` are considered as responders.
3) Users are expected to pre-process the input analysis data and select the parameter to be analyzed, i.e., best overall response by investigator or best overall response by `BICR`.
4) Unstratified analysis is provided by default.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "BESRSPI", "adrs")

run(rspt01, proc_data, ref_group = NULL, perform_analysis = "unstrat", strata = NULL)
```

#### **2. Best Overall Response (Ordering of treatment groups)** {#1}

1) By default, the first level or value of `arm_var` (default to `"ADSL.ARM"` unless specified) is treated as the reference group without specification.
2) To apply user-defined reference group, please provide the value from the treatment variable to the argument `ref_group`, e.g., `ref_group = "PLACEBO"`.
3) Since `rtables` displays the reference group at the very left column, the order of displayed treatment groups may not be exactly the same as the order factorized, depending on which group is selected as the reference group. See below for examples:

| Factorized `trt` order | `ref_group` | Displayed `trt` order | Reference group used in analysis |
| :---------------------:| :----------:|:---------------------:|:--------------------------------:|
| ARM C, ARM B, ARM A    | NULL        | ARM C, ARM B, ARM A   | ARM C                            |
| NULL                   | ARM B       | ARM B, ARM A, ARM C   | ARM B                            |
| ARM C, ARM B, ARM A    | ARM B       | ARM B, ARM C, ARM A   | ARM B                            |

#### **3. Best Overall Response (selecting sections to display)**

1) The section of `Odds Ratio` can be suppressed with the argument `odds_ratio = FALSE`.
2) The section of `Difference in response rate` can be suppressed with the argument `perform_analysis = NULL`.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "BESRSPI", "adrs")

run(rspt01, proc_data, odds_ratio = FALSE, perform_analysis = NULL)
```

#### **4. Best Overall Response (with stratified analysis)**

1) A stratified analysis can be added by specifying the argument `perform_analysis = "strat"` and providing the stratification variable to the argument `strata` . The argument `strata` is expected if `perform_analysis` is set to include stratified analysis.
2) The stratification variables are expected to be available in `adrs`.
3) If both unstratified and stratified analysis are required, use `perform_analysis = c("unstrat", "strat")`

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "BESRSPI", "adrs")

run(rspt01, proc_data, perform_analysis = "strat", strata = c("STRATA1", "STRATA2"))
```

#### **5. Best Overall Response (modifying analysis details like type of confidence interval, alpha level, test for p-value)**

1) The level of the confidence intervals is defined by the argument `conf_level`.
2) The methods to construct confidence interval and p-value are controlled by the argument `methods`. It is a named list with five optional sub-arguments. For example, `methods = list(prop_conf_method = "wald", diff_conf_method = "wald", strat_diff_conf_method = "ha", diff_pval_method = "fisher", strat_diff_pval_method = "schouten")`

See table below for what each argument controls and the available method options:

| Arguments                | Methods Controlled                          | Methods Options                      |
| :-----------------------:| :------------------------------------------:|:------------------------------------:|
| `prop_conf_method`       | proportion confidence interval              | `"waldcc"` (default), `"wald"`, etc. |
| `diff_conf_method`       | unstratified difference confidence interval | `"waldcc"` (default), `"wald"`, etc. |
| `diff_pval_method`       | unstratified p-value for odds ratio         | `"chisq"` (default), `"fisher"`      |
| `strat_diff_conf_method` | stratified difference confidence interval   | `"cmh"` (default), `"ha"`            |
| `strat_diff_pval_method` | stratified p-value for odds ratio           | `"cmh"` (default), `"schouten"`      |

See in the table below the method options for estimates of proportions and the associated statistical methods:

| Method Options      | Statistical Methods                   |
| :------------------:| :------------------------------------:|
| `"clopper-pearson"` | Clopper-Pearson                       |
| `"wald"`            | Wald, without correction              |
| `"waldcc"`          | Wald, with correction                 |
| `"wilson"`          | Wilson, without correction            |
| `"strat_wilson"`    | Stratified Wilson, without correction |
| `"wilsonc"`         | Wilson, with correction               |
| `"strat_wilsonc"`   | Stratified Wilson, with correction    |
| `"agresti-coull"`   | Agresti-Coull                         |
| `"jeffreys"`        | Jeffreys                              |

See in the table below the method options for estimates of proportion difference and the associated statistical methods:

| Method Options       | Statistical Methods                     |
| :-------------------:| :--------------------------------------:|
| `"cmh"`              | `CMH`, without correction               |
| `"wald" `            | Wald, with correction                   |
| `"waldcc"`           | Wald, without correction                |
| `"ha"`               | Anderson-Hauck                          |
| `"newcombe"`         | Newcombe, without correction            |
| `"newcombecc"`       | Newcombe, with correction               |
| `"strat_wilsonc"`    | Stratified Wilson, with correction      |
| `"strat_newcombe"`   | Stratified Newcombe, without correction |
| `"strat_newcombecc"` | Stratified Newcombe, with correction    |

See in the table below the method options for testing proportion difference and the associated statistical methods:

| Method Options | Statistical Methods                       |
| :-------------:| :----------------------------------------:|
| `"chisq"`      | Chi-Squared test                          |
| `"fisher"`     | the Fisher's exact test                   |
| `"cmh"`        | stratified Cochran-Mantel-Haenszel test   |
| `"shouten"`    | Chi-Squared test with Schouten correction |

An example:

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "BESRSPI", "adrs")

run(rspt01, proc_data,
  conf_level = 0.90,
  methods = list(
    prop_conf_method = "wald",
    diff_conf_method = "wald",
    diff_pval_method = "fisher"
  )
)
```

#### **6. Best Overall Response (modifying the definition of overall response)**

The following example shows how to customize the definition of responder, e.g, consider only complete response as response.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "BESRSPI", "adrs")

preprocess(rspt01) <- function(adam_db, ...) {
  adam_db$adrs <- adam_db$adrs %>%
    mutate(RSP_LAB = tern::d_onco_rsp_label(.data$AVALC)) %>%
    mutate(IS_RSP = .data$AVALC %in% c("CR"))
  adam_db
}

run(rspt01, proc_data)
```

### **Time-to-event Summary (`TTET01`)**

#### **1. Time-to-event Summary**

1) The **`ttet01`** template produces the standard time-to-event summary.
2) Users are expected to subset the parameter of interest (e.g. `PARAMCD == "PFS"`) in pre-processing.
3) Please see the section of [Best Overall Response (Ordering of treatment groups)](#1) to find out more about the ordering of treatment groups and reference group.
4) Unstratified analysis is provided by default.
5) Survival estimations and difference in survival are both provided by default.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "PFS", "adtte")

run(ttet01, proc_data)
```

#### **2. Time-to-event Summary (selecting sections to display)**

To suspend the section of earliest contributing events, use `summarize_event = FALSE`.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "PFS", "adtte")

run(ttet01, proc_data, summarize_event = FALSE)
```

To select either survival estimations or difference in survival or both, please specify in the argument `method`.
- `surv` calls out the analysis of patients remaining at risk, event free rate and corresponding 95% confidence interval of the rates.
- `surv_diff` calls out the analysis of difference in event free rate, the 95% confidence interval of the difference and its corresponding p-value.
- `both` calls out both.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "PFS", "adtte")

run(ttet01, proc_data, method = "surv")
```

#### **3. Time-to-event Summary (modifying analysis details like confidence interval type, ties, and alpha level)**

1) The level of the confidence intervals is defined by the argument `conf_level`.
2) The type of confidence interval is defined in the argument `conf_type`. Options are `"plain"` (default), `"log"` and `"log-log"`.
3) Handling of ties is specified in the argument `ties`. Options are `"efron"` (default),`"breslow"` or `"exact"`.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "PFS", "adtte")

run(ttet01, proc_data, conf_level = 0.90, conf_type = "log-log", ties = "efron")
```

#### **4. Time-to-event Summary (with stratified analysis)**

1) A stratified analysis can be added by specifying the argument `perform_analysis = "strat"` and providing the stratification variable to the argument `strata` . The argument `strata` is expected if `perform_analysis` is set to include stratified analysis.
2) The stratification variables are expected to be available in `adrs`.
3) If unstratified and stratified analysis are both required, users can use `perform_analysis = c("unstrat", "strat")`.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "PFS", "adtte")

run(ttet01, proc_data, perform_analysis = "strat", strata = "STRATA1")
```

#### **5. Time-to-event Summary (modifying time point for the "survival at xx months" analysis)**

The time point for the "survival at xx months" analysis can be modified by specifying the argument `time_point`. By default, the function takes `AVAL` from `adtte` in days and converts it to months. The survival estimates are then summarized in month, and the numeric values should be provided in months to `time_point`.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "PFS", "adtte")

run(ttet01, proc_data, perform_analysis = "unstrat", time_point = c(3, 6))
```

The following example shows how to specify the time point in **user-defined unit**.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "PFS", "adtte")

preprocess(ttet01) <- function(adam_db, dataset = "adtte",
                               ...) {
  adam_db[[dataset]] <- adam_db[[dataset]] %>%
    mutate(
      AVALU = "DAYS",
      IS_EVENT = .data$CNSR == 0,
      IS_NOT_EVENT = .data$CNSR == 1,
      EVNT1 = factor(
        case_when(
          IS_EVENT == TRUE ~ render_safe("{Patient_label} with event (%)"),
          IS_EVENT == FALSE ~ render_safe("{Patient_label} without event (%)")
        ),
        levels = render_safe(c("{Patient_label} with event (%)", "{Patient_label} without event (%)"))
      ),
      EVNTDESC = factor(.data$EVNTDESC)
    )

  adam_db
}

run(ttet01, proc_data, perform_analysis = "unstrat", time_point = c(91, 183))
```

#### **6. Time-to-event Summary (modifying the p-value method for testing hazard ratio)**

The default p-value method for testing hazard ratio is "log-rank". Alternative methods can be requested by specifying the argument `pval_method` and options include, `log-rank` (default), `wald` or `likelihood`. The syntax currently does not allow requesting more than one p-value.

Note that `ttet01` has been modified in the previous example (i.e., `preprocess(ttet01)` has been overridden); to access the default template, try `chevron::ttet01`.

```{r}
proc_data <- log_filter(syn_data, PARAMCD == "PFS", "adtte")

run(ttet01, proc_data, pval_method = "wald")
```

### **Vital Signs (`VST01`)**

#### **1. Vital Sign Results and Change from Baseline by Visit**

```{r}
t_vs_chg <- run(vst01, syn_data)
head(t_vs_chg, 20)
```

### **Vital Signs Abnormalities (Regardless of Abnormality at Baseline) (`VST02_1`)**

#### **1. Vital Sign Abnormalities (Regardless of Abnormality at Baseline)**

```{r}
run(vst02_1, syn_data)
```

### **Vital Signs Abnormalities (Among Subject Without Abnormality at Baseline) (`VST02_2`)**

#### **1. Vital Sign Abnormalities (Among Subject Without Abnormality at Baseline)**

```{r}
run(vst02_2, syn_data)
```

## **LISTINGS**

### **Glossary of Adverse Event Preferred Terms and Investigator-Specified Terms (`AEL01_NOLLT`)**

#### **1. Glossary of Adverse Event Preferred Terms and Investigator-Specified Terms**

1) The **`ael01_nollt`** template produces the standard glossary of adverse event preferred terms and investigator-specified terms.
2) The example below uses `head` function to print only the first 10 lines of the output.

```{r}
l_ae_nollt <- run(ael01_nollt, syn_data)
head(l_ae_nollt, 10)
```

## **Graphics**

### **Forest Plot for Odds Ratio (`FSTG01`)**

#### **1. Forest Plot for Odds Ratio (with subgroup analysis)**

1) The **`fstg01`** template produces the standard forest plot for odds ratio.
2) Users are expected to subset the parameter of interest (e.g. `PARAMCD == "BESRSPI"`) in pre-processing.
3) Users are expected to subset the arm variable to keep only the two arms to compare (e.g. `ARM %in% c("A: Drug X", "B: Placebo")`).
4) By default, the plots displays a subgroup analysis for `"SEX"`, `"AGEGR1"` and `"RACE"`.
5) Unstratified analysis is provided by default.
6) The plots displays by default the Total number of subjects, the odd ratio and the 95% confidence interval, and, for each arm, the number of subject, the number of responders and the proportion of responders.

```{r, fig.width = 10, fig.height = 6}
proc_data <- log_filter(
  syn_data,
  PARAMCD == "BESRSPI" & ARM %in% c("A: Drug X", "B: Placebo"), "adrs"
)
run(fstg01, proc_data)
```

#### **2. Forest Plot for Odds Ratio (with a user-defined confidence level)**

The confidence level of the confidence interval can be adjusted by the `conf_level` argument.

```{r, fig.width = 10, fig.height = 6}
run(fstg01, proc_data, conf_level = 0.90)
```

#### **3. Forest Plot for Odds Ratio (with p-values and/or different statistics)**

The interaction p-values and a different set of statistics can be displayed using the `stat_var` argument. Note that the users are expected to select a method for p-value computation. see `[tern::prop_diff_test]`.

```{r, fig.width = 10, fig.height = 6}
run(fstg01, proc_data, method = "fisher", stat_var = c("n_tot", "n", "ci", "or", "pval"))
```

#### **4. Forest Plot for Odds Ratio (with user-defined subgroup analysis)**

The `subgroups` arguments controls which variables are used for subgroup analysis. If `NULL`the subgroup analysis is removed.

```{r, fig.width = 10, fig.height = 6}
run(fstg01, proc_data, subgroups = NULL)
```

#### **5. Forest Plot for Odds Ratio (with stratified analysis)**

The `strata_var` argument is used to pass the columns used for stratified analysis.

```{r, fig.width = 10, fig.height = 6}
run(fstg01, proc_data, strata_var = "STRATA1")
```

#### **6. Forest Plot for Odds Ratio (without proportional sizing of the odds ratio symbol)**

The `col_symbol_size` argument controls the size of the odds ratio symbols which are by default proportional in size to the sample size of the subgroup. If `NULL` the same symbol size is used for all subgroups.

```{r, fig.width = 10, fig.height = 6}
run(fstg01, proc_data, col_symbol_size = NULL)
```

### **Forest Plot for Hazard Ratio (`FSTG02`)**

#### **1. Forest Plot for Hazard Ratio (with subgroup analysis)**

1) The **`fstg02`** template produces the standard forest plot for hazard ratio.
2) Users are expected to subset the parameter of interest (e.g. `PARAMCD == "OS"`) in pre-processing.
3) Users are expected to subset the arm variable to keep only the two arms to compare (e.g. `ARM %in% c("A: Drug X", "B: Placebo")`).
4) By default, the plots displays a subgroup analysis for `"SEX"`, `"AGEGR1"` and `"RACE"`.
5) Unstratified analysis is provided by default.
6) The plots displays by default the Total number of events, the hazard ratio and the 95% confidence interval, and, for each arm, the number of events and the median time to event in month.

```{r, fig.width = 10, fig.height = 6}
proc_data <- log_filter(
  syn_data,
  PARAMCD == "OS" & ARM %in% c("A: Drug X", "B: Placebo"), "adtte"
)
run(fstg02, proc_data)
```

#### **2. Forest Plot for Hazard Ratio (with p-values and/or different statistics)**

The interaction p-values and a different set of statistics can be displayed using the `control` argument. More details about the control options are available in `[tern::extract_survival_subgroups]` 

```{r, fig.width = 10, fig.height = 6}
run(
  fstg02,
  proc_data,
  stat_var = c("n_tot", "n", "ci", "hr", "pval"),
  control = list(conf_level = 0.9, pval_method = "likelihood")
)
```

#### **3. Forest Plot for Hazard Ratio (with user-defined subgroup analysis)**

The `subgroups` arguments controls which variables are used for subgroup analysis. If `NULL`the subgroup analysis is removed.

```{r, fig.width = 10, fig.height = 6}
run(fstg02, proc_data, subgroups = NULL)
```

#### **4. Forest Plot for Hazard Ratio (with stratified analysis)**

The `strata_var` argument is used to pass the columns used for stratified analysis.

```{r, fig.width = 10, fig.height = 6}
run(fstg02, proc_data, strata_var = "STRATA1")
```

#### **5. Forest Plot for Hazard Ratio (without proportional sizing of the hazard ratio symbol)**

The `col_symbol_size` argument controls the size of the hazard ratio symbols which are by default proportional in size to the number of events in the subgroup. If `NULL` the same symbol size is used for all subgroups.

```{r, fig.width = 10, fig.height = 6}
run(fstg02, proc_data, col_symbol_size = NULL)
```

### **Kaplan-Meier Plot (`KMG01`)**

#### **1. Kaplan-Meier Plot (without comparative statistics)**

1) The **`kmg01`** template produces the standard Kaplan-Meier Plot.
2) Users are expected to select a particular parameter for analysis.
3) Users are expected to select the treatment groups to compare, otherwise, all treatment groups available in the input datasets will be plotted.
4) The comparative statistics are not included by default.
5) The estimation of median survival time per treatment group by default.
6) More arguments in the `g_km` and `control_coxph` functions can be passed through, please use the Help to find out more information.

```{r, fig.width = 10, fig.height = 6}
proc_data <- log_filter(syn_data, PARAMCD == "OS", "adtte")
run(kmg01, proc_data, dataset = "adtte")
```

#### **2. Kaplan-Meier Plot (with comparative statistics)**

To enable the comparative statistics (hazard ratio and p-value), the argument `annot_coxph` needs to be set to TRUE. The compare group is determined by the levels in the factorized variable of treatment group and the first level is used as reference group in the statistics.

```{r, fig.width = 10, fig.height = 6}
proc_data <- log_filter(syn_data, PARAMCD == "OS", "adtte")
run(
  kmg01,
  proc_data,
  dataset = "adtte",
  annot_coxph = TRUE,
  control_annot_coxph = tern::control_coxph_annot(x = 0.33, y = 0.42)
)
```

#### **3. Kaplan-Meier Plot (without censoring marks)**

To suppress the censoring marks, set the argument `cencor_show` to FALSE.

```{r, fig.width = 10, fig.height = 6}
proc_data <- log_filter(syn_data, PARAMCD == "OS", "adtte")
run(kmg01, proc_data, dataset = "adtte", censor_show = FALSE)
```

#### **4. Kaplan-Meier Plot (without estimation of median survival time)**

```{r, fig.width = 10, fig.height = 6}
proc_data <- log_filter(syn_data, PARAMCD == "OS", "adtte")
run(kmg01, proc_data, dataset = "adtte", annot_surv_med = FALSE)
```

#### **5. Kaplan-Meier Plot (with statistical annotation of either median or min of survival time)**

To add the statistics annotation, use the function `annot_stats`. Options are `min` or `median`.

```{r, fig.width = 10, fig.height = 6}
proc_data <- log_filter(syn_data, PARAMCD == "OS", "adtte")
run(kmg01, proc_data, dataset = "adtte", annot_stats = "median")
run(kmg01, proc_data, dataset = "adtte", annot_stats = c("min", "median"))
```

#### **6. Kaplan-Meier Plot (without the table of patients at risk)**

```{r, fig.width = 10, fig.height = 6}
proc_data <- log_filter(syn_data, PARAMCD == "OS", "adtte")
run(kmg01, proc_data, dataset = "adtte", annot_at_risk = FALSE)
```

### **Mean Plot (`MNG01`)**

#### **1. Plot of Mean and Confidence Interval (with Table Section)**

1) The **`mng01`** template produces the standard mean plot.
2) Note that the template `mng01` is quite general. The users are expected to specify the analysis dataset and the visit variable in the `run` function, and select the parameters prior to the `run` function.
3) The table of summary statistics is included by default.
4) The variable Analysis Value `AVAL` is used for plotting by default.
5) If the input dataset contains results of the same analyses in multiple units,(e.g. SI/CV units in `ADLB`), please make sure that the parameters in appropriate units are selected in advance.

```{r, fig.height = 8}
proc_data <- log_filter(syn_data, PARAMCD == "DIABP", "advs")
run(mng01, proc_data, dataset = "advs", x_var = c("AVISIT", "AVISITN"))
```

#### **2. Plot of Mean and Confidence Interval of Change from Baseline of Vital Signs**

```{r, fig.height = 8}
proc_data <- log_filter(syn_data, PARAMCD == "DIABP", "advs")
run(mng01, proc_data, dataset = "advs", x_var = c("AVISIT", "AVISITN"), y_var = "CHG")
```

#### **3. Plot of Mean (+/-SD) (Changing the Statistics)**

To change the statistics, use the argument `interval_fun`. Options are `mean_ci`, `mean_sei`, `mean_sdi`, `median_ci`, `quantiles`,`range`.

```{r, fig.height = 8}
proc_data <- log_filter(syn_data, PARAMCD == "DIABP", "advs")
run(mng01, proc_data, dataset = "advs", x_var = c("AVISIT", "AVISITN"), interval_fun = "mean_sdi")
```

#### **4. Plot of Mean and Confidence Interval (Modify Alpha Level)**

To change the alpha level of the confidence interval, use the argument `control = control_analyze_vars(conf_level = <0.xx>)`. Note that this is only in effect when `interval_fun` is set to `mean_ci`.

```{r, fig.height = 8}
proc_data <- log_filter(syn_data, PARAMCD == "DIABP", "advs")
run(
  mng01, proc_data,
  dataset = "advs", x_var = c("AVISIT", "AVISITN"),
  interval_fun = "mean_ci", control = tern::control_analyze_vars(conf_level = 0.80)
)
```

#### **5. Plot of Mean and Confidence Interval （With Number of Patients Only)**

```{r, fig.height = 8}
proc_data <- log_filter(syn_data, PARAMCD == "DIABP", "advs")
run(mng01, proc_data, dataset = "advs", x_var = c("AVISIT", "AVISITN"), table = "n")
```

#### **6. Plot of Mean and Confidence Interval (without Table Section)**

```{r, fig.height = 8}
proc_data <- log_filter(syn_data, PARAMCD == "DIABP", "advs")
run(mng01, proc_data, dataset = "advs", x_var = c("AVISIT", "AVISITN"), table = NULL)
```

A new argument has been added to control the theme (e.g. setting the angle of the axis); see an example below:

```{r, fig.height = 8}
ggtheme <- ggplot2::theme(
  panel.grid = ggplot2::element_line(colour = "black", linetype = 3),
  panel.background = ggplot2::element_rect(fill = "white"),
  legend.position = "top",
  axis.text.x = ggplot2::element_text(angle = 22, hjust = 1, vjust = 1)
)
run(mng01, syn_data, dataset = "adlb", ggtheme = ggtheme)
```