Learn R Programming
⚠️There's a newer version (0.6.12) of this package.Take me there.

rtables

Reporting tables with R

The rtables R package was designed to create and display complex tables with R. The cells in an rtable may contain any high-dimensional data structure which can then be displayed with cell-specific formatting instructions. Currently, rtables can be outputted in ascii and html.

Note: we have completely refactored the rtables package which is officially released on CRAN in December 2020. With this significant change please familiarize yourself with the new framework by reading the package vignettes.

rtables is developed and copy written by F. Hoffmann-La Roche and it is released open source under Apache License Version 2.

rtables development is driven by the need to create regulatory ready tables for health authority review. Some of the key requirements for this undertaking are listed below:

  • cell values and their visualization separate (i.e. no string based tables)
    • values need to be programmatically accessible in their non-rounded state for cross-checking
  • multiple values displayed within a cell
  • flexible tabulation framework
  • flexible formatting (cell spans, rounding, alignment, etc.)
  • multiple output formats (html, ascii, latex, pdf, xml)
  • flexible pagination
  • distinguish between name and label in the data structure to work with CDISC standards
  • title, footnotes, cell cell/row/column references

Note that the current state of rtables does not fulfill all of those requirements, however, rtables is still under active development and we are working on adding the missing features.

Installation

rtables is now available on CRAN and you can install the latest released version with:

install.packages("rtables")

or you can install the latest stable version directly from GitHub with:

devtools::install_github("Roche/rtables")

To install a frozen pre-release version of rtables based on the new Layouting and Tabulation API as presented at user!2020 and JSM2020 run the following command in R:

devtools::install_github("roche/rtables", ref="v0.3.3")

To install the latest development version of the new test version of rtables run

devtools::install_github("roche/rtables", ref = "gabe_tabletree_work")

Usage

We first begin with a demographic table alike example and then show the creation of a more complex table.

library(rtables)
#> Loading required package: magrittr

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  analyze(c("AGE", "BMRKR1", "BMRKR2"), function(x, ...) {
    if (is.numeric(x)) {
      in_rows(
        "Mean (sd)" = c(mean(x), sd(x)),
        "Median" = median(x),
        "Min - Max" = range(x),
        .formats = c("xx.xx (xx.xx)", "xx.xx", "xx.xx - xx.xx")
      )
    } else if (is.factor(x) || is.character(x)) {
      in_rows(.list = list_wrap_x(table)(x))
    } else {
      stop("type not supproted")
    }
  })

build_table(lyt, ex_adsl)
#>                A: Drug X      B: Placebo    C: Combination
#> ----------------------------------------------------------
#> AGE                                                       
#>   Mean (sd)   33.77 (6.55)   35.43 (7.9)     35.43 (7.72) 
#>   Median           33             35              35      
#>   Min - Max     21 - 50        21 - 62         20 - 69    
#> BMRKR1                                                    
#>   Mean (sd)   5.97 (3.55)     5.7 (3.31)     5.62 (3.49)  
#>   Median          5.39           4.81            4.61     
#>   Min - Max   0.41 - 17.67   0.65 - 14.24    0.17 - 21.39 
#> BMRKR2                                                    
#>   LOW              50             45              40      
#>   MEDIUM           37             56              42      
#>   HIGH             47             33              50
library(rtables)
library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union

## for simplicity grab non-sparse subset
ADSL = ex_adsl %>% filter(RACE %in% levels(RACE)[1:3])

biomarker_ave = function(x, ...) {
     val = if(length(x) > 0) round(mean(x), 2) else "no data"
     in_rows(
        "Biomarker 1 (mean)" = rcell(val)
     )
}

basic_table() %>%
  split_cols_by("ARM") %>%
  split_cols_by("BMRKR2") %>%
  add_colcounts() %>%
  split_rows_by("RACE", split_fun = trim_levels_in_group("SEX")) %>%
  split_rows_by("SEX") %>%
  summarize_row_groups() %>%
  analyze("BMRKR1", biomarker_ave) %>%
  build_table(ADSL)
