---
title: "DescribeAE"
date: "`r Sys.Date()`"
output:
  html_vignette:
    toc: true
    toc_depth: 2
    keep_md: true
vignette: >
  %\VignetteIndexEntry{DescribeAE}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
---

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

```{r setup}
library(RastaRocket)
```

# Introduction

Adverse events (AE) are a crucial aspect of clinical trials, providing insight into the safety profile of treatments. The `DescribeAE` package provides functions to summarize and visualize adverse events by different criteria such as **System Organ Class (SOC)**, **Preferred Term (PT)**, and **Grade**.

This vignette demonstrates how to use two core functions:

- `desc_ei_per_pt()`: Summarizes adverse events by **System Organ Class (SOC)** and **Preferred Term (PT)**.
- `desc_ei_per_grade()`: Summarizes adverse events by **grade**, which represents severity.

These functions generate tables that help interpret the distribution of adverse events across different treatment arms in a randomized controlled trial (RCT).

# Toy dataset

Before using these functions, we need to create a toy datasets. Below is an example of how to structure the data.

## Assigning Patients to Treatment Arms

```{r}
df_pat_grp <- data.frame(
  USUBJID = paste0("ID_", 1:10),
  RDGRPNAME = c(rep("A", 3), rep("B", 3), rep("C", 4))
)
```

## Recording Adverse Events by LLT, PT, SOC and Grade

```{r}
df_pat_llt <- data.frame(
  USUBJID = c("ID_1", "ID_1", "ID_2", "ID_8", "ID_9"),
  EINUM = c(1, 2, 1, 1, 1),
  EILLTN = c("llt1", "llt2", "llt1", "llt3", "llt4"),
  EIPTN = c("Arrhythmia", "Myocardial Infarction", "Myocardial Infarction", "Pneumonia", "Pneumonia"),
  EISOCPN = c("Cardiac Disorders", "Cardiac Disorders", "Cardiac Disorders", "Infections", "Infections"),
  EIGRDM = c(1, 3, 4, 2, 4),
  EIGRAV = c("Grave", "Non grave", "Non grave", "Non grave", "Grave") 
)
```


# Summarizing Adverse Events

## Describing Adverse Events by System Organ Class

To analyze adverse events based on their **System Organ Class (SOC)** and **Preferred Term (PT)**, use the `desc_ei_per_pt()` function:

```{r}
desc_ei_per_pt(df_pat_grp = df_pat_grp,
               df_pat_llt = df_pat_llt)
```

### Interpretation:

This table shows how frequently different types of adverse events occur within each treatment arm. It helps in identifying which organ systems are most affected and whether certain treatment groups have higher rates of specific adverse events.


## Describing Adverse Events by Grade

To assess the severity of adverse events across treatment arms, use `desc_ei_per_grade()`:

```{r}
desc_ei_per_grade(df_pat_grp = df_pat_grp,
                  df_pat_grade = df_pat_llt)
```

### Interpretation:

This table summarizes the distribution of adverse event grades (severity levels) per treatment group. It helps in understanding whether a treatment is associated with more severe adverse events compared to others.


# What if you have only one group ?

In that case the table `df_pat_grp` must still be provided with RDGRPNAME set to "Total" (or any other string)

```{r}
desc_ei_per_pt(df_pat_grp = df_pat_grp |> dplyr::mutate(RDGRPNAME = "A"),
               df_pat_llt = df_pat_llt)
```

```{r}
desc_ei_per_grade(df_pat_grp = df_pat_grp,
                  df_pat_grade = df_pat_llt |> dplyr::mutate(RDGRPNAME = "A"))
```


# Custom appearance

To have a nicer appearance of the table, it is possible to apply custom formatting by using `custom_format`.  
It allows you to align columns and optionally adjust column widths.

```{r}
desc_ei_per_pt(df_pat_grp = df_pat_grp,
               df_pat_llt = df_pat_llt) |> custom_format()
```


```{r}
desc_ei_per_grade(df_pat_grp = df_pat_grp,
                  df_pat_grade = df_pat_llt) |> custom_format()
```


You can customize the format by specifying the column size and the alignment.

```{r}
desc_ei_per_pt(df_pat_grp = df_pat_grp,
               df_pat_llt = df_pat_llt) |> custom_format(align = "center", column_size = list(pt ~ gt::px(280)))
```


