---
title: "Subsetting Tables"
author: "Gabriel Becker and Adrian Waddell"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Subsetting Tables}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
editor_options: 
  chunk_output_type: console
---


```{r, echo=FALSE}
knitr::opts_chunk$set(comment = "")
```

```{css, echo=FALSE}
.reveal .r code {
    white-space: pre;
}
```

## Introduction

`TableTree` objects are based on a tree data structure as the name indicates. The package is written such that the user
does not need to walk trees for many basic table manipulations. Walking trees will still be necessary for certain
manipulation and will be the subject of a different vignette.

In this vignette we show some methods to subset tables and to extract cell values.

We will use the following table for illustrative purposes:

```{r}
library(rtables)
library(dplyr)

tbl <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_rows_by("SEX", split_fun = drop_split_levels) %>%
  analyze(c("AGE", "STRATA1")) %>%
  build_table(ex_adsl %>% filter(SEX %in% c("M", "F")))

tbl
```


The `[` accessor function always returns an `TableTree` object if `drop=TRUE` is not set. The first argument are the row indices and the second argument the column indices. Alternatively logical subsetting can be used. The indices are based on visible rows and not on the tree structure. So:

```{r}
tbl[1, 1]
```

is a table with an empty cell  because the first row is a label row. We need to access a cell with actual cell data:

```{r}
tbl[3, 1]
```

which is another `TableTree` and not an `rcell`. If we wanted the `rcell` we need to use the `drop` argument:

```{r}
tbl[3, 1, drop = TRUE]
```


One can access multiple rows and columns:

```{r}
tbl[1:3, 1:2]
```


Note that we do not repeat label rows for descending children, e.g.

```{r}
tbl[2:4, ]
```

does not show that the first row is derived from `AGE`. In order to repeat content/label information one should use the pagination feature. Please read the related vignette.



## Path Based Cell Value Accessing:

Cell values can also be access via path information. The functions `row_paths`, `col_paths`, `row_paths_summary`, `col_paths_summary` are helpful to get information on the paths.


```{r}
tbl2 <- basic_table() %>%
  split_cols_by("ARM") %>%
  split_cols_by("SEX", split_fun = drop_split_levels) %>%
  analyze(c("AGE", "STRATA1")) %>%
  build_table(ex_adsl %>% filter(SEX %in% c("M", "F")))

tbl2
```

So the column paths are as follows:

```{r}
col_paths_summary(tbl2)
```

and the row paths are as follows:

```{r}
row_paths_summary(tbl2)
```

So in order to get the average age for all female patients in arm `A: Drug X`:

```{r}
value_at(tbl2, c("AGE",  "Mean"), c("ARM", "A: Drug X", "SEX", "F"))
```

You can also request information from non-cell specific paths with the `cell_values` function:

```{r}
cell_values(tbl2, c("AGE", "Mean"), c("ARM", "A: Drug X"))
```

Note the return value of `cell_values` is always a list even if you specify a path to a cell:

```{r}
cell_values(tbl2, c("AGE",  "Mean"), c("ARM", "A: Drug X", "SEX", "F"))
```

Hence, use `value_at` if you want to access data from a cell, and `cell_values` if you want to access data from multiple cells.