#>                                                          A: Drug X                            B: Placebo                           C: Combination           
#>                                                LOW        MEDIUM        HIGH         LOW         MEDIUM       HIGH         LOW         MEDIUM        HIGH   
#>                                               (N=45)      (N=35)       (N=46)       (N=42)       (N=48)      (N=31)       (N=40)       (N=39)       (N=47)  
#> ------------------------------------------------------------------------------------------------------------------------------------------------------------
#> ASIAN                                                                                                                                                       
#>   F                                         13 (28.9%)   9 (25.7%)   19 (41.3%)   9 (21.4%)    18 (37.5%)    9 (29%)    13 (32.5%)   9 (23.1%)    17 (36.2%)
#>     Biomarker 1 (mean)                         5.23        6.17         5.38         5.64         5.55        4.33         5.46         5.48         5.19   
#>   M                                         8 (17.8%)     7 (20%)    10 (21.7%)   12 (28.6%)   10 (20.8%)   8 (25.8%)   5 (12.5%)    11 (28.2%)    16 (34%) 
#>     Biomarker 1 (mean)                         6.77        6.06         5.54         4.9          4.98        6.81         6.53         5.47         4.98   
#>   U                                          1 (2.2%)    1 (2.9%)      0 (0%)       0 (0%)       0 (0%)     1 (3.2%)      0 (0%)      1 (2.6%)     1 (2.1%) 
#>     Biomarker 1 (mean)                         4.68         7.7       no data      no data      no data       6.97       no data       11.93         9.01   
#> BLACK OR AFRICAN AMERICAN                                                                                                                                   
#>   F                                         6 (13.3%)    3 (8.6%)    9 (19.6%)    6 (14.3%)    8 (16.7%)    2 (6.5%)    7 (17.5%)    4 (10.3%)     3 (6.4%) 
#>     Biomarker 1 (mean)                         5.01         7.2         6.79         6.15         5.26        8.57         5.72         5.76         4.58   
#>   M                                         5 (11.1%)    5 (14.3%)    2 (4.3%)     3 (7.1%)    5 (10.4%)    4 (12.9%)    4 (10%)     5 (12.8%)    5 (10.6%) 
#>     Biomarker 1 (mean)                         6.92        5.82        11.66         4.46         6.14        8.47         6.16         5.25         4.83   
#>   U                                           0 (0%)      0 (0%)       0 (0%)       0 (0%)       0 (0%)      0 (0%)      1 (2.5%)     1 (2.6%)      0 (0%)  
#>     Biomarker 1 (mean)                       no data      no data     no data      no data      no data      no data       2.79         9.82       no data  
#>   UNDIFFERENTIATED                           1 (2.2%)     0 (0%)       0 (0%)       0 (0%)       0 (0%)      0 (0%)       2 (5%)       0 (0%)       0 (0%)  
#>     Biomarker 1 (mean)                         9.48       no data     no data      no data      no data      no data       6.46       no data      no data  
#> WHITE                                                                                                                                                       
#>   F                                         6 (13.3%)     7 (20%)     4 (8.7%)    5 (11.9%)    6 (12.5%)    6 (19.4%)    6 (15%)      3 (7.7%)     2 (4.3%) 
#>     Biomarker 1 (mean)                         4.43        7.83         4.52         6.42         5.07        7.83         6.71         5.87         10.7   
#>   M                                          4 (8.9%)    3 (8.6%)     2 (4.3%)    6 (14.3%)     1 (2.1%)    1 (3.2%)      2 (5%)     5 (12.8%)     3 (6.4%) 
#>     Biomarker 1 (mean)                         5.81        7.23         1.39         4.72         4.58        12.87        2.3          5.1          5.98   
#>   U                                          1 (2.2%)     0 (0%)       0 (0%)      1 (2.4%)      0 (0%)      0 (0%)       0 (0%)       0 (0%)       0 (0%)  
#>     Biomarker 1 (mean)                         3.94       no data     no data        3.77       no data      no data     no data      no data      no data  
#> AMERICAN INDIAN OR ALASKA NATIVE                                                                                                                            
#> MULTIPLE                                                                                                                                                    
#> NATIVE HAWAIIAN OR OTHER PACIFIC ISLANDER                                                                                                                   
#> OTHER                                                                                                                                                       
#> UNKNOWN

Acknowledgements

We would like to thank everyone who has made rtables a better project by providing feedback and improving examples & vignettes. The following list of contributors is alphabetical:

Maximo Carreras, Francois Collins, Saibah Chohan, Tadeusz Lewandowski, Nick Paszty, Nina Qi, Jana Stoilova, Heng Wang, Godwin Yung

Presentations

New (Current) Layouting and Tabulation Framework (v.0.3+)

v0.1.0 and previous

Copy Link

Version

Install

install.packages('rtables')

Monthly Downloads

3,275

Version

0.5.1

License

Apache License 2.0 | file LICENSE

Issues

69

Pull Requests

0

Stars

239

Forks

51

Maintainer

Gabriel Becker

Last Published

May 21st, 2022

Functions in rtables (0.5.1)

Viewer

Dispaly an rtable object in the Viewer pane in RStudio or in a browser
VarLevelSplit-class

Split on levels within a variable
add_colcounts

Add the column population counts to the header
select_all_levels

Add Combination Levels to split
build_table

Create a table from a layout and data
EmptyColInfo

Empty table, column, split objects
as.vector,TableRow-method

convert to a vector
CellValue

Cell Value constructor
as_html

