extract_body {gt}

Extract the table body from a gt object

Description

We can extract the body of a gt table, even at various stages of its rendering, from a gt_tbl object using extract_body(). By default, the data frame returned will have gone through all of the build stages but we can intercept the table body after a certain build stage. Here are the eight different build stages and some notes about each:

1. "init": the body table is initialized here, entirely with NA values. It's important to note that all columns of the are of the character type in this first stage. And all columns remain in the same order as the input data table.

2. "fmt_applied": Any cell values that have had formatting applied to them are migrated to the body table. All other cells remain as NA values. Depending on the output type, the formatting may also be different.

3. "sub_applied": Any cell values that have had substitution functions applied to them (whether or not they were previously formatted) are migrated to the body table or modified in place (if formatted). All cells that had neither been formatted nor undergone substitution remain as NA values.

4. "unfmt_included": All cells that either didn't have any formatting or any substitution operations applied are migrated to the body table. NA values now become the string "NA", so, there aren't any true missing values in this body table.

5. "cols_merged": The result of column-merging operations (through cols_merge() and related functions) is materialized here. Columns that were asked to be hidden will be present here (i.e., hiding columns doesn't remove them from the body table).

6. "body_reassembled": Though columns do not move positions rows can move to different positions, and this is usually due to migration to different row groups. At this stage, rows will be in the finalized order that is seen in the associated display table.

7. "text_transformed": Various ⁠text_*()⁠ functions in gt can operate on body cells (now fully formatted at this stage) and return transformed character values. After this stage, the effects of those functions are apparent.

8. "footnotes_attached": Footnote marks are attached to body cell values (either on the left or right of the content). This stage performs said attachment.

Usage

extract_body(
  data,
  build_stage = NULL,
  output = c("html", "latex", "rtf", "word")
)

Arguments

data

The gt table data object

⁠obj:<gt_tbl>⁠ // required

This is the gt table object that is commonly created through use of the gt() function.

build_stage

The build stage of the formatted R data frame

⁠scalar<character>⁠ // default: NULL (optional)

When a gt undergoes rendering, the body of the table proceeds through several build stages. Providing a single stage name will yield a data frame that has been extracted after completed that stage. Here are the build stages in order: (1) "init", (2) "fmt_applied", (3) "sub_applied", (4) "unfmt_included", (5) "cols_merged", (6) "body_reassembled", (7) "text_transformed", and (8) "footnotes_attached". If not supplying a value for build_stage then the entire build for the table body (i.e., up to and including the "footnotes_attached" stage) will be performed before returning the data frame.

output

Output format

⁠singl-kw:[html|latex|rtf|word]⁠ // default: "html"

The output format of the resulting data frame. This can either be "html" (the default), "latex", "rtf", or "word".

Value

A data frame or tibble object containing the table body.

Function ID

13-7

Function Introduced

v0.10.0 (October 7, 2023)

See Also

Other table export functions: as_gtable(), as_latex(), as_raw_html(), as_rtf(), as_word(), extract_cells(), extract_summary(), gtsave()