Title:	Exporting Tools for 'rtables'
Version:	0.1.0
Date:	2025-04-17
Description:	Designed to create and display complex tables with R, the 'rtables' R package allows cells in an 'rtables' object to contain any high-dimensional data structure, which can then be displayed with cell-specific formatting instructions. Additionally, the 'rtables.officer' package supports export formats related to the Microsoft Office software suite, including Microsoft Word ('docx') and Microsoft PowerPoint ('pptx').
License:	Apache License 2.0
URL:	https://github.com/insightsengineering/rtables.officer, https://insightsengineering.github.io/rtables.officer/
BugReports:	https://github.com/insightsengineering/rtables.officer/issues
Depends:	formatters (≥ 0.5.11), magrittr (≥ 1.5), methods, R (≥ 2.10), rlistings (≥ 0.2.11), rtables (≥ 0.6.12)
Imports:	checkmate (≥ 2.1.0), flextable (≥ 0.9.6), lifecycle (≥ 0.2.0), officer (≥ 0.6.6), stats, stringi (≥ 1.6)
Suggests:	broom (≥ 1.0.5), car (≥ 3.0-13), dplyr (≥ 1.0.5), knitr (≥ 1.42), r2rtf (≥ 0.3.2), rmarkdown (≥ 2.23), survival (≥ 3.3-1), tern (≥ 0.9.7), testthat (≥ 3.0.4), tibble (≥ 3.2.1), tidyr (≥ 1.1.3), withr (≥ 2.0.0), xml2 (≥ 1.1.0)
VignetteBuilder:	knitr, rmarkdown
Config/Needs/verdepcheck:	insightsengineering/formatters, insightsengineering/rtables, tidyverse/magrittr, mllg/checkmate, rstudio/htmltools, gagolews/stringi, tidymodels/broom, cran/car, tidyverse/dplyr, davidgohel/flextable, yihui/knitr, r-lib/lifecycle, davidgohel/officer, Merck/r2rtf, rstudio/rmarkdown, therneau/survival, r-lib/testthat, tidyverse/tibble, tidyverse/tidyr, r-lib/withr, r-lib/xml2
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.2
Collate:	'add_flextable_separators.R' 'as_flextable.R' 'export_as_docx.R' 'package.R' 'theme_defaults.R'
NeedsCompilation:	no
Packaged:	2025-04-22 08:51:58 UTC; melkiades
Author:	Gabriel Becker [ctb], Davide Garolini [aut], Emily de la Rua [aut], Abinaya Yogasekaram [aut], Joe Zhu [aut, cre], F. Hoffmann-La Roche AG [cph, fnd]
Maintainer:	Joe Zhu <joe.zhu@roche.com>
Repository:	CRAN
Date/Publication:	2025-04-22 09:40:02 UTC

rtables.officer: Exporting Tools for 'rtables'

Description

Designed to create and display complex tables with R, the 'rtables' R package allows cells in an 'rtables' object to contain any high-dimensional data structure, which can then be displayed with cell-specific formatting instructions. Additionally, the 'rtables.officer' package supports export formats related to the Microsoft Office software suite, including Microsoft Word ('docx') and Microsoft PowerPoint ('pptx').

Author(s)

Maintainer: Joe Zhu joe.zhu@roche.com (ORCID)

Authors:

• Davide Garolini davide.garolini@roche.com (ORCID)

• Emily de la Rua emily.de_la_rua@contractors.roche.com (ORCID)

• Abinaya Yogasekaram abinaya.yogasekaram@contractors.roche.com (ORCID)

Other contributors:

• Gabriel Becker gabembecker@gmail.com [contributor]

• F. Hoffmann-La Roche AG [copyright holder, funder]

See Also

Useful links:

• https://github.com/insightsengineering/rtables.officer

• https://insightsengineering.github.io/rtables.officer/

• Report bugs at https://github.com/insightsengineering/rtables.officer/issues

Add Conditional Separators (horizontal line or padding) to flextable Rows

Description

Modifies an existing flextable object by adding visual separators (horizontal lines or bottom padding) after specific rows based on a control vector, without changing the table's row count.

Usage

add_flextable_separators(
  ft,
  trailing_sep,
  border = officer::fp_border(width = 1, color = "grey60"),
  padding = 10
)

Arguments

Value

