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.

cols_merge_range(data, col_begin, col_end, 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.

sep

The separator text that indicates the values are ranged.

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.

Details

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 result in missing values for the merged column (e.g., NA + 20.0 = NA)

  2. NAs in col_end (but not col_begin) result in a display of only the col_begin values only for the merged column (e.g., 12.0 + NA = 12.0)

  3. NAs both in col_begin and col_end result in missing values for the merged column (e.g., NA + NA = NA)

Any resulting NA values in the col_begin column following the merge operation can be easily formatted using the fmt_missing() function.

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

Figures

See also

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) tab_1 <- gtcars %>% dplyr::select(model, starts_with("mpg")) %>% dplyr::slice(1:8) %>% gt() %>% cols_merge_range( col_begin = vars(mpg_c), col_end = vars(mpg_h) ) %>% cols_label( mpg_c = md("*MPG*") )