Skip to contents

Every layout must start with a basic table.


  title = "",
  subtitles = character(),
  main_footer = character(),
  prov_footer = character(),
  show_colcounts = FALSE,
  colcount_format = "(N=xx)",
  header_section_div = NA_character_,
  top_level_section_div = NA_character_,
  inset = 0L



single string to use as main title (main_title()). Ignored for subtables.


a vector of strings to use as subtitles (subtitles()), where every element is printed on a separate line. Ignored for subtables.


a vector of strings to use as main global (non-referential) footer materials (main_footer()), where every element is printed on a separate line.


a vector of strings to use as provenance-related global footer materials (prov_footer()), where every element is printed on a separate line.


whether column counts should be displayed in the resulting table when this layout is applied to data.


format for use when displaying the column counts. Must be 1d, or 2d where one component is a percent. See Details below.


string which will be used to divide the header from the table. See header_section_div() for the associated getter and setter. Please consider changing last element of section_div() when concatenating tables that require a divider between them.


if assigned a single character, the first (top level) split or division of the table will be highlighted by a line made of that character. See section_div for more information.


number of spaces to inset the table header, table body, referential footnotes, and main_footer, as compared to alignment of title, subtitle, and provenance footer. Defaults to 0 (no inset).


A PreDataTableLayouts object suitable for passing to further layouting functions, and to build_table().


colcount_format is ignored if show_colcounts is FALSE (the default). When show_colcounts is TRUE, and colcount_format is 2-dimensional with a percent component, the value component for the percent is always populated with 1 (i.e. 100%). 1d formats are used to render the counts exactly as they normally would be, while 2d formats which don't include a percent, and all 3d formats result in an error. Formats in the form of functions are not supported for colcount format. See formatters::list_valid_format_labels() for the list of valid format labels to select from.


  • Because percent components in colcount_format are always populated with the value 1, we can get arguably strange results, such as that individual arm columns and a combined "all patients" column all list "100%" as their percentage, even though the individual arm columns represent strict subsets of the "all patients" column.

  • Note that subtitles (subtitles()) and footers (main_footer() and prov_footer()) that span more than one line can be supplied as a character vector to maintain indentation on multiple lines.


lyt <- basic_table() %>%
  analyze("AGE", afun = mean)

tbl <- build_table(lyt, DM)
#>            all obs     
#> ———————————————————————
#> mean   34.2219101123596

lyt2 <- basic_table(
  title = "Title of table",
  subtitles = c("a number", "of subtitles"),
  main_footer = "test footer",
  prov_footer = paste(
    "test.R program, executed at",
) %>%
  split_cols_by("ARM") %>%
  analyze("AGE", mean)

tbl2 <- build_table(lyt2, DM)
#> Title of table
#> a number
#> of subtitles
#> —————————————————————————————————————————————————————————————
#>           A: Drug X          B: Placebo       C: Combination 
#> —————————————————————————————————————————————————————————————
#> mean   34.9090909090909   33.0188679245283   34.5658914728682
#> —————————————————————————————————————————————————————————————
#> test footer
#> test.R program, executed at 2024-04-15 15:06:14.552044

lyt3 <- basic_table(
  show_colcounts = TRUE,
  colcount_format = "xx. (xx.%)"
) %>%