# Introduction to {rtables.officer}

#### Davide Garolini, Emily de la Rua and Joe Zhu

#### 2025-01-17

## 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.