The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

DescribeAE

2025-11-17

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:

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

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

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:

desc_ei_per_pt(df_pat_grp = df_pat_grp,
               df_pat_llt = df_pat_llt)
Evénements indésirables
Total
A
B
C
AE
N (%)		 Patient
N (%)		 AE
N (%)		 Patient
N (%)		 AE
N (%)		 Patient
N (%)		 AE
N (%)		 Patient
N (%)
Total
Total 5 (100.0) 4 (40.0) 3 (100.0) 2 (66.7) 0 ( 0.0) 0 ( 0.0) 2 (100.0) 2 (50.0)
Cardiac Disorders
Total 3 ( 60.0) 2 (20.0) 3 (100.0) 2 (66.7)



Myocardial Infarction 2 ( 40.0) 2 (20.0) 2 ( 66.7) 2 (66.7)



Arrhythmia 1 ( 20.0) 1 (10.0) 1 ( 33.3) 1 (33.3)



Infections
Total 2 ( 40.0) 2 (20.0)



2 (100.0) 2 (50.0)
Pneumonia 2 ( 40.0) 2 (20.0)



2 (100.0) 2 (50.0)

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():

desc_ei_per_grade(df_pat_grp = df_pat_grp,
                  df_pat_grade = df_pat_llt)
Grade
Total
A
B
C
AE
N (%)		 Patient
N (%)		 AE
N (%)		 Patient
N (%)		 AE
N (%)		 Patient
N (%)		 AE
N (%)		 Patient
N (%)
Any grade 5 (100.0) 4 (40.0) 3 (100.0) 2 (66.7) 0 ( 0.0) 0 ( 0.0) 2 (100.0) 2 (50.0)
1 1 ( 20.0) 1 (10.0) 1 ( 33.3) 1 (33.3)



2 1 ( 20.0) 1 (10.0)



1 ( 50.0) 1 (25.0)
3 1 ( 20.0) 1 (10.0) 1 ( 33.3) 1 (33.3)



4 2 ( 40.0) 2 (20.0) 1 ( 33.3) 1 (33.3)

1 ( 50.0) 1 (25.0)
SAE 2 ( 40.0) 2 (20.0) 1 ( 33.3) 1 (33.3)

1 ( 50.0) 1 (25.0)

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)

desc_ei_per_pt(df_pat_grp = df_pat_grp |> dplyr::mutate(RDGRPNAME = "A"),
               df_pat_llt = df_pat_llt)
Evénements indésirables
Total
AE
N (%)		 Patient
N (%)
Total
Total 5 (100.0) 4 (40.0)
Cardiac Disorders
Total 3 ( 60.0) 2 (20.0)
Myocardial Infarction 2 ( 40.0) 2 (20.0)
Arrhythmia 1 ( 20.0) 1 (10.0)
Infections
Total 2 ( 40.0) 2 (20.0)
Pneumonia 2 ( 40.0) 2 (20.0)
 
desc_ei_per_grade(df_pat_grp = df_pat_grp,
                  df_pat_grade = df_pat_llt |> dplyr::mutate(RDGRPNAME = "A"))
Grade
Total
A
B
C
AE
N (%)		 Patient
N (%)		 AE
N (%)		 Patient
N (%)		 AE
N (%)		 Patient
N (%)		 AE
N (%)		 Patient
N (%)
Any grade 5 (100.0) 4 (40.0) 3 (100.0) 2 (66.7) 0 ( 0.0) 0 ( 0.0) 2 (100.0) 2 (50.0)
1 1 ( 20.0) 1 (10.0) 1 ( 33.3) 1 (33.3)



2 1 ( 20.0) 1 (10.0)



1 ( 50.0) 1 (25.0)
3 1 ( 20.0) 1 (10.0) 1 ( 33.3) 1 (33.3)



4 2 ( 40.0) 2 (20.0) 1 ( 33.3) 1 (33.3)

1 ( 50.0) 1 (25.0)
SAE 2 ( 40.0) 2 (20.0) 1 ( 33.3) 1 (33.3)

1 ( 50.0) 1 (25.0)

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:

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.

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.

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.

plot_butterfly_stacked_barplot(df_pat_llt = df_pat_llt,
                               df_pat_grp = df_pat_grp)

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:

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.

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.