The modified flextable object, or the original ft if all trailing_sep values are NA. Throws an error for invalid inputs or invalid characters in trailing_sep.

Examples

content <- data.frame(
  USUBJID = c("S1", "S1", "S1", "S2", "S2", "S2", "S3"),
  ARM = c("A", "A", "B", "A", "A", "B", "A"),
  VAL = round(rnorm(7), 2)
)
ft <- flextable::as_flextable(content)
ft <- flextable::theme_booktabs(ft)

# Define separators: line, space, NA, line, space, NA, NA
sep_ctrl <- c("-", " ", NA, "-", " ", NA, NA)

ft_modified <- add_flextable_separators(ft, sep_ctrl)
print(ft_modified)

# Example: All NA - should return original ft
ft_all_na <- add_flextable_separators(ft, rep(NA, 7))
identical(ft, ft_all_na) # Should be TRUE

# Example: Invalid character - should throw error
tryCatch(
  add_flextable_separators(ft, c("-", "x", NA, "-", " ", NA, NA)),
  error = function(e) print(e)
)

Export to a Word document

Description

From an rtables table, produce a self-contained Word document or attach it to a template Word file (template_file). This function is based on the tt_to_flextable() transformer and the officer package.

Usage

export_as_docx(
  tt,
  file,
  add_page_break = FALSE,
  titles_as_header = TRUE,
  integrate_footers = TRUE,
  section_properties = section_properties_default(),
  doc_metadata = NULL,
  template_file = NULL,
  ...
)

section_properties_default(
  page_size = c("letter", "A4"),
  orientation = c("portrait", "landscape")
)

margins_potrait()

margins_landscape()

Arguments

Details

Pagination Behavior for Titles and Footers (this behavior is experimental at the moment):

The rendering of titles and footers interacts with table pagination as follows:

• Titles: When titles_as_header = TRUE (default), the integrated title header rows typically repeat at the top of each new page if the table spans multiple pages. Setting titles_as_header = FALSE renders titles as a separate paragraph only once before the table begins.

• Footers: Regardless of the integrate_footers setting, footers appear only once. Integrated footnotes (integrate_footers = TRUE) appear at the very end of the complete table, and separate text paragraphs (integrate_footers = FALSE) appear after the complete table. Footers do not repeat on each page.

Value

No return value, called for side effects

Functions

• section_properties_default(): Helper function that defines standard portrait properties for tables.

• margins_potrait(): Helper function that defines standard portrait margins for tables.

• margins_landscape(): Helper function that defines standard landscape margins for tables.

Note

export_as_docx() has few customization options available. If you require specific formats and details, we suggest that you use tt_to_flextable() prior to export_as_docx(). If the table is modified first using tt_to_flextable(), the titles_as_header and integrate_footers parameters must be re-specified.

See Also

tt_to_flextable()

Examples

lyt <- basic_table() %>%
  split_cols_by("ARM") %>%
  analyze(c("AGE", "BMRKR2", "COUNTRY"))

tbl <- build_table(lyt, ex_adsl)

# See how the section_properties_portrait() function is built for customization
tf <- tempfile(fileext = ".docx")
export_as_docx(tbl,
  file = tf,
  section_properties = section_properties_default(orientation = "landscape")
)

Create a flextable from an rtables table

Description

Principally used within export_as_docx(), this function produces a flextable from an rtables table. If theme = theme_docx_default() (default), a .docx-friendly table will be produced. If theme = NULL, the table will be produced in an rtables-like style.

Usage

tt_to_flextable(
  tt,
  theme = theme_docx_default(),
  border = flextable::fp_border_default(width = 0.5),
  indent_size = NULL,
  titles_as_header = TRUE,
  bold_titles = TRUE,
  integrate_footers = TRUE,
  counts_in_newline = FALSE,
  paginate = FALSE,
  fontspec = NULL,
  lpp = NULL,
  cpp = NULL,
  ...,
  colwidths = NULL,
  tf_wrap = !is.null(cpp),
  max_width = cpp,
  total_page_height = 10,
  total_page_width = 10,
  autofit_to_page = TRUE
)

theme_docx_default(
  font = "Arial",
  font_size = 9,
  cell_margins = c(word_mm_to_pt(1.9), word_mm_to_pt(1.9), 0, 0),
  bold = c("header", "content_rows", "label_rows", "top_left"),
  bold_manual = NULL,
  border = flextable::fp_border_default(width = 0.5)
)

