Skip to contents

Create a flextable from an rtables table

Source: R/tt_export.R
tt_to_flextable.Rd

Principally used for export (export_as_docx()), this function produces a flextable from an rtables table. If theme = NULL, rtables-like style will be used. Otherwise, theme_docx_default() will produce a .docx-friendly table.

Usage

tt_to_flextable(
  tt,
  theme = theme_docx_default(tt),
  border = flextable::fp_border_default(width = 0.5),
  indent_size = NULL,
  titles_as_header = TRUE,
  footers_as_text = FALSE,
  counts_in_newline = FALSE,
  paginate = FALSE,
  lpp = NULL,
  cpp = NULL,
  ...,
  colwidths = propose_column_widths(matrix_form(tt, indent_rownames = TRUE)),
  tf_wrap = !is.null(cpp),
  max_width = cpp,
  total_width = 10
)

theme_docx_default(
  tt = NULL,
  font = "Arial",
  font_size = 9,
  bold = c("header", "content_rows", "label_rows"),
  bold_manual = NULL,
  border = flextable::fp_border_default(width = 0.5)
)

Arguments

tt

(TableTree or related class)
a TableTree object representing a populated table.

theme

(function or NULL)
A theme function that is designed internally as a function of a flextable object to change its layout and style. If NULL, it will produce a table similar to rtables default. Defaults to theme_docx_default(tt).

border

(officer border object)
defaults to officer::fp_border(width = 0.5).

indent_size

(integer(1))
if NULL, the default indent size of the table (see matrix_form() indent_size) is used. To work with docx, any size is multiplied by 2 mm (5.67 pt) by default.

titles_as_header

(flag)
defaults to TRUE for tt_to_flextable(), so the table is self-contained as it makes additional header rows for main_title() string and subtitles() character vector (one per element). FALSE is suggested for export_as_docx(). This adds titles and subtitles as a text paragraph above the table. The same style is applied.

footers_as_text

(flag)
defaults to FALSE for tt_to_flextable(), so the table is self-contained with the flextable definition of footnotes. TRUE is used for export_as_docx() to add the footers as a new paragraph after the table. The same style is applied, but with a smaller font.

counts_in_newline

(flag)
defaults to FALSE. In rtables text printing (formatters::toString()), the column counts, i.e. (N=xx), are always on a new line. For docx exports it could be necessary to print it on the same line.

paginate

(flag)
when exporting .docx documents using export_as_docx, we suggest relying on the Microsoft Word pagination system. If TRUE, this option splits tt into different "pages" as multiple flextables. Cooperation between the two mechanisms is not guaranteed. Defaults to FALSE.

lpp

(numeric(1))
maximum lines per page including (re)printed header and context rows.

cpp

(numeric(1) or NULL)
width (in characters) of the pages for horizontal pagination. NA (the default) indicates cpp should be inferred from the page size; NULL indicates no horizontal pagination should be done regardless of page size.

...

additional parameters passed to methods or tabulation functions.

colwidths

(numeric)
a vector of column widths for use in vertical pagination.

tf_wrap

(flag)
whether the text for title, subtitles, and footnotes should be wrapped.

max_width

(integer(1), string or NULL)
width that title and footer (including footnotes) materials should be word-wrapped to. If NULL, it is set to the current print width of the session (getOption("width")). If set to "auto", the width of the table (plus any table inset) is used. Parameter is ignored if tf_wrap = FALSE.

total_width

(numeric(1))
total width (in inches) for the resulting flextable(s). Defaults to 10.

font

(string)
defaults to "Arial". If the font is not available, flextable default is used.

font_size

(integer(1))
font size. Defaults to 9.

bold

(character)
parts of the table text that should be in bold. Can be any combination of c("header", "content_rows", "label_rows"). The first one renders all column names bold (not topleft content). The second and third option use make_row_df() to render content or/and label rows as bold.

bold_manual

(named list or NULL)
list of index lists. See example for needed structure. Accepted groupings/names are c("header", "body").

Value

A flextable object.

Functions

See also

export_as_docx()

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)
# rtables style
tt_to_flextable(tbl, theme = NULL)

Title says Whaaaat
Oh, ok.
A: Drug X
B: Placebo
C: Combination
row1 {1}
5
5
5
row2
1, 2 {2}
1, 2 {2}
1, 2 {2}
{1} - row 1 - row footnote
{2} - row 2 - cell footnote
ha HA! Footer!

tt_to_flextable(tbl, theme = theme_docx_default(tbl, font_size = 7))

Title says Whaaaat
Oh, ok.
A: Drug X
B: Placebo
C: Combination
row1 {1}
5
5
5
row2
1, 2 {2}
1, 2 {2}
1, 2 {2}
{1} - row 1 - row footnote
{2} - row 2 - cell footnote
ha HA! Footer!

# 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(tbl,
  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
)

Title says Whaaaat
Oh, ok.
A: Drug X
B: Placebo
C: Combination
row1 {1}
5
5
5
row2
1, 2 {2}
1, 2 {2}
1, 2 {2}
{1} - row 1 - row footnote
{2} - row 2 - cell footnote
ha HA! Footer!