Introduction to {rtables.officer}

Introduction

The rtables package provides a framework to create, tabulate, and output tables in R. Most of the design requirements for rtables have their origin in studying tables that are commonly used to report analyses from clinical trials; however, we were careful to keep rtables a general purpose toolkit.

In this vignette, we give a short introduction into creating tables with rtables and exporting them into docx files with rtables.officer.

The content of this vignette is based on the following two resources:

• The rtables useR 2020 presentation by Gabriel Becker
• rtables - A Framework For Creating Complex Structured Reporting Tables Via Multi-Level Faceted Computations.

The packages used in this vignette are rtables.officer, rtables, and dplyr:

library(rtables.officer)
library(dplyr)

Overview

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 output tables in ascii, html, and pdf formats.

The rtables.officer package is designed to support export formats related to the Microsoft Office software suite, including Microsoft Word (docx) and Microsoft PowerPoint (pptx).

For a detailed guide on getting started with rtables, please refer to this page.

Data

The data used in this vignette is a made up using random number generators. The data content is relatively simple: one row per imaginary person and one column per measurement: study arm, the country of origin, gender, handedness, age, and weight.

n <- 400

set.seed(1)

df <- tibble(
  arm = factor(sample(c("Arm A", "Arm B"), n, replace = TRUE), levels = c("Arm A", "Arm B")),
  country = factor(sample(c("CAN", "USA"), n, replace = TRUE, prob = c(.55, .45)), levels = c("CAN", "USA")),
  gender = factor(sample(c("Female", "Male"), n, replace = TRUE), levels = c("Female", "Male")),
  handed = factor(sample(c("Left", "Right"), n, prob = c(.6, .4), replace = TRUE), levels = c("Left", "Right")),
  age = rchisq(n, 30) + 10
) %>% mutate(
  weight = 35 * rnorm(n, sd = .5) + ifelse(gender == "Female", 140, 180)
)

head(df)
# # A tibble: 6 × 6
#   arm   country gender handed   age weight
#   <fct> <fct>   <fct>  <fct>  <dbl>  <dbl>
# 1 Arm A USA     Female Left    31.3   139.
# 2 Arm B CAN     Female Right   50.5   116.
# 3 Arm A USA     Male   Right   32.4   186.
# 4 Arm A USA     Male   Right   34.6   169.
# 5 Arm B USA     Female Right   43.0   160.
# 6 Arm A USA     Female Right   43.2   126.

Note that we use factor variables so that the level order is represented in the row or column order when we tabulate the information of df below.

Building a Table

The aim of this vignette is to build the following table and then use rtables.officer to export it to a docx file.

#                     Arm A                     Arm B         
#              Female        Male        Female        Male   
#              (N=96)      (N=105)       (N=92)      (N=107)  
# ————————————————————————————————————————————————————————————
# CAN        45 (46.9%)   64 (61.0%)   46 (50.0%)   62 (57.9%)
#   Left     32 (33.3%)   42 (40.0%)   26 (28.3%)   37 (34.6%)
#     mean     38.87        40.43        40.33        37.68   
#   Right    13 (13.5%)   22 (21.0%)   20 (21.7%)   25 (23.4%)
#     mean     36.64        40.19        40.16        40.65   
# USA        51 (53.1%)   41 (39.0%)   46 (50.0%)   45 (42.1%)
#   Left     34 (35.4%)   19 (18.1%)   25 (27.2%)   25 (23.4%)
#     mean     40.36        39.68        39.21        40.07   
#   Right    17 (17.7%)   22 (21.0%)   21 (22.8%)   20 (18.7%)
#     mean     36.94        39.80        38.53        39.02

First, we build the table as follows:

lyt <- basic_table(show_colcounts = TRUE) %>%
  split_cols_by("arm") %>%
  split_cols_by("gender") %>%
  split_rows_by("country") %>%
  summarize_row_groups() %>%
  split_rows_by("handed") %>%
  summarize_row_groups() %>%
  analyze("age", afun = mean, format = "xx.xx")

tbl <- build_table(lyt, df)
tbl
#                     Arm A                     Arm B         
#              Female        Male        Female        Male   
#              (N=96)      (N=105)       (N=92)      (N=107)  
# ————————————————————————————————————————————————————————————
# CAN        45 (46.9%)   64 (61.0%)   46 (50.0%)   62 (57.9%)
#   Left     32 (33.3%)   42 (40.0%)   26 (28.3%)   37 (34.6%)
#     mean     38.87        40.43        40.33        37.68   
#   Right    13 (13.5%)   22 (21.0%)   20 (21.7%)   25 (23.4%)
#     mean     36.64        40.19        40.16        40.65   
# USA        51 (53.1%)   41 (39.0%)   46 (50.0%)   45 (42.1%)
#   Left     34 (35.4%)   19 (18.1%)   25 (27.2%)   25 (23.4%)
#     mean     40.36        39.68        39.21        40.07   
#   Right    17 (17.7%)   22 (21.0%)   21 (22.8%)   20 (18.7%)
#     mean     36.94        39.80        38.53        39.02

Exporting to a docx File

Next, we will export the rtables object generated above (tbl) into a docx file, namely example.docx.

output_dir <- "." # specify here where the file should be saved
export_as_docx(tbl, file = file.path(output_dir, "example.docx"))

The export_as_docx() function used above first converts the rtables object into a flextable object and then uses the officer package to save the output to a docx file.