---
title: "Advanced user in-text tables"
author: "Laure Cougnaud"
date: "`r format(Sys.Date(), '%B %d, %Y')`"
output: 
  rmarkdown::html_document:
    toc: true
    toc_float: true
    toc_depth: 5
    number_sections: true
vignette: >
  %\VignetteIndexEntry{Advanced user of in-text tables}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

In this vignette we focus on providing more explanation on how
the `inTextSummaryTable` package actually works. We would describe some of the
functionalities less exposed to the users.

We assume you are already familiar on how to create and export tables, otherwise
we advise to first check out the dedicated vignettes for creating and
exporting tables. The vignettes are accessible with the commands below.

```{r getVignette, eval = FALSE}

vignette("inTextSummaryTable-createTables", "inTextSummaryTable")
vignette("inTextSummaryTable-exportTables", "inTextSummaryTable")

```

We will first create example data sets to show how the exporting functionalities
work. The data sets used are available in the `clinUtils` package.


```{r options, echo = FALSE}

library(knitr)
opts_chunk$set(
    echo = TRUE, results = 'markup', warning = FALSE, 
    # stop document execution if error (not the default)
    error = FALSE, 
    message = FALSE, cache = FALSE,
    fig.width = 8, fig.height = 7,
    fig.path = "./figures_vignette/",
    fig.align = 'center')
options(width = 170)
# instead of warn = 0 by default
# include warnings when they occur in the document
options(warn = 1)

```

```{r loadPackages}

library(inTextSummaryTable)
library(clinUtils)
library(pander)
library(tools) # toTitleCase

```

```{r loadData}	

# load example data
data(dataADaMCDISCP01)

dataAll <- dataADaMCDISCP01
labelVars <- attr(dataAll, "labelVars")

dataADSL <- dataADaMCDISCP01$ADSL

```


```{r formatExampleData}

dataAE <-  subset(dataAll$ADAE, SAFFL == "Y" & TRTEMFL == "Y")
dataAEInterest <- subset(dataAE, AESOC %in% c(
        "INFECTIONS AND INFESTATIONS",
        "GENERAL DISORDERS AND ADMINISTRATION SITE CONDITIONS"
    )
)

# ensure that order of elements is the one specified in 
# the corresponding numeric variable
dataAEInterest$TRTA <- reorder(dataAEInterest$TRTA, dataAEInterest$TRTAN)
dataAEInterest$AESEV <- factor(dataAEInterest$AESEV, levels = c("MILD", "MODERATE"))

dataTotalAE <- subset(dataAll$ADSL, TRT01A != "Placebo")
# should contain columns specified in 'colVar'
dataTotalAE$TRTA <- dataTotalAE$TRT01A 

```

# Detailed framework of the creation of the in-text table

The `getSummaryStatisticsTable` consists of the following framework:

* **computation of the summary statistics** table with the
  **`computeSummaryStatisticsTable`** function
* **export of the table** to the required format with the **`outputType`**
  parameter

## Computation of the summary statistics

The supporting data for the summary statistics table, is accessed via the
**`computeSummaryStatisticsTable`**. This includes the entire set of
statistics (as numeric) and combined statistic set.

The output from the `computeSummaryStatisticsTable` is equivalent of the table
output by the `getSummaryStatisticsTable` function when the `outputType` is set
to 'data.frame-base'.

```{r computeSummaryStatisticsTable}

summaryTable <- computeSummaryStatisticsTable(
    data = dataAEInterest,
    rowVar = c("AESOC", "AEDECOD"),
    rowVarTotalInclude = c("AESOC", "AEDECOD"),
    colVar = "TRTA",
    stats = getStats("n (%)"),
    dataTotal = dataTotalAE,
    labelVars = labelVars,
    rowVarLab = c('AESOC' = "TEAE by SOC and Preferred Term\nn (%)")
)

pander(head(summaryTable, 3))

```	

Please note the presence of the **`isTotal` column**, which flags the records
containing the number of subjects reported in the table header.

```{r computeSummaryStatisticsTable-isTotal}

pander(subset(summaryTable, isTotal))

```	

## Export table to the requested format

The summary table is exported to the format of interest with:

```{r export-flextable}

export(
	summaryTable = summaryTable,
	outputType = "flextable"
)

```	

Please see the vignette: `inTextSummaryTable-exportTables` for more
information on the different export types available.

# Combine summary statistics table

## Via the `combine` function

Summary statistics tables can be combined with the `combine` function.

```{r combine}
tableDemoCat <- computeSummaryStatisticsTable(
	data = dataADSL,
	var = c("SEX", "AGE"), varInclude0 = TRUE,
	colVar = "TRT01P",
	stats = getStats("n (%)", includeName = FALSE),
	labelVars = labelVars
)
tableDemoCont <- computeSummaryStatisticsTable(
	data = dataADSL,
	var = c("HEIGHTBL", "WEIGHTBL"),
	colVar = "TRT01P",
	stats = getStats(c("n", "Mean")),
	labelVars = labelVars
)
tableDemo <- combine(tableDemoCat, tableDemoCont)
export(tableDemo)
```

