cols_merge_range: Merge two columns to a value range column

In gt: Easily Create Presentation-Ready Display Tables

Merge two columns to a value range column

Description

The cols_merge_range() function is a specialized variant of the cols_merge() function. It operates by taking a two columns that constitute a range of values (col_begin and col_end) and merges them into a single column. What results is a column containing both values separated by a long dash (e.g., ⁠12.0 — 20.0⁠). The column specified in col_end is dropped from the output table.

Usage

cols_merge_range(
  data,
  col_begin,
  col_end,
  rows = everything(),
  sep = "--",
  autohide = TRUE
)

Arguments

data	A table object that is created using the gt() function.
col_begin	A column that contains values for the start of the range.
col_end	A column that contains values for the end of the range.
rows	Rows that will participate in the merging process. Providing everything() (the default) results in all rows in columns undergoing merging. Alternatively, we can supply a vector of row identifiers within c(), a vector of row indices, or a helper function focused on selections. The select helper functions are: starts_with(), ends_with(), contains(), matches(), one_of(), num_range(), and everything(). We can also use a standalone predicate expression to filter down to the rows we need (e.g., ⁠[colname_1] > 100 & [colname_2] < 50⁠).
sep	The separator text that indicates the values are ranged. The default value of "--" indicates that an en dash will be used for the range separator. Using "---" will be taken to mean that an em dash should be used. Should you want these special symbols to be taken literally, they can be supplied within the base I() function.
autohide	An option to automatically hide the column specified as col_end. Any columns with their state changed to hidden will behave the same as before, they just won't be displayed in the finalized table.

Value

An object of class gt_tbl.

Comparison with other column-merging functions

This function could be somewhat replicated using cols_merge(), however, cols_merge_range() employs the following specialized operations for NA handling:

1. NAs in col_begin (but not col_end) result in a display of only

2. NAs in col_end (but not col_begin) result in a display of only the col_begin values only for the merged column (this is the converse of the previous)

3. NAs both in col_begin and col_end result in missing values for the merged column

Any resulting NA values in the col_begin column following the merge operation can be easily formatted using the sub_missing() function. Separate calls of sub_missing() can be used for the col_begin and col_end columns for finer control of the replacement values.

This function is part of a set of four column-merging functions. The other three are the general cols_merge() function and the specialized cols_merge_uncert() and cols_merge_n_pct() functions. These functions operate similarly, where the non-target columns can be optionally hidden from the output table through the hide_columns or autohide options.

Examples

Use gtcars to create a gt table, keeping only the model, mpg_c, and mpg_h columns. Merge the "mpg*" columns together as a single range column (which is labeled as MPG, in italics) using the cols_merge_range() function.

gtcars |>
  dplyr::select(model, starts_with("mpg")) |>
  dplyr::slice(1:8) |>
  gt() |>
  cols_merge_range(
    col_begin = mpg_c,
    col_end = mpg_h
  ) |>
  cols_label(mpg_c = md("*MPG*"))

Function ID

5-13

Function Introduced

v0.2.0.5 (March 31, 2020)

See Also

Other column modification functions: cols_align_decimal(), cols_align(), cols_hide(), cols_label_with(), cols_label(), cols_merge_n_pct(), cols_merge_uncert(), cols_merge(), cols_move_to_end(), cols_move_to_start(), cols_move(), cols_unhide(), cols_width()

gt documentation built on April 3, 2023, 5:18 p.m.