rtables (version 0.6.10)

tt_to_flextable: Create a flextable from an rtables table

Description

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,
  bold_titles = TRUE,
  footers_as_text = FALSE,
  counts_in_newline = FALSE,
  paginate = FALSE,
  fontspec = NULL,
  lpp = NULL,
  cpp = NULL,
  ...,
  colwidths = NULL,
  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", "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)

Value

A flextable object.

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() that is a classic Word output. 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.

bold_titles

(flag or integer)
defaults to TRUE for tt_to_flextable(), so the titles are bold. If it is one or more integers, those lines will be bold.

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.

fontspec

(font_spec)
a font_spec object specifying the font information to use for calculating string widths and heights, as returned by font_spec().

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. Please consider consulting the family column from systemfonts::system_fonts().

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", "top_left"). 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").

remove_internal_borders

(character)
defaults to "label_rows". Remove internal borders between rows. Currently there are no other options and can be turned off by providing any character value.

mm

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

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.

Details

Themes can also be extended when you need only a minor change from a default style. You can either add your own theme to the theme call (e.g. c(theme_docx_default(), my_theme)) or create a new theme like shown in the examples. Please pay attention to the parameters' inputs as they are relevant for this to work properly. Indeed, it is possible to use some hidden values for building your own theme (hence the need of ...). In particular, tt_to_flextable sends in the following variable: tbl_row_class = make_row_df(tt)$node_class. This is 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.

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)

if (FALSE) { # require(flextable)
library(flextable)
# example code

# rtables style
tt_to_flextable(tbl, theme = NULL)

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

# Example with multiple themes (only extending the docx default!)
my_theme <- function(x, ...) {
  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))
}
if (FALSE) { # require(flextable)
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
)

# Extending themes
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 <- border_inner(flx, part = "body", border = flextable::fp_border_default(width = 0.5))

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