| Title: | 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'). |
| Authors: | Gabriel Becker [ctb], Davide Garolini [aut] (ORCID: <https://orcid.org/0000-0002-1445-1369>), Emily de la Rua [aut] (ORCID: <https://orcid.org/0009-0000-8738-5561>), Abinaya Yogasekaram [aut] (ORCID: <https://orcid.org/0009-0005-2083-1105>), Joe Zhu [aut, cre] (ORCID: <https://orcid.org/0000-0001-7566-2787>), F. Hoffmann-La Roche AG [cph, fnd] |
| Maintainer: | Joe Zhu <[email protected]> |
| License: | Apache License 2.0 |
| Version: | 0.1.2.9001 |
| Built: | 2026-05-21 03:18:34 UTC |
| Source: | https://github.com/insightsengineering/rtables.officer |
flextable RowsModifies 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.
add_flextable_separators( ft, trailing_sep, border = officer::fp_border(width = 1, color = "grey60"), padding = 10 )add_flextable_separators( ft, trailing_sep, border = officer::fp_border(width = 1, color = "grey60"), padding = 10 )
ft |
A flextable object. |
trailing_sep |
A vector specifying separators. Its length must equal
the number of rows in the body of |
border |
The |
padding |
The amount of bottom padding (in points) to add when
|
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.
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) )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) )
Apply alignments to a flextable
apply_alignments(flx, aligns_df, part)apply_alignments(flx, aligns_df, part)
flx |
( |
aligns_df |
( |
part |
( |
a flextable object with the alignments updated.
df <- head(iris) aligns_df <- matrix(data = "right", nrow = nrow(df), ncol = ncol(df)) aligns_df[3, 3] <- "center" aligns_df[5, 2] <- "center" flx <- flextable::flextable(df) apply_alignments(flx = flx, aligns_df = aligns_df, part = "body")df <- head(iris) aligns_df <- matrix(data = "right", nrow = nrow(df), ncol = ncol(df)) aligns_df[3, 3] <- "center" aligns_df[5, 2] <- "center" flx <- flextable::flextable(df) apply_alignments(flx = flx, aligns_df = aligns_df, part = "body")
Apply manual bolding to a flextable
apply_bold_manual(flx, bold_manual)apply_bold_manual(flx, bold_manual)
flx |
( |
bold_manual |
( |
a flextable object with the bolding updated.
df <- head(iris) flx <- flextable::flextable(df) special_bold <- list( "header" = list("i" = 1, "j" = c(1, 3)), "body" = list("i" = c(1, 2), "j" = 1) ) apply_bold_manual(flx, special_bold)df <- head(iris) flx <- flextable::flextable(df) special_bold <- list( "header" = list("i" = 1, "j" = c(1, 3)), "body" = list("i" = c(1, 2), "j" = 1) ) apply_bold_manual(flx, special_bold)
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.
export_as_docx( tt, file, add_page_break = FALSE, add_template_page_numbers = TRUE, 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()export_as_docx( tt, file, add_page_break = FALSE, add_template_page_numbers = TRUE, 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()
tt |
( |
file |
( |
add_page_break |
( |
add_template_page_numbers |
( |
titles_as_header |
( |
integrate_footers |
( |
section_properties |
( |
doc_metadata |
( |
template_file |
( |
... |
( |
page_size |
( |
orientation |
( |
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.
No return value, called for side effects
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.
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.
tt_to_flextable(), extract_font_and_size_from_flx()
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(tmpdir = tempdir(check = TRUE), fileext = ".docx") export_as_docx(tbl, file = tf, section_properties = section_properties_default(orientation = "landscape") )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(tmpdir = tempdir(check = TRUE), fileext = ".docx") export_as_docx(tbl, file = tf, section_properties = section_properties_default(orientation = "landscape") )
Extract font and size from a flextable
extract_font_and_size_from_flx(flx)extract_font_and_size_from_flx(flx)
flx |
( |
a named list with 2 elements:
ftp: contains font name, size and other text attributes from the title.
ftp_footer: contains font name, size and other text attributes from the footer.
df <- head(iris) flx <- flextable::flextable(df) extract_font_and_size_from_flx(flx)df <- head(iris) flx <- flextable::flextable(df) extract_font_and_size_from_flx(flx)
flextable from an rtables tablePrincipally 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.
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)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)
tt |
( |
theme |
( |
border |
( |
indent_size |
( |
titles_as_header |
( |
bold_titles |
( |
integrate_footers |
( |
counts_in_newline |
( |
paginate |
( |
fontspec |
( |
lpp |
( |
cpp |
( |
... |
( |
colwidths |
( |
tf_wrap |
( |
max_width |
( |
total_page_height |
( |
total_page_width |
( |
autofit_to_page |
( |
font |
( |
font_size |
( |
cell_margins |
( |
bold |
( |
bold_manual |
(named |
remove_internal_borders |
( |
mm |
( |
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.
A flextable object.
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.
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.
export_as_docx(), apply_alignments()
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(tmpdir = tempdir(check = TRUE), fileext = ".html") )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(tmpdir = tempdir(check = TRUE), fileext = ".html") )