## Manually

The tables created via the `inTextSummaryTable` are simple R `data.frame` objects,
so these can be combined/update to include extra statistics of interest.

The general workflow is to:

* create a table of descriptive statistics with the package 
(via the `computeSummaryStatisticsTable` function)
* create a `data.frame` with your statistics of relevance - in a similar format 
* combine your table with a table created by the package
* export it (via the `exportSummaryStatisticsTable` function)

For example, we combine the descriptive statistics table created above
with a set of pre-computed statistics (e.g. p-values of the difference between the treatment
groups).

```{r combine-manually}
dataADSL$TRT01P <- with(dataADSL, reorder(TRT01P, TRT01PN))

# check format of table created with the package:
descTable <- tableDemoCont
descTable[, c("variable", "TRT01P", "isTotal", "n", "Mean")]
```

### Statistics in rows

```{r combine-manually-rows}
# add p-values in an extra row
infTable <- unique(subset(descTable, !isTotal)[, c("variable", "TRT01P"), drop = FALSE])
infTable[which(infTable$variable == "Baseline Height (cm)"), "pValue"] <- 1e-10
infTable[which(infTable$variable == "Baseline Weight (kg)"), "pValue"] <- 1e-9
summaryTable <- plyr::rbind.fill(descTable, infTable)

exportSummaryStatisticsTable(
	summaryTable = summaryTable, 
	rowVar = "variable", 
	colVar = "TRT01P", 
	statsVar = c("n", "Mean", "pValue") 
)
```

### Statistics in rows, in an extra column

```{r combine-manually-columns}
compLab <- "Comparison between treatments (p-value)"

# add p-values in a new column - in an extra row
infTable <- unique(subset(descTable, !isTotal)[, "variable", drop = FALSE])
infTable$TRT01P <- compLab
infTable[which(infTable$variable == "Baseline Height (cm)"), "pValue"] <- 1e-10
infTable[which(infTable$variable == "Baseline Weight (kg)"), "pValue"] <- 1e-9 
summaryTable <- plyr::rbind.fill(descTable, infTable) 

# order columns to have comparison column as last 
summaryTable$TRT01P <- factor(summaryTable$TRT01P, levels = c(levels(dataADSL$TRT01P), compLab))
exportSummaryStatisticsTable(
	summaryTable = summaryTable,  
	rowVar = "variable",  
	colVar = "TRT01P",  
	statsVar = c("n", "Mean", "pValue")
)
```

### Statistics in an extra column

```{r combine-manually-columns-rows}
infTable <- unique(subset(descTable, !isTotal)[, "variable", drop = FALSE])
infTable$TRT01P <- compLab
infTable[which(infTable$variable == "Baseline Height (cm)"), "Mean"] <- 1e-10
infTable[which(infTable$variable == "Baseline Weight (kg)"), "Mean"] <- 1e-9

summaryTable <- plyr::rbind.fill(descTable, infTable) 

# order columns to have comparison column as last 
summaryTable$TRT01P <- factor(summaryTable$TRT01P, levels = c(levels(dataADSL$TRT01P), compLab)) 

exportSummaryStatisticsTable(
	summaryTable = summaryTable,
	rowVar = "variable",
	colVar = "TRT01P",
	statsVar = c("n", "Mean")
)
```

# Data pre-processing

The variables used for the row and columns of the summary statistics tables
should be present in a long format in the input data for the
`getSummaryStatisticsTable` function.

In case the grouping of the rows/columns is more complex and no grouping
variable is yet available in the data, the function `combineVariables` offers
simpler functionalities to create the input data.

The label for the grouping is extracted from the SAS dataset labels if
`labelVars` is specified, or can be customized (`label` parameter).

For example, the adverse events are counted for different population set:
screened population, completer population, only events with high severity, or
related to the treatment and with high severity.

```{r combineVariables}

# prepare the data: create grouping of interest
dataAEGroup <- combineVariables(
    data = dataAEInterest,
    newVar = "AEGRP",
    paramsList = list(
        # for all screened patients
        list(var = "TRTA", value = "Xanomeline High Dose"),
        # for moderate severity
        list(var = "AESEV", value = "MODERATE", labelExtra = "Moderate"),
        list(var = "AENDY", label = paste("With adverse events ending date"))
    ),
    # include also counts for all records
    includeAll = TRUE,
    labelAll = "All Adverse events", 
    labelVars = labelVars
)
labelVars["AEGRP"] <- "Patient groups of interest"

# create the table
getSummaryStatisticsTable(
    data = dataAEGroup,
    colVar = "TRTA", 
    rowVar = "AEGRP", 
    labelVars = labelVars,
    dataTotal = dataTotalAE,
    stats = list(expression(paste0(statN, " (", round(statPercN, 1), ")"))),
    title = "Table: Adverse events: counts for groups of interest",
    footer = "Statistics: n (%)"
)

```

# Appendix

## Session information

```{r includeSessionInfo, echo = FALSE}

pander(sessionInfo())

```