-
Notifications
You must be signed in to change notification settings - Fork 49
/
introspecting_tables.Rmd
150 lines (111 loc) · 4.78 KB
/
introspecting_tables.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
---
title: "Introspecting Tables"
author: "Gabriel Becker and Adrian Waddell"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Introspecting Tables}
%\VignetteEncoding{UTF-8}
%\VignetteEngine{knitr::rmarkdown}
editor_options:
chunk_output_type: console
---
```{r, echo=FALSE}
knitr::opts_chunk$set(comment = "#")
```
The packages used in this vignette are `rtables` and `dplyr`:
```{r, message=FALSE}
library(rtables)
library(dplyr)
```
## Introduction
First, let's set up a simple table.
```{r}
lyt <- basic_table(show_colcounts = TRUE) %>%
split_cols_by("ARMCD") %>%
split_cols_by("STRATA2") %>%
split_rows_by("STRATA1") %>%
add_overall_col("All") %>%
summarize_row_groups() %>%
analyze("AGE", afun = max, format = "xx.x")
tbl <- build_table(lyt, ex_adsl)
tbl
```
## Getting Started
We can get basic table dimensions, the number of rows, and the number of columns with the following code:
```{r}
dim(tbl)
nrow(tbl)
ncol(tbl)
```
## Detailed Table Structure
The `table_structure()` function prints a summary of a table's row
structure at one of two levels of detail. By default, it summarizes
the structure at the subtable level.
```{r}
table_structure(tbl)
```
When the `detail` argument is set to `"row"`, however, it provides a
more detailed row-level summary which acts as a useful alternative to
how we might normally use the `str()` function to interrogate compound
nested lists.
```{r}
table_structure(tbl, detail = "row")
```
The `make_row_df()` and `make_col_df()` functions each create a `data.frame` with a variety of information about
the table's structure. Most useful for introspection purposes are the `label`, `name`, `abs_rownumber`, `path` and
`node_class` columns (the remainder of the information in the returned `data.frame` is used for pagination)
```{r}
make_row_df(tbl)[, c("label", "name", "abs_rownumber", "path", "node_class")]
```
There is also a wrapper function, `row_paths()` available for `make_row_df` to display only the row path structure:
```{r}
row_paths(tbl)
```
By default `make_row_df()` summarizes only visible rows, but setting `visible_only` to `FALSE` gives us a structural
summary of the table with the full hierarchy of subtables, including those that are not represented directly by any
visible rows:
```{r}
make_row_df(tbl, visible_only = FALSE)[, c("label", "name", "abs_rownumber", "path", "node_class")]
```
`make_col_df()` similarly accepts `visible_only`, though here the meaning is slightly different, indicating whether
only *leaf* columns should be summarized (defaults to `TRUE`) or whether higher level groups of columns - analogous to
subtables in row space - should be summarized as well.
```{r}
make_col_df(tbl)[, c("label", "name", "abs_pos", "path", "leaf_indices")]
```
```{r}
make_col_df(tbl, visible_only = FALSE)[, c("label", "name", "abs_pos", "path", "leaf_indices")]
```
Similarly, there is wrapper function `col_paths()` available, which displays only the column structure:
```{r}
col_paths(tbl)
```
The `row_paths_summary()` and `col_paths_summary()` functions wrap the respective `make_*_df` functions, printing the
`name`, `node_class`, and `path` information (in the row case), or the `label` and `path` information (in the column
case), indented to illustrate table structure:
```{r}
row_paths_summary(tbl)
```
```{r}
col_paths_summary(tbl)
```
## Insights on Value Format Structure
We can gain insight into the value formatting structure of a table using `table_shell()`, which returns a table with the same output as `print()` but with the cell values replaced by their underlying format strings (e.g. instead of `40.0`, `xx.x` is displayed, and so on). This is useful for understanding the structure of the table, and for debugging purposes. Another useful tool is the `value_formats()` function which instead of a table returns a matrix of the format strings for each cell value in the table.
See below the printout for the above examples:
```{r}
table_shell(tbl)
```
```{r}
value_formats(tbl)
```
## Applications
Knowing the structure of an `rtable` object is helpful for retrieving specific values from the table.
For examples, see the [Path Based Cell Value Accessing](https://insightsengineering.github.io/rtables/latest-tag/articles/subsetting_tables.html#path-based-cell-value-accessing)
section of the Subsetting and Manipulating Table Contents vignette.
Understanding table structure is also important for post-processing processes such as sorting and pruning. More details
on this are covered in the [Pruning and Sorting Tables vignette](https://insightsengineering.github.io/rtables/latest-tag/articles/sorting_pruning.html)
vignette.
## Summary
In this vignette you have learned a number of utility functions that are available for examining the underlying
structure of `rtable` objects.