Merge pull request #29 from Merck/vignette-base-char-subgroup

add examples to vignettes for baseline characteristic table

vignettes/baseline-character.Rmd

@@ -0,0 +1,263 @@
+---
+title: "Getting Started with Baseline Characteristics Table"
+output:
+  rmarkdown::html_document:
+    toc: true
+    toc_float: true
+    toc_depth: 2
+    number_sections: true
+    highlight: "textmate"
+    css: "custom.css"
+vignette: >
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteIndexEntry{Getting Started with Baseline Characteristics Table}
+---
+
+```{r}
+library(metalite)
+library(metalite.sl)
+```
+
+# Create Baseline Characteristic Table
+
+The baseline characteristic analysis aims to provide tables to summarize details of participants.
+The development of baseline characteristic analysis involves functions:
+
+- `prepare_base_cha`: prepare analysis raw datasets.
+- `format_base_char`: prepare analysis (mock) outdata with proper format.
+- `rtf_base_char`: transfer (mock) output dataset to RTF table.
+
+## Build a metadata
+
+```{r}
+adsl <- r2rtf::r2rtf_adsl
+adsl$TRTA <- adsl$TRT01A
+adsl$TRTA <- factor(
+  adsl$TRTA,
+  levels = c("Placebo", "Xanomeline Low Dose", "Xanomeline High Dose"),
+  labels = c("Placebo", "Low Dose", "High Dose")
+)
+```
+
+```{r}
+plan <- plan(
+  analysis = "base_char",
+  population = "apat",
+  observation = "apat",
+  parameter = "age;gender;race"
+)
+```
+
+```{r}
+meta <- meta_adam(population = adsl,
+                  observation = adsl) |>
+  define_plan(plan = plan) |>
+  define_population(
+    name = "apat",
+    group = "TRTA",
+    subset = quote(SAFFL == "Y"),
+    var = c("USUBJID", "TRTA", "SAFFL", "AGEGR1", "SEX", "RACE")
+  ) |>
+  define_parameter(
+    name = "age",
+    var = "AGE",
+    label = "Age (years)",
+    vargroup = "AGEGR1"
+  ) |>
+  define_parameter(name = "gender",
+                   var = "SEX",
+                   label = "Gender") |>
+  define_parameter(name = "race",
+                   var = "RACE",
+                   label = "Race") |>
+  define_analysis(name = "base_char",
+                  title = "Participant Baseline Characteristics by Treatment Group",
+                  label = "baseline characteristic table") |>
+  meta_build()
+```
+
+## Analysis preparation
+
+The input of the function `prepare_base_char()` is a `meta` object created by the metalite package.
+
+```{r}
+outdata <- meta |>
+  prepare_base_char(parameter = "age;gender;race")
+
+outdata
+
+outdata$n
+outdata$char_n
+outdata$char_var
+outdata$char_prop
+```
+
+## Format the numbers
+
+`format_base_char` to prepare analysis dataset before generate RTF output
+
+```{r}
+outdata <-
+  outdata |> format_base_char(display_col = c("n", "prop", "total"),
+                              digits_prop = 2)
+
+outdata$tbl
+```
+
+```{r}
+outdata <-
+  outdata |> format_base_char(display_col = c("n", "prop"), digits_prop = 3)
+
+outdata$tbl
+```
+
+## Output as RTF
+
+`rtf_base_char` to generate RTF output
+
+```{r}
+outdata |> rtf_base_char(
+  source = "Source: [CDISCpilot: adam-adsl]",
+  path_outdata = tempfile(fileext = ".Rdata"),
+  path_outtable = "base_char.rtf"
+)
+```
+
+# Create Baseline Characteristic Table for Subgroup Analysis 
+
+The baseline characteristic subgroup analysis aims to provide tables to summarize details of participants by subgroup.
+The development of baseline characteristic subgroup analysis involves functions:
+
+- `prepare_base_char_subgroup()`: prepare analysis raw datasets.
+- `format_base_char_subgroup()`: prepare analysis (mock) outdata with proper format.
+- `rtf_base_char_subgroup()`: transfer (mock) output dataset to RTF table.
+
+## Build a metadata
+
+```{r}
+adsl <- r2rtf::r2rtf_adsl
+adsl$TRTA <- adsl$TRT01A
+adsl$TRTA <- factor(
+  adsl$TRTA,
+  levels = c("Placebo", "Xanomeline Low Dose", "Xanomeline High Dose"),
+  labels = c("Placebo", "Low Dose", "High Dose")
+)
+
+```
+
+```{r}
+plan <- plan(
+  analysis = "base_char",
+  population = "apat",
+  observation = "apat",
+  parameter = "age;gender;race"
+) |>
+  add_plan(
+    analysis = "base_char_subgroup",
+    population = "apat",
+    observation = "apat",
+    parameter = "age"
+  ) 
+```
+
+```{r}
+meta <- meta_adam(population = adsl,
+                  observation = adsl) |>
+  define_plan(plan = plan) |>
+  define_population(
+    name = "apat",
+    group = "TRTA",
+    subset = quote(SAFFL == "Y"),
+    var = c("USUBJID", "TRTA", "SAFFL", "AGEGR1", "SEX", "RACE")
+  ) |>
+  define_parameter(
+    name = "age",
+    var = "AGE",
+    label = "Age (years)",
+    vargroup = "AGEGR1"
+  ) |>
+  define_parameter(name = "gender",
+                   var = "SEX",
+                   label = "Gender") |>
+  define_parameter(name = "race",
+                   var = "RACE",
+                   label = "Race") |>
+  define_analysis(name = "base_char",
+                  title = "Participant Baseline Characteristics by Treatment Group",
+                  label = "baseline characteristic table") |>
+  define_analysis(name = "base_char_subgroup",
+                  title = "Participant by Age Category and Sex",
+                  label = "baseline characteristic sub group table") |>
+  meta_build()
+```
+
+## Analysis preparation
+
+```{r}
+meta <- meta_sl_example()
+```
+
+The input of the function `prepare_base_char_subgroup()` is a `meta` object created by the metalite package.
+
+The output of the function is an `outdata` object containing a list of analysis
+raw datasets. Key arguments are:
+
+- `subgroup_var`: a character value of subgroup variable name in observation data saved in meta$data_observation.
+- `subgroup_header`: a character vector for column header hierarchy. The first element will be the first level header and the second element will be second level header.
+
+```{r}
+outdata <- prepare_base_char_subgroup(
+  meta,
+  population = "apat",
+  parameter = "age",
+  subgroup_var = "TRTA",
+  subgroup_header = c("SEX", "TRTA"),
+  display_subgroup_total = TRUE
+)
+```
+
+The output dataset contains commonly used statistics within each `subgroup_var`.
+
+```{r}
+outdata$out_all$`Placebo`
+outdata$out_all$`High Dose`
+outdata$out_all$`Low Dose`
+```
+
+The information about subgroup saved with `outdata$group` and `outdata$subgroup`.
+
+```{r}
+outdata$group
+outdata$subgroup
+```
+
+`n_pop`: participants in population within each `subgroup_var`.
+
+```{r}
+outdata$out_all$`Placebo`$n
+outdata$out_all$`High Dose`$n
+outdata$out_all$`Low Dose`$n
+```
+
+## Format output
+
+`format_base_char_subgroup` to prepare analysis dataset before generate RTF output
+
+```{r}
+tbl <- format_base_char_subgroup(outdata)
+head(tbl$tbl)
+```
+
+## Output as RTF
+
+`rtf_base_char_subgroup` to generate RTF output
+
+```{r warning=FALSE}
+outdata |>
+  format_base_char_subgroup() |>
+  rtf_base_char_subgroup(
+    source = "Source:  [CDISCpilot: adam-adsl]",
+    path_outdata = tempfile(fileext = ".Rdata"),
+    path_outtable = "base_char_subgroup.rtf"
+  )
+```