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(),
  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(
  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"),
  bold_manual = NULL,
  border = flextable::fp_border_default(width = 0.5)
)

word_mm_to_pt(mm)

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(). See details for more information.

border

(flextable::fp_border())
border style. Defaults to flextable::fp_border_default(width = 0.5).

indent_size

(numeric(1))
if NULL, the default indent size of the table (see formatters::matrix_form() indent_size, default is 2) is used. To work with docx, any size is multiplied by 1 mm (2.83 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 formatters::main_title() string and formatters::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.

cell_margins

(numeric(1) or numeric(4))
a numeric or a vector of four numbers indicating c("left", "right", "top", "bottom"). It defaults to 0 for top and bottom, and to 0.19 mm in word pt for left and right.

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 formatters::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").

mm

(numeric(1))
the value in mm to transform to pt.

Value

A flextable object.

Details

It is possible to use some hidden values for building your own theme. In particular, tt_to_flextable sends in the following variables tbl_ncol_body = NCOL(tt) and tbl_row_class = make_row_df(tt)$node_class. These are ignored if not used in the theme. See theme_docx_default for an example on own to retrieve these values and how to use them.

Functions

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

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

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)

library(flextable)
# example code

# 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(font_size = 6))

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!
library(flextable)
# 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
)

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!