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

```{r, include = FALSE}
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*.
1. 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).
1. 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.
1. have very few arguments to modify the standard.
1. 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.

```{r}
library(chevron)
data(syn_data, package = "chevron")
```

A the `aet02` output is then created as follows:

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

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

```{r}
main(aet02)
```

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

```{r}
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.

```{r, eval = FALSE}
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.