---
title: "Manipulating tbl data frame"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Manipulating tbl data frame}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Introduction

The `tbl` data frame is the main input to the `gentlg` function for creating the RTF/HTML outputs. This vignette will show you the `tbl` structure and how the `tbl` variables are in action for rendering the RTF/HTML outputs.

### Basic tbl data frame

The basic variables of tbl includes label, col1, col2, ..., coln, where

* label: row text displayed on the 1st column of the table

* col1: statistic results displayed on the 2nd column of the table

* col2: statistic results displayed on the 3rd column of the table.

The example below shows you a very basic tbl data frame, and how this tbl is transformed  through the `gentlg` function call to create the HTML output.

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

tbl <- tibble::tribble(
               ~label,      ~col1,      ~col2,      ~col3,
  "Analysis Set: ITT",       "86",       "84",       "84",
        "Age (Years)",         NA,         NA,         NA,
                  "N",       "86",       "84",       "84"
)

knitr::kable(tbl)

# render tbl
gentlg(huxme       = tbl,
          format      = "HTML",
          orientation = "landscape",
          opath       = ".",
          file        = "DEMO1",
          title       = "Basic tbl without formatting",
          colheader   = c("", "Placebo", "Active 1", "Active 2"),
          print.hux = FALSE,
          wcol        = .30)
```

## Formatting table

The above example does not have any formatting in actions on the table. To enable formatting, additional variables will need to be created in the `tbl` data frame.

### Add new row

For inserting a blank line prior to the 2nd row (i.e. Age (Years)), we will need to add the `newrows` variable with value = `1`.

```{r}
tbl <- tbl %>%
  mutate(newrows = case_when(label == "Age (Years)" ~ 1,
                             TRUE ~ 0))

knitr::kable(tbl)

# render tbl
gentlg(huxme       = tbl,
          format      = "HTML",
          orientation = "landscape",
          opath       = ".",
          file        = "DEMO2",
          title       = "Adding the variable of newrows",
          colheader   = c("", "Placebo", "Active 1", "Active 2"),
          print.hux = FALSE,
          wcol        = .30)
```

### Add indentation

For adding 1 indentation to the `N` row, we will need to add the `indentme` variable with value = 1, which indicates 1 indentation (2 will result in 2 indentation, and so on).

```{r}
tbl <- tbl %>%
  mutate(indentme = case_when(label == "N" ~ 1,
                             TRUE ~ 0))

knitr::kable(tbl)

# render tbl
gentlg(huxme       = tbl,
          format      = "HTML",
          orientation = "landscape",
          opath       = ".",
          file        = "DEMO3",
          title       = "Adding the variable of indentme",
          colheader   = c("", "Placebo", "Active 1", "Active 2"),
          print.hux = FALSE,
          wcol        = .30)
```

### Enable bold font

To enable bolding on the row of `Age (Years)`, the `boldme` variable with value = 1 will need to be added.

```{r}
tbl <- tbl %>%
  mutate(boldme = case_when(label == "Age (Years)" ~ 1,
                             TRUE ~ 0))

knitr::kable(tbl)

# render tbl
gentlg(huxme       = tbl,
          format      = "HTML",
          orientation = "landscape",
          opath       = ".",
          file        = "DEMO4",
          title       = "Adding the variable of boldme",
          colheader   = c("", "Placebo", "Active 1", "Active 2"),
          print.hux = FALSE,
          wcol        = .30)
```

There is another formatting variable called `newpage`, where assigning `newpage = 1` will start a new page in the output.

## Fomatting functions

Besides manually adding the formatting variables to `tbl`, we have developed several formatting functions to facilitate the formatting process:

* `add_newrows`: add `newrows` variable to the `tbl` based on `row_type`

* `add_indent`: add `indentme` variable to the `tbl` based on `row_type`

* `add_newpage`: add `newpage` variable to the `tbl` based on `row_type`.

The `row_type` variable is created in the tbl by calling the `freq`, `nested_freq`, and `univar` functions, which is used by the above functions for setting up the formatting variables. The `tbl` example below is obtained by calling the `univar` function for summarizing the age statistics in the CDISC ADSL dataset. After calling the `univar` function, we create the `anbr` (analysis number) variable as the identifier of this `tbl` chunk.

```{r}
tbl <- cdisc_adsl %>%
  univar(colvar = "TRT01PN",
         rowvar = "AGE",
         statlist = statlist(c("N", "MEANSD")),
         decimal = 0,
         row_header = "Age (Years)") %>%
  mutate(anbr = "01")

knitr::kable(tbl)
```

The `add_format` function, which incorporates all 3 formatting functions above (`add_indent`, `add_newrows`, `add_newpage`), can then be applied to the `tbl` for creating the formatting variables.

```{r}
tbl <- cdisc_adsl %>%
  univar(colvar = "TRT01PN",
         rowvar = "AGE",
         statlist = statlist(c("N", "MEANSD")),
         decimal = 0,
         row_header = "Age (Years)") %>%
  mutate(anbr = "01") %>%
  add_format()

knitr::kable(tbl)

# render tbl
gentlg(huxme       = tbl,
          tlf         = "Table",
          format      = "HTML",
          orientation = "landscape",
          opath       = ".",
          file        = "DEMO5",
          title       = "Using row_type to set up indentation",
          colheader   = c("", "Placebo", "Active 1", "Active 2"),
          print.hux = FALSE,
          wcol        = .30)
```

The default indentation for each row_type is shown below.

| row_type          | default indentation |
| ----------------- |:-------------------:|
| TABLE_BY_HEADER   | 0                   |
| BY_HEADER[1-9]    | 0                   |
| HEADER            | 0                   |
| N                 | 1                   |
| VALUE             | 2                   |
| NESTED            | 0                   |