gt (version 0.2.2)

cols_merge: Merge data from two or more columns to a single column

Description

This function takes input from two or more columns and allows the contents to be merged them into a single column, using a pattern that specifies the formatting. We can specify which columns to merge together in the columns argument. The string-combining pattern is given in the pattern argument. The first column in the columns series operates as the target column (i.e., will undergo mutation) whereas all following columns will be untouched. There is the option to hide the non-target columns (i.e., second and subsequent columns given in columns).

Usage

cols_merge(
  data,
  columns,
  hide_columns = columns[-1],
  pattern = paste0("{", seq_along(columns), "}", collapse = " ")
)

Arguments

data

A table object that is created using the gt() function.

columns

The columns that will participate in the merging process. The first column name provided will be the target column (i.e., undergo mutation) and the other columns will serve to provide input.

hide_columns

Any column names provided here will have their state changed to hidden (via internal use of cols_hide() if they aren't already hidden. This is convenient if the shared purpose of these specified columns is only to provide string input to the target column.

pattern

A formatting pattern that specifies the arrangement of the column values and any string literals. We need to use column numbers (corresponding to the position of columns provided in columns) within the pattern. These indices are to be placed in curly braces (e.g., {1}). All characters outside of braces are taken to be string literals.

Value

An object of class gt_tbl.

Figures

Function ID

4-10

Details

There are two other column-merging functions that offer specialized behavior that is optimized for common table tasks: cols_merge_range() and cols_merge_uncert(). These functions operate similarly, where the non-target columns can be optionally hidden from the output table through the autohide option.

See Also

Other Modify Columns: cols_align(), cols_hide(), cols_label(), cols_merge_range(), cols_merge_uncert(), cols_move_to_end(), cols_move_to_start(), cols_move(), cols_width()

Examples

# NOT RUN {
# Use `sp500` to create a gt table;
# merge the `open` & `close` columns
# together, and, the `low` & `high`
# columns (putting an em dash between
# both); rename the columns
tab_1 <-
  sp500 %>%
  dplyr::slice(50:55) %>%
  dplyr::select(-volume, -adj_close) %>%
  gt() %>%
  cols_merge(
    columns = vars(open, close),
    hide_columns = vars(close),
    pattern = "{1}—{2}"
  ) %>%
  cols_merge(
    columns = vars(low, high),
    hide_columns = vars(high),
    pattern = "{1}—{2}"
  ) %>%
  cols_label(
    open = "open/close",
    low = "low/high"
  )

# }