tab_spanner_delim: Create column labels and spanners via delimited names

Description

This function will split selected delimited column names such that the first components (LHS) are promoted to being spanner column labels, and the secondary components (RHS) will become the column labels. Please note that reference to individual columns must continue to be the column names from the input table data (which are unique by necessity).

Usage

tab_spanner_delim(
  data,
  delim,
  columns = everything(),
  split = c("last", "first")
)

Value

An object of class gt_tbl.

Arguments

data: A table object that is created using the gt() function.
delim: The delimiter to use to split an input column name. The delimiter supplied will be autoescaped for the internal splitting procedure. The first component of the split will become the spanner column label (and its ID value, used for styling or for the addition of footnotes in those locations) and the second component will be the column label.
columns: An optional vector of column names that this operation should be limited to. The default is to consider all columns in the table.
split: Should the delimiter splitting occur from the "last" instance of the delim character or from the "first"? By default, column name splitting begins at the last instance of the delimiter.

Examples

Use iris to create a gt table and use the tab_spanner_delim() function to automatically generate column spanner labels. This splits any columns that are dot-separated between column spanner labels (first part) and column labels (second part).

iris %>%
  dplyr::group_by(Species) %>%
  dplyr::slice(1:4) %>%
  gt() %>%
  tab_spanner_delim(delim = ".")

This image of a table was generated from the first code example in the `tab_spanner_delim()` help file.

Function ID

2-3

Details

If we look to the column names in the iris dataset as an example of how tab_spanner_delim() might be useful, we find the names Sepal.Length, Sepal.Width, Petal.Length, Petal.Width. From this naming system, it's easy to see that the Sepal and Petal can group together the repeated common Length and Width values. In your own datasets, we can avoid a lengthy relabeling with cols_label() if column names can be fashioned beforehand to contain both the spanner column label and the column label. An additional advantage is that the column names in the input table data remain unique even though there may eventually be repeated column labels in the rendered output table).