theme_html_default(
  font = "Courier",
  font_size = 9,
  cell_margins = 0.2,
  remove_internal_borders = "label_rows",
  border = flextable::fp_border_default(width = 1, color = "black")
)

word_mm_to_pt(mm)

Arguments

Details

If you would like to make a minor change to a pre-existing style, this can be done by extending themes. You can do this by either adding your own theme to the theme call (e.g. theme = c(theme_docx_default(), my_theme)) or creating a new theme as shown in the examples below. Please pay close attention to the parameters' inputs.

It is possible to use some hidden values to build your own theme (hence the need for the ... parameter). In particular, tt_to_flextable() uses the following variable: tbl_row_class = rtables::make_row_df(tt)$node_class. This is ignored if not used in the theme. See theme_docx_default() for an example on how to retrieve and use these values.

Value

A flextable object.

Functions

• theme_docx_default(): Main theme function for export_as_docx().

• theme_html_default(): Theme function for html outputs.

• word_mm_to_pt(): Padding helper functions to transform mm to pt.

Note

Currently cpp, tf_wrap, and max_width are only used in pagination and should be used cautiously if used in combination with colwidths and autofit_to_page. If issues arise, please raise an issue on GitHub or communicate this to the package maintainers directly.

See Also

export_as_docx()

Examples

analysisfun <- function(x, ...) {
  in_rows(
    row1 = 5,
    row2 = c(1, 2),
    .row_footnotes = list(row1 = "row 1 - row footnote"),
    .cell_footnotes = list(row2 = "row 2 - cell footnote")
  )
}

lyt <- basic_table(
  title = "Title says Whaaaat", subtitles = "Oh, ok.",
  main_footer = "ha HA! Footer!"
) %>%
  split_cols_by("ARM") %>%
  analyze("AGE", afun = analysisfun)

tbl <- build_table(lyt, ex_adsl)

# Example 1: rtables style ---------------------------------------------------
tt_to_flextable(tbl, theme = NULL)

# Example 2: docx style ------------------------------------------------------
tt_to_flextable(tbl, theme = theme_docx_default(font_size = 6))

# Example 3: Extending the docx theme ----------------------------------------
my_theme <- function(x, ...) {
  flextable::border_inner(x, part = "body", border = flextable::fp_border_default(width = 0.5))
}
flx <- tt_to_flextable(tbl, theme = c(theme_docx_default(), my_theme))

# Example 4: Creating a custom theme -----------------------------------------
special_bold <- list(
  "header" = list("i" = 1, "j" = c(1, 3)),
  "body" = list("i" = c(1, 2), "j" = 1)
)
custom_theme <- theme_docx_default(
  font_size = 10,
  font = "Brush Script MT",
  border = flextable::fp_border_default(color = "pink", width = 2),
  bold = NULL,
  bold_manual = special_bold
)
tt_to_flextable(tbl,
  border = flextable::fp_border_default(color = "pink", width = 2),
  theme = custom_theme
)

# Example 5: Extending the docx theme ----------------------------------------
my_theme <- function(font_size = 6) { # here can pass additional arguments for default theme
  function(flx, ...) {
    # First apply theme_docx_default
    flx <- theme_docx_default(font_size = font_size)(flx, ...)

    # Then apply additional styling
    flx <- flextable::border_inner(flx,
      part = "body",
      border = flextable::fp_border_default(width = 0.5)
    )

    return(flx)
  }
}
flx <- tt_to_flextable(tbl, theme = my_theme())

# html theme

# Define a layout for the table
lyt <- basic_table() %>%
  # Split columns by the "ARM" variable
  split_cols_by("ARM") %>%
  # Analyze the "AGE", "BMRKR2", and "COUNTRY" variables
  analyze(c("AGE", "BMRKR2", "COUNTRY"))

# Build the table using the defined layout and example data 'ex_adsl'
tbl <- build_table(lyt, ex_adsl)

# Convert the table to a flextable object suitable for HTML,
# applying the default HTML theme and setting the orientation to landscape
tbl_html <- tt_to_flextable(
  tbl,
  theme = theme_html_default(),
  section_properties = section_properties_default(orientation = "landscape")
)

# Save the flextable as an HTML file named "test.html"
flextable::save_as_html(tbl_html, path = tempfile(fileext = ".html"))