template-fig_03.qmd

---
title: FDA Figure 3
subtitle: Figure 3. Time to Adverse Event Leading to Treatment Discontinuation, Safety Population, Trial X
format: html
---

::: panel-tabset
## Spec. Screenshot

![](../assets/images/screenshots/fig_03.png){fig-align="center"}

## ggplot2 Figure

```{r fig, message=FALSE, warning=FALSE}
# Load Libraries & Data
library(falcon)

# Output Figure
make_fig_03(df = adsl, dctreas_var = "DCSREAS")
```

## Figure Setup

```{r fig, eval=FALSE, echo=TRUE}
```

## Function Details

### `make_fig_03()`

------------------------------------------------------------------------

Required variables:

-   **`df`**: The variables specified by `arm_var`, `id_var`, `saffl_var`, `trtsdtm_var`, `trtedtm_var` and `dctreas_var`.

| Argument      | Description                                                                                                                                                                                                                         | Default                                           |
|:--------------|:------------------------------------------|:--------------|
| `df`          | (`data.frame`) Dataset (typically ADSL) required to build figure.                                                                                                                                                                   | *No default*                                      |
| `arm_var`     | (`character`) Arm variable used to split table into columns.                                                                                                                                                                        | `"ARM"`                                           |
| `saffl_var`   | (`character`) Flag variable used to indicate inclusion in safety population.                                                                                                                                                        | `"SAFFL"`                                         |
| `id_var`      | (`character`) Identifier variable used to count the participants within each flag.                                                                                                                                                  | `"USUBJID"`                                       |
| `trtsdtm_var` | (`character`) Treatment start datetime variable in df.                                                                                                                                                                              | `"TRTSDTM"`                                       |
| `trtedtm_var` | (`character`) Treatment end datetime variable in df.                                                                                                                                                                                | `"TRTEDTM"`                                       |
| `u_trtdur`    | (`character`) Unit for duration of treatment. Options are `"days"`, `"weeks"`, `"months"` and `"years"`.                                                                                                                            | `"days"`                                          |
| `dctreas_var` | (`character`) Reason for treatment discontinuation variable used to split figure into lines.                                                                                                                                        | `"DCTREAS"`                                       |
| `x_lab`       | (`character`) x-axis label.                                                                                                                                                                                                         | `paste0("Time from first dose (", u_trtdur, ")")` |
| `y_lab`       | (`character`) y-axis label.                                                                                                                                                                                                         | `"Percent of Patients (%)"`                       |
| `xticks`      | (`vector` of `numeric`) x-axis tick positions. If `NA` (default), tick mark positions are automatically calculated.                                                                                                                 | `NA`                                              |
| `add_table`   | (`flag`) whether "Number of Patients" table should be printed under the plot.                                                                                                                                                       | `TRUE`                                            |
| `annotations` | (named `list` of `character`) List of annotations to add to the figure. Valid annotation types are `title`, `subtitles`, and `caption`. Each name-value pair should use the annotation type as name and the desired string as value. | `NULL`                                            |

Source code for this function is available [here](https://github.com/pharmaverse/falcon/blob/main/R/fda-fig_03.R).
:::