---
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 or HTML outputs.
This vignette will show you the `tbl` structure and how the `tbl` variables are in action for
rendering the RTF or HTML outputs.

### Basic `tbl` data frame

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

* `label`: row text displayed on the first column of the table
* `col1`: statistic results displayed on the second column of the table
* `col2`: statistic results displayed on the third 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 second 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 one indentation to the `N` row, we will need to add the `indentme`
variable with `value = 1`, which indicates one indentation (two will result in two 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 bold font 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.

## Formatting 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                   |