--- title: "Customizing Appearance" author: "Davide Garolini, Abinaya Yogasekaram, and Gabriel Becker" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Customizing Appearance} %\VignetteEncoding{UTF-8} %\VignetteEngine{knitr::rmarkdown} editor_options: chunk_output_type: console --- ```{r, include = FALSE} suggested_dependent_pkgs <- c("dplyr") knitr::opts_chunk$set( collapse = TRUE, comment = "#>", eval = all(vapply( suggested_dependent_pkgs, requireNamespace, logical(1), quietly = TRUE )) ) ``` ```{r, echo=FALSE} knitr::opts_chunk$set(comment = "#") ``` ```{css, echo=FALSE} .reveal .r code { white-space: pre; } ``` ## Customizing Appearance In this vignette, we describe the various ways we can modify and customize the appearance of `rtables`. Loading the package: ```{r, message=FALSE} library(rtables) library(dplyr) ``` ### Rows and cell values alignments It is possible to align the content by assigning `"left"`, `"center"` (default), and `"right"` to `.aligns` and `align` arguments in `in_rows()` and `rcell()`, respectively. It is also possible to use `decimal`, `dec_right`, and `dec_left` for decimal alignments. The first takes all numerical values and aligns the decimal character `.` in every value of the column that has `align = "decimal"`. Also numeric without decimal values are aligned according to an imaginary `.` if specified as such. `dec_left` and `dec_right` behave similarly, with the difference that if the column present empty spaces at left or right, it pushes values towards left or right taking the one value that has most decimal characters, if right, or non-decimal values if left. For more details, please read the related documentation page `help("decimal_align")`. Please consider using `?in_rows` and `?rcell` for further clarifications on the two arguments, and use `formatters::list_valid_aligns()` to see all available alignment options. In the following we show two simplified examples that use `align` and `.aligns`, respectively. ```{r} # In rcell we use align. lyt <- basic_table() %>% analyze("AGE", function(x) { in_rows( left = rcell("l", align = "left"), right = rcell("r", align = "right"), center = rcell("c", align = "center") ) }) tbl <- build_table(lyt, DM) tbl ``` ```{r} # In in_rows, we use .aligns. This can either set the general value or the # single values (see NB). lyt2 <- basic_table() %>% analyze("AGE", function(x) { in_rows( left = rcell("l"), right = rcell("r"), center = rcell("c"), .aligns = c("right") ) # NB: .aligns = c("right", "left", "center") }) tbl2 <- build_table(lyt2, DM) tbl2 ``` These concepts can be well applied to any clinical table as shown in the following, more complex, example. ```{r} lyt3 <- basic_table() %>% split_cols_by("ARM") %>% split_rows_by("SEX") %>% analyze(c("AGE", "STRATA1"), function(x) { if (is.numeric(x)) { in_rows( "mean" = rcell(mean(x)), "sd" = rcell(sd(x)), .formats = c("xx.x"), .aligns = "left" ) } else if (is.factor(x)) { rcell(length(unique(x)), align = "right") } else { stop("Unsupported type") } }, show_labels = "visible", na_str = "NE") tbl3 <- build_table(lyt3, ex_adsl) tbl3 ``` ### Top-left Materials The sequence of strings printed in the area between the column header display and the first row label \emph{top left material} can be modified during pre-processing using label position argument in row splits `split_rows_by`, with the `append_topleft` function, and during post-processing using the `top_left()` function. Note: Indenting is automatically added \emph{only in the case of} `label_pos = "topleft"`. Within the layout initializer: ```{r} lyt <- basic_table() %>% split_cols_by("ARM") %>% split_rows_by("STRATA1") %>% analyze("AGE") %>% append_topleft("New top_left material here") build_table(lyt, DM) ``` Specify label position using the `split_rows` function. Notice the position of `STRATA1` and `SEX`. ```{r} lyt <- basic_table() %>% split_cols_by("ARM") %>% split_rows_by("STRATA1", label_pos = "topleft") %>% split_rows_by("SEX", label_pos = "topleft") %>% analyze("AGE") build_table(lyt, DM) ``` Post-processing using the `top_left()` function: ```{r} lyt <- basic_table() %>% split_cols_by("ARM") %>% split_rows_by("SEX") %>% analyze(c("AGE", "STRATA1"), function(x) { if (is.numeric(x)) { in_rows( "mean" = rcell(mean(x)), "sd" = rcell(sd(x)), .formats = c("xx.x"), .aligns = "left" ) } else if (is.factor(x)) { rcell(length(unique(x)), align = "right") } else { stop("Unsupported type") } }, show_labels = "visible", na_str = "NE") %>% build_table(ex_adsl) # Adding top-left material top_left(lyt) <- "New top-left material here" lyt ``` ### Table Inset Table title, table body, referential footnotes and and main footers can be inset from the left alignment of the titles and provenance footer materials. This can be modified within the layout initializer `basic_table()` using the `inset` argument or during post-processing with `table_inset()`. Using the layout initializer: ```{r} lyt <- basic_table(inset = 5) %>% analyze("AGE") build_table(lyt, DM) ``` Using the post-processing function: Without inset - ```{r} lyt <- basic_table() %>% analyze("AGE") tbl <- build_table(lyt, DM) tbl ``` With an inset of 5 characters - ```{r} table_inset(tbl) <- 5 tbl ``` Below is an example with a table produced for clinical data. Compare the inset of the table and main footer between the two tables. Without inset - ```{r} analysisfun <- function(x, ...) { in_rows( row1 = 5, row2 = c(1, 2), .row_footnotes = list(row1 = "row 1 rfn"), .cell_footnotes = list(row2 = "row 2 cfn") ) } lyt <- basic_table( title = "Title says Whaaaat", subtitles = "Oh, ok.", main_footer = "ha HA! Footer!", prov_footer = "provenaaaaance" ) %>% split_cols_by("ARM") %>% analyze("AGE", afun = analysisfun) result <- build_table(lyt, ex_adsl) result ``` With inset - Notice, the inset does not apply to any title materials (main title, subtitles, page titles), or provenance footer materials. Inset settings is applied to top-left materials, referential footnotes main footer materials and any horizontal dividers. ```{r} table_inset(result) <- 5 result ``` ### Horizontal Separation A character value can be specified to modify the horizontal separation between column headers and the table. Horizontal separation applies when: 1. separating title + subtitles from the column labels + top left materials, 2. column labels + top left material from row labels + cells, 3. row labels + cells from footer content, and 4. Referential footnotes from main + provenance content \emph{only if} there would be something on both sides of the divider. Below, we replace the default line with "=". ```{r} tbl <- basic_table() %>% split_cols_by("Species") %>% add_colcounts() %>% analyze(c("Sepal.Length", "Petal.Width"), function(x) { in_rows( mean_sd = c(mean(x), sd(x)), var = var(x), min_max = range(x), .formats = c("xx.xx (xx.xx)", "xx.xxx", "xx.x - xx.x"), .labels = c("Mean (sd)", "Variance", "Min - Max") ) }) %>% build_table(iris, hsep = "=") tbl ``` ### Section Dividers A character value can be specified as a section divider which succeed every group defined by a split instruction. Note, a trailing divider at the end of the table is never printed. Below, a "+" is repeated and used as a section divider. ```{r} lyt <- basic_table() %>% split_cols_by("Species") %>% analyze(head(names(iris), -1), afun = function(x) { list( "mean / sd" = rcell(c(mean(x), sd(x)), format = "xx.xx (xx.xx)"), "range" = rcell(diff(range(x)), format = "xx.xx") ) }, section_div = "+") build_table(lyt, iris) ``` Section dividers can be set to " " to create a blank line. ```{r} lyt <- basic_table() %>% split_cols_by("Species") %>% analyze(head(names(iris), -1), afun = function(x) { list( "mean / sd" = rcell(c(mean(x), sd(x)), format = "xx.xx (xx.xx)"), "range" = rcell(diff(range(x)), format = "xx.xx") ) }, section_div = " ") build_table(lyt, iris) ``` Separation characters can be specified for different row splits. However, only one will be printed if they "pile up" next to each other. ```{r} lyt <- basic_table() %>% split_cols_by("ARM") %>% split_rows_by("RACE", section_div = "=") %>% split_rows_by("STRATA1", section_div = "~") %>% analyze("AGE", mean, var_labels = "Age", format = "xx.xx") build_table(lyt, DM) ``` ### Indent Modifier Tables by default have indenting at each level of splitting. A custom indent value can be supplied with the `indent_mod` argument within a split function to modify this default. Compare the indenting of the tables below: Default Indent - ```{r} basic_table( title = "Study XXXXXXXX", subtitles = c("subtitle YYYYYYYYYY", "subtitle2 ZZZZZZZZZ"), main_footer = "Analysis was done using cool methods that are correct", prov_footer = "file: /path/to/stuff/that/lives/there HASH:1ac41b242a" ) %>% split_cols_by("ARM") %>% split_rows_by("SEX") %>% split_rows_by("STRATA1") %>% analyze("AGE", mean, format = "xx.x") %>% build_table(DM) ``` Modified indent - ```{r} basic_table( title = "Study XXXXXXXX", subtitles = c("subtitle YYYYYYYYYY", "subtitle2 ZZZZZZZZZ"), main_footer = "Analysis was done using cool methods that are correct", prov_footer = "file: /path/to/stuff/that/lives/there HASH:1ac41b242a" ) %>% split_cols_by("ARM") %>% split_rows_by("SEX", indent_mod = 3) %>% split_rows_by("STRATA1", indent_mod = 5) %>% analyze("AGE", mean, format = "xx.x") %>% build_table(DM) ``` ### Variable Label Visibility With split instructions, visibility of the label for the variable being split can be modified to `visible`, `hidden` and `topleft` with the `show_labels` argument, `label_pos` argument, and `child_labels` argument where applicable. Note: this is NOT the name of the levels contained in the variable. For analyze calls, \code{default} indicates that the variable should be visible only if multiple variables are analyzed at the same level of nesting. Visibility of labels for the groups generated by a split can also be modified using the `child_label` argument with a split call. The `child_label` argument can force labels to be visible in addition to content rows but we cannot hide or move the content rows. Notice the placement of the "AGE" label in this example: ```{r} lyt <- basic_table(show_colcounts = TRUE) %>% split_cols_by(var = "ARM") %>% split_rows_by("SEX", split_fun = drop_split_levels, child_labels = "visible") %>% split_rows_by("STRATA1") %>% analyze("AGE", mean, show_labels = "default") build_table(lyt, DM) ``` When set to default, the label `AGE` is not repeated since there is only one variable being analyzed at the same level of nesting. Override this by setting the `show_labels` argument as "visible". ```{r} lyt2 <- basic_table(show_colcounts = TRUE) %>% split_cols_by(var = "ARM") %>% split_rows_by("SEX", split_fun = drop_split_levels, child_labels = "hidden") %>% split_rows_by("STRATA1") %>% analyze("AGE", mean, show_labels = "visible") build_table(lyt2, DM) ``` Below is an example using the `label_pos` argument for modifying label visibility: Label order will mirror the order of `split_rows_by` calls. If the labels of any subgroups should be hidden, the `label_pos` argument should be set to hidden. "SEX" label position is hidden - ```{r} basic_table( title = "Study XXXXXXXX", subtitles = c("subtitle YYYYYYYYYY", "subtitle2 ZZZZZZZZZ"), main_footer = "Analysis was done using cool methods that are correct", prov_footer = "file: /path/to/stuff/that/lives/there HASH:1ac41b242a" ) %>% split_cols_by("ARM") %>% split_rows_by("SEX", split_fun = drop_split_levels, label_pos = "visible") %>% split_rows_by("STRATA1", label_pos = "hidden") %>% analyze("AGE", mean, format = "xx.x") %>% build_table(DM) ``` "SEX" label position is with the top-left materials - ```{r} basic_table( title = "Study XXXXXXXX", subtitles = c("subtitle YYYYYYYYYY", "subtitle2 ZZZZZZZZZ"), main_footer = "Analysis was done using cool methods that are correct", prov_footer = "file: /path/to/stuff/that/lives/there HASH:1ac41b242a" ) %>% split_cols_by("ARM") %>% split_rows_by("SEX", split_fun = drop_split_levels, label_pos = "topleft") %>% split_rows_by("STRATA1", label_pos = "hidden") %>% analyze("AGE", mean, format = "xx.x") %>% build_table(DM) ``` ### Cell, Label, and Annotation Wrapping An `rtable` can be rendered with a customized width by setting custom rendering widths for cell contents, row labels, and titles/footers. This is demonstrated using the sample data and table below. In this section we aim to render this table with a reduced width since the table has very wide contents in several cells, labels, and titles/footers. ```{r} trimmed_data <- ex_adsl %>% filter(SEX %in% c("M", "F")) %>% filter(RACE %in% levels(RACE)[1:2]) levels(trimmed_data$ARM)[1] <- "Incredibly long column name to be wrapped" levels(trimmed_data$ARM)[2] <- "This_column_name_should_be_split_somewhere" wide_tbl <- basic_table( title = "Title that is too long and also needs to be wrapped to a smaller width", subtitles = "Subtitle that is also long and also needs to be wrapped to a smaller width", main_footer = "Footnote that is wider than expected for this table.", prov_footer = "Provenance footer material that is also wider than expected for this table." ) %>% split_cols_by("ARM") %>% split_rows_by("RACE", split_fun = drop_split_levels) %>% analyze( c("AGE", "EOSDY"), na_str = "Very long cell contents to_be_wrapped_and_splitted", inclNAs = TRUE ) %>% build_table(trimmed_data) wide_tbl ``` In the following sections we will use the `toString()` function to render the table in string form. This resulting string representation is ready to be printed or written to a plain text file, but we will use the `strsplit()` function in combination with the `matrix()` function to preview the rendered wrapped table in matrix form within this vignette. #### Cell & Label Wrapping The width of a rendered table can be customized by wrapping column widths. This is done by setting custom width values via the `widths` argument of the `toString()` function. The length of the vector passed to the `widths` argument must be equal to the total number of columns in the table, including the row labels column, with each value of the vector corresponding to the maximum width (in characters) allowed in each column, from left to right. Similarly, wrapping can be applied when exporting a table via one of the four `export_as_*` functions and when implementing pagination via the `paginate_table()` function from the `rtables` package. In these cases, the rendered column widths are set using the `colwidths` argument which takes input in the same format as the `widths` argument of `toString()`. For example, `wide_tbl` has four columns (1 row label column and 3 content columns) which we will set the widths of below to use in the rendered table. We set the width of the row label column to 10 characters and the widths of each of the 3 content columns to 8 characters. Any words longer than the specified width are broken and continued on the following line. By default there are 3 spaces separating each of the columns in the rendered table but this can be customized via the `col_gap` argument to `toString()` if further width customization is desired. ```{r} result_wrap_cells <- toString(wide_tbl, widths = c(10, 8, 8, 8)) matrix_wrap_cells <- matrix(strsplit(result_wrap_cells, "\n")[[1]], ncol = 1) matrix_wrap_cells ``` In the resulting output we can see that the table has been correctly rendered using wrapping with a total width of 43 characters, but that the titles and footers remain wider than the rendered table. #### Title & Footer Wrapping In addition to wrapping column widths, titles and footers can be wrapped by setting `tf_wrap = TRUE` in `toString()` and setting the `max_width` argument of `toString()` to the maximum width (in characters) allowed for titles/footers. The four `export_as_*` functions and `paginate_table()` can also wrap titles/footers by setting the same two arguments. In the following code, we set `max_width = 43` so that the rendered table and all of its annotations have a maximum width of 43 characters. ```{r} result_wrap_cells_tf <- toString( wide_tbl, widths = c(10, 8, 8, 8), tf_wrap = TRUE, max_width = 43 ) matrix_wrap_cells_tf <- matrix(strsplit(result_wrap_cells_tf, "\n")[[1]], ncol = 1) matrix_wrap_cells_tf ```