value_formats addition to vignette and docs

R/tree_accessors.R

@@ -1173,18 +1173,22 @@ setMethod("content_na_str<-", "Split", function(obj, value) {
 #' Returns a matrix of formats for the cells in a table
 #' @param obj A table or row object.
 #' @param default `FormatSpec`.
-#' @export
+#'
 #' @return Matrix (storage mode list) containing the effective format for each
 #' cell position in the table (including 'virtual' cells implied by label rows,
-#' whose formats are always `NULL`)
-#' @examples
+#' whose formats are always `NULL`).
+#'
+#' @seealso [table_shell()] and [table_shell_str()] for information on the table format structure.
 #'
+#' @examples
 #' lyt <- basic_table() %>%
 #'   split_rows_by("RACE", split_fun = keep_split_levels(c("ASIAN", "WHITE"))) %>%
 #'   analyze("AGE")
 #'
 #' tbl <- build_table(lyt, DM)
 #' value_formats(tbl)
+#'
+#' @export
 setGeneric("value_formats", function(obj, default = obj_format(obj)) standardGeneric("value_formats"))
 #' @rdname value_formats
 setMethod(
@@ -1193,7 +1197,6 @@ setMethod(
     obj_format(obj) %||% default
   }
 )
-
 #' @rdname value_formats
 setMethod(
   "value_formats", "TableRow",

R/tt_toString.R

@@ -72,8 +72,10 @@ setMethod("toString", "VTableTree", function(x,
 #' @inheritParams tostring
 #' @inheritParams gen_args
 #' @return for `table_shell_str` the string representing the table shell, for `table_shell`,
-#' `NULL`, as the function is called for the side effect of printing the shell to the console
-#' @export
+#' `NULL`, as the function is called for the side effect of printing the shell to the console.
+#'
+#' @seealso [value_formats()] for a matrix of formats for each cell in a table.
+#'
 #' @examples
 #' library(dplyr)
 #'
@@ -89,6 +91,8 @@ setMethod("toString", "VTableTree", function(x,
 #'
 #' tbl <- build_table(lyt, iris2)
 #' table_shell(tbl)
+#'
+#' @export
 table_shell <- function(tt, widths = NULL, col_gap = 3, hsep = default_hsep(),
                         tf_wrap = FALSE, max_width = NULL) {
   cat(table_shell_str(

vignettes/introspecting_tables.Rmd

@@ -120,6 +120,20 @@ row_paths_summary(tbl)
 col_paths_summary(tbl)
 ```
 
+## Insights on Value Format Structure
+
+We can gain insight into the value formatting structure of a table using `table_shell()`, which returns a table with the same output as `print()` but with the cell values replaced by their underlying format strings (e.g. instead of `40.0`, `xx.x` is displayed, and so on). This is useful for understanding the structure of the table, and for debugging purposes. Another useful tool is the `value_formats()` function which instead of a table returns a matrix of the format strings for each cell value in the table.
+
+See below the printout for the above examples:
+
+```{r}
+table_shell(tbl)
+```
+
+```{r}
+value_formats(tbl)
+```
+
 ## Applications
 
 Knowing the structure of an `rtable` object is helpful for retrieving specific values from the table.