---
title: "Treatment Compliance Table"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Treatment Compliance Table}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  comment = "#>",
  collapse = TRUE,
  out.width = "100%",
  dpi = 150
)
```

```{r setup, message=FALSE}
library(metalite)
library(metalite.sl)
library(dplyr)
```



# Create Treatment Compliance Table

The objective of this tutorial is to generate a production-ready Treatment Compliance specification analyses.

This report produces a table that contains a summary of treatment compliance information. The report consists of a treatment compliance category section and a treatment compliance statistics section. 
To accomplish this using metalite.sl, three essential functions are required:

- `prepare_trt_compliance ()`:this function is a wrapper function of `prepare_sl_summary ()` which prepares data for treatment compliance analysis.

- `format_trt_compliance()`: prepare analysis outdata with proper format.

- `rtf_trt_compliance()`: transfer output dataset to RTF table.

An example output:

```{r, out.width = "100%", out.height = "400px", echo = FALSE, fig.align = "center"}
knitr::include_graphics("pdf/treatment0compliance.pdf")
```

## Example data

Within metalite.sl, we utilized the ADSL datasets from the metalite
package to create an illustrative dataset.
The metadata structure remains consistent across all analysis examples
within metalite.sl.
To calculate treatment compliance percent and treatment compliance range, we utilized adex dataset.
Additional information can be accessed on the
[metalite package website](https://merck.github.io/metalite/articles/metalite.html).

## Build a metadata

```{r}
adsl <- r2rtf::r2rtf_adsl

adex <- metalite.ae::metalite_ae_adex

adex1 <- adex |>
  filter(EXNUMDOS > 0 & !(is.na(AENDY))) |>
  group_by(USUBJID) |>
  slice(n()) |>
  select(USUBJID, AENDY) |>
  rename(ADURN = AENDY)

adsl <- merge(adsl, adex1, by = "USUBJID")

adsl <- adsl |>
  mutate(
    TRTDUR = as.numeric(TRTDUR),
    ADURN = as.numeric(ADURN),
    CMPLPCT = round((ADURN / TRTDUR) * 100, 2)
  )

adsl <- adsl |>
  mutate(
    CMPLRNG = case_when(
      CMPLPCT >= 0 & CMPLPCT <= 20 ~ "0% to <=20%",
      CMPLPCT > 20 & CMPLPCT <= 40 ~ ">20% to <=40%",
      CMPLPCT > 40 & CMPLPCT <= 60 ~ ">40% to <=60%",
      CMPLPCT > 60 & CMPLPCT <= 80 ~ ">60% to <=80%",
      CMPLPCT > 80 ~ ">80%"
    ),
    CMPLRNGN = case_when(
      CMPLPCT >= 0 & CMPLPCT <= 20 ~ 1,
      CMPLPCT > 20 & CMPLPCT <= 40 ~ 2,
      CMPLPCT > 40 & CMPLPCT <= 60 ~ 3,
      CMPLPCT > 60 & CMPLPCT <= 80 ~ 4,
      CMPLPCT > 80 ~ 5
    )
  )

head(adsl)
```

```{r}
adsl$TRTA <- adsl$TRT01A
adsl$TRTA <- factor(adsl$TRTA,
  levels = c("Placebo", "Xanomeline Low Dose", "Xanomeline High Dose"),
  labels = c("Placebo", "Low Dose", "High Dose")
)
```

```{r}
plan <- plan(
  analysis = "trt_compliance", population = "apat",
  observation = "apat", parameter = "CMPLRNG;CMPLPCT"
)
```

```{r}
meta <- meta_adam(
  population = adsl,
  observation = adsl
) |>
  define_plan(plan = plan) |>
  define_population(
    name = "apat",
    group = "TRTA",
    subset = quote(SAFFL == "Y"),
    var = c("USUBJID", "TRTA", "SAFFL", "CMPLPCT", "CMPLRNG")
  ) |>
  metalite::define_parameter(
    name = "CMPLPCT",
    var = "CMPLPCT",
    label = "Treatment Compliance Percent",
  ) |>
  metalite::define_parameter(
    name = "CMPLRNG",
    var = "CMPLRNG",
    label = "Treatment Compliance Range",
  ) |>
  define_analysis(
    name = "trt_compliance",
    title = "Summary of Treatment Compliance",
    label = "treatment compliance table"
  ) |>
  meta_build()
```

<details>
<summary>Click to show the output</summary>
```{r}
meta
```
</details>

## Analysis preparation

The function `prepare_trt_compliance()` is written to prepare data for treatment compliance analysis.The function takes four arguments:

meta is metadata object created by metalite and it contains data from ADSL.
Analysis, Population, and Parameter arguments are used to subset and process the meta data. They have default values, which rely on the meta data object.

The function assign default value Analysis to `trt_compliance`, Population to the population value associated with the `trt_compliance` analysis in meta plan, and parameter to the parameter(s) associated with the `trt_compliance` analysis in meta$plan.

However, the user can also manually specify the analysis, population, and parameter values when calling the function, if they want to override the default values.

In the body of the function, it calls another function prepare_sl_summary with the same meta, analysis, population, and parameter arguments.
`prepare_sl_summary` takes the meta data, subsets it based on the analysis, population, and parameter values, and then calculates and returns a summary of the relevant data.

The result of prepare_sl_summary is then returned as the result of prepare_trt_compliance.

The resulting output of the function `prepare_trt_compliance()` comprises
a collection of raw datasets for analysis and reporting.

```{r}
outdata <- prepare_trt_compliance(meta)
```

<details>
<summary>Click to show the output</summary>
```{r}
outdata
```
- `parameter`: parameter name
```{r}
outdata$parameter
```
- `n`: number of participants in population
```{r}
outdata$n
```

The resulting dataset contains frequently used statistics,
with variables indexed according to the order specified in `outdata$group`.

```{r}
outdata$group
```
- `char_n`: number of participants completed vs not completed in each parameter
```{r}
outdata$char_n
```
- `char_var` : name of parameter

```{r}
outdata$char_var
```
- `char_prop` : proportion of subject with treatment compliance


```{r}
outdata$char_prop
```
</details>

## Format output

Once the raw analysis results are obtained,
the `format_trt_compliance()` function can be employed to prepare the outdata,ensuring its compatibility with production-ready RTF tables.

```{r}
outdata <- outdata |> format_trt_compliance()
```

<details>
<summary>Click to show the output</summary>
```{r}
outdata$tbl
```
</details>

## Additional statistics

By using the `display` argument,
we can choose specific statistics to include.

```{r}
tbl <- outdata |> format_trt_compliance(display_stat = c("mean", "sd", "median", "range"), display_col = c("n", "prop", "total"))
```

<details>
<summary>Click to show the output</summary>
```{r}
tbl$tbl
```
</details>

## RTF tables

The last step is to prepare the RTF table using `rtf_trt_compliance`.

```{r}
outdata |>
  format_trt_compliance() |>
  rtf_trt_compliance(
    "Source: [CDISCpilot: adam-adsl]",
    path_outtable = "outtable/treatment0compliance.rtf"
  )
```

```{r, out.width = "100%", out.height = "400px", echo = FALSE, fig.align = "center"}
knitr::include_graphics("pdf/treatment0compliance.pdf")
```