---
title: "Subgroup Analysis for Specific AE"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{Subgroup Analysis for Specific AE}
  %\VignetteEncoding{UTF-8}
---

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

```{r}
library(metalite.ae)
```

## Overview

The AE specific subgroup analysis aims to provide tables to summarize details of
adverse events by subgroup.
The development of AE specific subgroup analysis involves exported functions:

- `prepare_ae_specific_subgroup()`: prepare analysis raw datasets.
- `format_ae_specific_subgroup()`: prepare analysis (mock) outdata with proper format.
- `tlf_ae_specific_subgroup()`: transfer (mock) output dataset to RTF table.

### Analysis preparation

The `prepare_ae_specific_subgroup()` function is designed to be used for multiple purposes.
The input of the function is a `meta` object created by the metalite package.

```{r}
meta <- meta_ae_example()
```

The output of the function is an `outdata` object containing a list of analysis
raw datasets. Key arguments are `subgroup_var`, `subgroup_header`, and
`display_subgroup_total`.

```{r}
outdata <- prepare_ae_specific_subgroup(
  meta,
  population = "apat",
  observation = "wk12",
  parameter = "rel",
  subgroup_var = "SEX",
  subgroup_header = c("TRTA", "SEX"),
  display_subgroup_total = TRUE
)
```

```{r}
outdata
```

The output dataset contains commonly used statistics within each `subgroup_var`.

```{r}
outdata$out_all$F
outdata$out_all$M
outdata$out_all$Total
```

The variable is indexed by the order of `outdata$group` and `outdata$subgroup`
within each `subgroup_var`.

```{r}
outdata$group
outdata$subgroup
```

The row is indexed by the order of `name` within each `subgroup_var` analysis output.

```{r}
head(data.frame(outdata$out_all$Total$order, outdata$out_all$Total$name))
```

- `n_pop`: participants in population within each `subgroup_var`.

```{r}
outdata$out_all$F$n_pop
outdata$out_all$M$n_pop
outdata$out_all$Total$n_pop
```

- `n`: number of subjects with AE within each `subgroup_var`.

```{r}
head(outdata$out_all$F$n)
head(outdata$out_all$M$n)
head(outdata$out_all$Total$n)
```

- `prop`: proportion of subjects with AE within each `subgroup_var`.

```{r}
head(outdata$out_all$F$prop)
head(outdata$out_all$M$prop)
head(outdata$out_all$Total$prop)
```

- `diff`: risk difference compared with the `reference_group` within each `subgroup_var`.

```{r}
head(outdata$out_all$Total$diff)
```

### Format output

After we have the raw analysis results, we can use `format_ae_specific_subgroup()`
to prepare the outdata to create RTF tables.

```{r}
tbl <- outdata |> format_ae_specific_subgroup()
head(tbl$tbl)
```

We can hide the total column:

```{r}
tbl <- outdata |> format_ae_specific_subgroup(display = c("n", "prop"))
head(tbl$tbl)
```

Adding risk difference:

```{r}
tbl <- outdata |> format_ae_specific_subgroup(display = c("n", "prop", "diff"))
head(tbl$tbl)
```

### Mock data preparation

We can also use `format_ae_specific_subgroup()` to create mock output data.

The purpose of the `mock` argument is not to create a comprehensive mock table template,
but a handy way to help users create a mock table that mimics the exact output layout.

Additional work is required to develop a flexible mock table generation tool
(for example, a dedicated mock table generation package).

```{r}
tbl <- outdata |> format_ae_specific_subgroup(mock = FALSE)
head(tbl$tbl)
```

### RTF tables

By using `tlf_ae_specific_subgroup()`, we can transfer the output from
`format_ae_specific_subgroup()` to an RTF or PDF table.

```{r}
outdata |>
  format_ae_specific_subgroup() |>
  tlf_ae_specific_subgroup(
    meddra_version = "24.0",
    source = "Source:  [CDISCpilot: adam-adsl; adae]",
    path_outtable = "rtf/ae0specific0sub0gender1.rtf"
  )
```

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