Convert an rtable object to a shiny.tag html object
[<-,VTableTree,ANY,ANY,list-method

retrieve and assign elements of a TableTree
add_overall_level

Add an virtual 'overall' level to split
analyze

Generate Rows Analyzing Variables Across Columns
in_rows

Create multiple rows in analysis or summary functions
manual_cols

Manual column declaration
horizontal_sep

Access or recursively set header-body separator for tables
do_base_split

Apply Basic Split (For Use In Custom Split Functions)
rcell

Cell value constructors
export_as_pdf

Export as PDF
matrix_form,VTableTree-method

Transform rtable to a list of matrices which can be used for outputting
row_footnotes

Referential Footnote Accessors
add_existing_table

Add an already calculated table to the layout
InstantiatedColumnInfo-class

InstantiatedColumnInfo
clayout

Column information/structure accessors
obj_name,VNodeInfo-method

Label, Name and Format accessor generics Getters and setters for basic, relatively universal attributes of "table-like" objects"
gen_args

General Argument Conventions
length,CellValue-method

Length of a Cell value
list_wrap_x

Returns a function that coerces the return values of f to a list
get_formatted_cells

get formatted cells
label_at_path

Label at Path
collect_leaves

Collect leaves of a table tree
sort_at_path

Sort substructure of a TableTree at a particular Path in the Tree.
sf_args

Split Function Arg Conventions
split_cols_by_multivar

Associate Multiple Variables with Columns
clear_indent_mods

Clear All Indent Mods from a Table
VarStaticCutSplit-class

Splits for cutting by values of a numeric variable
insert_row_at_path

Insert Row at Path
custom_split_funs

Custom Split Functions Split functions provide the work-horse for rtables's generalized partitioning. These functions accept a (sub)set of incoming data, a split object, and return 'splits' of that data.
prune_table

Recursively prune a TableTree
rrow

row
row_paths

Return List with Table Row/Col Paths
insert_rrow

[DEPRECATED] insert rrows at (before) a specific location
make_row_df

Column Layout Summary
rbindl_rtables

rbind TableTree and related objects
cbind_rtables

cbind two rtables
rheader

Create a header
remove_split_levels

Split functions
cell_values

Retrieve cell values by row and column path
export_as_txt

Export as plain text with page break symbol
tt_at_path

Get or set table elements at specified path
spl_context

spl_context within analysis and split functions .spl_context in analysis and split functions
summarize_rows

summarize_rows
ElementaryTable-class

TableTree classes
obj_avar

Row attribute accessors
split_cols_by

Declaring a column-split based on levels of a variable
AnalyzeVarSplit

Define a subset tabulation/analysis
add_overall_col

Add Overall Column
rrowl

rrowl
main_title,VTitleFooter-method

Titles and Footers
tostring

Convert an rtable object to a string
vars_in_layout

List Variables required by a pre-data table layout
tree_children

Retrieve or set the direct children of a Tree-style object
basic_table

Layout with 1 column and zero rows
compare_rtables

Compare two rtables
top_left

Top Left Material (Experimental)
ManualSplit

Manually defined split
analyze_colvars

Generate Rows Analyzing Different Variables Across Columns
constr_args

Constructor Arg Conventions
MultiVarSplit

Split between two or more different variables
append_topleft

Append a description to the 'top-left' materials for the layout
update_ref_indexing

Update footnote indexes on a built table
compat_args

Compatability Arg Conventions
content_table

Retrieve or set Content Table from a TableTree
internal_methods

combine SplitVector objects
is_rtable

Check if an object is a valid rtable
make_afun

Create custom analysis function wrapping existing function
lyt_args

Layouting Function Arg Conventions
pag_tt_indices

Pagination of a TableTree
df_to_tt

Create ElementaryTable from data.frame
trim_levels_to_map

Trim Levels to map
row_paths_summary

Print Row/Col Paths Summary
names,VTableNodeInfo-method

Names of a TableTree
no_colinfo

Exported for use in tern
nrow,VTableTree-method

Table Dimensions
LabelRow

Row classes and constructors
all_zero_or_na

Trimming and Pruning Criteria
value_formats

Value Formats
path_enriched_df

Transform TableTree object to Path-Enriched data.frame
format_rcell

Format rcell
split_cols_by_cuts

Split on static or dynamic cuts of the data
cont_n_allcols

Score functions for sorting TableTrees
simple_analysis

Default tabulation
split_rows_by

Add Rows according to levels of a variable
summarize_row_groups

Add a content row of summary counts
export_as_tsv

Create Enriched flat value table with paths
tt_to_flextable

Create a FlexTable object representing an rtables TableTree
rtables_aligns

Currently supported cell value alignments
indent_string

Indent Strings
indent

Change indentation of all rrows in an rtable
rtable

Create a Table
table_shell

Table shells
trim_rows

Trim rows from a populated table without regard for table structure
trim_zero_rows

Trim Zero Rows
table_structure

Summarize Table