Merge pull request #53 from yuliasidi/main

vignette on meta_forestly

.Rbuildignore

@@ -14,3 +14,5 @@
 ^vignettes/design-pattern.Rmd$
 ^vignettes/forestly.Rmd$
 ^vignettes/layout.Rmd$
+^vignettes/meta-forestly.Rmd$
+

_pkgdown.yml

@@ -33,6 +33,7 @@ articles:
   contents:
   - forest-plot-static
   - layout
+  - meta-forestly
 - title: Package design
   contents:
   - design-pattern

vignettes/meta-forestly.Rmd

@@ -0,0 +1,141 @@
+---
+title: "A closer look at meta_forestly()"
+output:
+  rmarkdown::html_document:
+    self_contained: no
+    number_sections: yes
+    code_folding: hide
+vignette: |
+  %\VignetteIndexEntry{A closer look at meta_forestly()}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>",
+  message = FALSE,
+  warning = FALSE,
+  eval = TRUE,
+  echo = TRUE
+)
+```
+
+```{r}
+library(forestly)
+library(metalite)
+```
+
+```{r, echo = FALSE}
+data(forestly_adsl)
+data(forestly_adae)
+```
+
+
+# Overview
+
+`meta_forestly()` is the first step in the interactive forest plot generation workflow and is a wrapper of several functions from [metalite](https://merck.github.io/metalite/). Specifically, it defines a metadata, including ADaM datesets, population, observations and parameters to be used in the forest plot. 
+In this vignette we will take a closer look at the `parameter_term` argument in `meta_forestly()` to better understand how to generate the forest plot for different parameters of interest.
+
+# `parameter_term` examples
+
+Prior to turning to the examples, just a reminder that the treatment group variable in the ADaM datasets should be set as a factor, otherwise a warning will be generated. 
+For example, if this is what you have in the `TRT01A`:
+```{r}
+unique(forestly_adsl$TRT01A)
+```
+
+you can easily turn it into a factor variable with the desired labels using the following code: 
+
+```{r}
+forestly_adsl$TRTA <- factor(
+  forestly_adsl$TRT01A, 
+  levels = c("Xanomeline Low Dose", "Placebo"), 
+  labels = c("Low Dose", "Placebo")
+  )
+```
+
+A similar approach needs to be applied to the `TRTA`:
+
+```{r}
+forestly_adae$TRTA <- factor(
+  forestly_adae$TRTA, 
+  levels = c("Xanomeline Low Dose", "Placebo"), 
+  labels = c("Low Dose", "Placebo")
+  )
+```
+
+If the deliverable requires a forest plot of all adverse events and serious adverse events, then the following code could be used with `any` and `ser` parameters in `parameter_term` argument respectively:
+
+```{r}
+meta_forestly(
+  dataset_adsl = forestly_adsl,
+  dataset_adae = forestly_adae,
+  parameter_term = "any;ser"
+) |>
+  prepare_ae_forestly() |>
+  format_ae_forestly() |>
+  ae_forestly()
+```
+
+However, if grade 3-5 adverse events need to be plotted as well, we can add `g35` parameter in the `parameter_term`. Click on the AE criteria below to see that a forest plot for grade 3-5 adverse events was added.
+
+```{r}
+meta_forestly(
+  dataset_adsl = forestly_adsl,
+  dataset_adae = forestly_adae,
+  parameter_term = "any;ser;g35"
+) |>
+  prepare_ae_forestly() |>
+  format_ae_forestly() |>
+  ae_forestly()
+```
+
+# Adding a new parameter
+
+Below we demonstrate how to add a new parameter to the `meta_forestly()`. Consider, for instance, that now we need to plot adverse events which resulted in dose reductions, a parameter that is currently not available in the [predefined options](https://merck.github.io/forestly/articles/forestly.html) of the `parameter_term`. Instead of using `meta_forestly()` directly, we will define `meta_new` object using [metalite](https://merck.github.io/metalite/) core functions as demonstrated below. 
+
+Specifically, `define_parameter()` is where the new parameter `reduc` is defined by filtering `forestly_adae` with `AEACN == "DOSE REDUCED"` condition in order to identify the adverse events of interest:
+
+```{r}
+meta_new <- meta_adam(
+  population = forestly_adsl,
+  observation = forestly_adae
+  ) |>
+  define_plan(plan = metalite::plan(
+    analysis = "ae_forestly",
+    population = "apat",
+    observation = "all",
+    parameter = "any;ser;g35;reduc"
+    )
+  ) |>
+  define_population(
+    name = "apat",
+    group = "TRTA",
+  ) |>
+  define_observation(
+    name = "all",
+    group = "TRTA",
+    label = "All AEs"
+  ) |>
+  define_parameter(
+    name = "reduc",
+    subset = AEACN == "DOSE REDUCED",
+    label = "adverse events resulting in dose reduction"
+  ) |>
+  define_analysis(
+    name = "ae_forestly",
+    label = "Interactive forest plot"
+  ) |>
+  meta_build()
+```
+
+Now, similar to the originally generated forest plot above, we need to apply `prepare_ae_forestly()`, `format_ae_forestly()`, and `ae_forestly()` to generate the plot that will include adverse events which resulted in dose reductions:
+
+```{r}
+meta_new |>
+  prepare_ae_forestly() |>
+  format_ae_forestly() |>
+  ae_forestly()
+```