```{r}
desc_ei_per_grade(df_pat_grp = df_pat_grp,
                  df_pat_grade = df_pat_llt) |> custom_format(align = "center", column_size = list(grade ~ gt::px(150)))
```



# Plot Adverse Events

This section provides several visualization methods for adverse events (AEs) based on patient data.
Currently, these plots support only two groups. Future work may involve migration to aevisR for enhanced functionality.

First, we define the two patients group:

```{r}
df_pat_grp <- df_pat_grp |> 
  dplyr::mutate(RDGRPNAME = c(rep("A", 5), rep("B", 5)))
```


## Dumbell plot

The dumbbell plot visualizes the difference in AE occurrence between the two groups. It highlights the absolute risk difference for each AE.

```{r fig.height=5, fig.width=8}
plot_dumbell(df_pat_llt = df_pat_llt,
             df_pat_grp = df_pat_grp)
```

## Volcano plot

The volcano plot displays the association between risk differences and statistical significance (-log10 p-values). This helps identify AEs that differ significantly between groups.

```{r fig.height=6, fig.width=6}
plot_volcano(df_pat_llt = df_pat_llt,
             df_pat_grp = df_pat_grp)
```

## Butterfly plot

The butterfly stacked bar plot compares AE frequencies across groups while stacking by severity grade. It provides a detailed view of AE distributions.

```{r fig.height=5, fig.width=6}
plot_butterfly_stacked_barplot(df_pat_llt = df_pat_llt,
                               df_pat_grp = df_pat_grp)
```

<!-- ## Patient Span Chart (Panchart) -->

<!-- The Patient Span Chart provides a timeline view of adverse events, treatments, and randomization for a selected patient. -->
<!-- It is particularly useful for tracking the sequence of AEs in relation to treatment administration and study randomization. -->

<!-- ### Example Dataset -->

<!-- ```{r} -->
<!-- df_pat_grp_rando <- data.frame( -->
<!--   id_pat = c("ID_1", "ID_2"), -->
<!--   grp = c("A", "B"), -->
<!--   rando_date = c("2020-12-01", "2021-01-03") -->
<!-- ) -->

<!-- df_pat_pt_grade_date <- data.frame( -->
<!--   id_pat = c("ID_1", "ID_1", "ID_1", "ID_1", "ID_2"), -->
<!--   pt = c("Arrhythmia", "Myocardial Infarction", "Arrhythmia", -->
<!--           "Pneumonia", "Pneumonia"), -->
<!--   grade = c(4, 2, 1, 3, 4), -->
<!--   start = c("2021-01-01", "2021-02-03", "2021-01-02", "2021-03-05", "2021-02-01"), -->
<!--   end = c("2021-01-14", "2021-03-03", "2021-01-22", "2021-05-05", "2021-02-03") -->
<!-- ) -->

<!-- df_pat_treatment_date <- data.frame( -->
<!--   id_pat = c("ID_1", "ID_1", "ID_1"), -->
<!--   treatment_date = c("2021-01-25", "2021-03-01", "2021-01-20") -->
<!-- ) -->
<!-- ``` -->

<!-- ### Generating the Panchart for a Specific Patient -->

<!-- ```{r fig.height=4, fig.width=6} -->
<!-- plot_patient_panchart( -->
<!--   df_soc_pt = df_soc_pt, -->
<!--   df_pat_grp_rando = df_pat_grp_rando, -->
<!--   df_pat_pt_grade_date = df_pat_pt_grade_date, -->
<!--   df_pat_treatment_date = df_pat_treatment_date, -->
<!--   pat_id = "ID_1" -->
<!-- ) -->
<!-- ``` -->

<!-- Interpreting the Chart -->

<!-- - Horizontal bars represent the duration of each adverse event. -->
<!-- - Vertical dashed lines indicate the patient's randomization and treatment dates. -->
<!-- - Colors differentiate the severity of adverse events (by grade). -->
<!-- - Separate facets display treatments and adverse events categorized by Preferred Term (PT). -->

# Conclusion

The `DescribeAE` package provides a structured approach to summarizing and visualizing adverse events in clinical trials. By using `desc_ei_per_soc()` and `desc_ei_per_grade()`, researchers can:

- Identify which organ systems are most affected.
- Compare the frequency and severity of adverse events across treatment arms.
- Gain insights into the safety profile of treatments.

These summaries support better decision-making in clinical trial analyses, ensuring a comprehensive evaluation of adverse events. For further customization, users can preprocess their data accordingly before applying these functions.