---
title: "Column Metadata & How tidytlg Sets Up Your Data Using `tlgsetup`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Column Metadata & How tidytlg Sets Up Your Data Using `tlgsetup`}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup, message=FALSE}
library(dplyr)
library(tidytlg)
```

The `tlgsetup` helper function was created to support generating different column structures for our outputs.  This allows us
to specify column types once that can be used across multiple outputs.  This metadata can be hardcoded as well
(please see the code below), or pulled from another source like a dataframe, file or database.

Here we see an example of the column metadata which defines our columns, how to combine columns, column
labels and spanning headers across columns.

```{r}
column_metadata <-
  tibble::tribble(
    ~tbltype, ~coldef, ~decode,                ~span1,
    "type1",  "0",     "Placebo",              "",
    "type1",  "54",    "Low Dose",             "Xanomeline",
    "type1",  "81",    "High Dose",            "Xanomeline",
    "type1",  "54+81", "Total Xanomeline",     ""
  )
column_metadata
```

In this example, we would summarize `Placebo`, `Xanomeline Low Dose`, and `Xanomeline High Dose`
which are already available in the data. The helper function will add the observations to the data for the
`Total Xanomeline` column based off of `coldef`.  So for our `adsl` data,
we will add a spanning header for `Xanomeline` and a total `Xanomeline` column which is a
combination of the `Xanomeline Low Dose` and `Xanomeline High Dose`.

In addition, the helper function will add the factor variable `colnbr` which is used as our new
column summary variable.  Note that our column summary variable has been converted to a factor.  This is required and allows
us to define column order as well as label in one variable.

Let's read in `adsl` and check the dimensions.

```{r}
data("cdisc_adsl")
adsl <- cdisc_adsl %>%
  filter(ITTFL == "Y") %>%
  select(USUBJID, TRT01PN, TRT01P, ITTFL, SEX, RACE, AGE)
glimpse(adsl)
```

```{r echo = FALSE}
paste0("Dimensions prior to the tlgsetup call are ", dim(adsl)[1], " rows and ", dim(adsl)[2], " columns.")
```

Now let's pass the `adsl` data through our `tlgsetup` function to add observations to support the
`type1` column structure and check out the dimensions.

```{r warning=FALSE}
setup_table <- tlgsetup(adsl,
  var = "TRT01PN",
  column_metadata = column_metadata
)
glimpse(setup_table)
```

```{r echo = FALSE}
paste0(
  "Dimensions after to the rmtsetup call are ", dim(setup_table)[1], " rows and ", dim(setup_table)[2], " columns."
)
```

Here we see we have added two new variables, `colnbr` and `tbltype`, which will now be used as our treatment variable when generating our results.

If we take a look at the observation counts for `colnbr`, we see the 168 records added to the data support `Total Xanomeline` as we expected!
```{r}
setup_table %>%
  group_by(colnbr) %>%
  count()
```
