Merge two columns to a value & uncertainty column

The cols_merge_uncert() function is a specialized variant of the cols_merge() function. It operates by taking a base value column (col_val) and an uncertainty column (col_uncert) and merges them into a single column. What results is a column with values and associated uncertainties (e.g., 12.0 ± 0.1), and, the column specified in col_uncert is dropped from the output table.

cols_merge_uncert(data, col_val, col_uncert)

Arguments

data	a table object that is created using the gt() function.
col_val	a single column name that contains the base values.
col_uncert	a single column name that contains the uncertainty values.

Value

an object of class gt_tbl.

Details

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

1. NAs in col_val result in missing values for the merged column (e.g., NA + 0.1 = NA)

2. NAs in col_uncert (but not col_val) result in base values only for the merged column (e.g., 12.0 + NA = 12.0)

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

Any resulting NA values in the col_val 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_range() function. These functions operate similarly, where the second column specified is dropped from the output table. For all of the cols_merge*() functions, column removal occurs late in the rendering lifecycle so those secondary columns are still usable as column references (e.g., inside expressions provided to `rows` in the fmt*() functions).

Figures

See also

Other column modification functions: cols_align, cols_hide, cols_label, cols_merge_range, cols_merge, cols_move_to_end, cols_move_to_start, cols_move, cols_split_delim

Examples

# Use `exibble` to create a gt table,
# keeping only the `currency` and `num`
# columns; merge columns into one with
# a base value and uncertainty (after
# formatting the `num` column)
tab_1 <-
  exibble %>%
  dplyr::select(currency, num) %>%
  dplyr::slice(1:7) %>%
  gt() %>%
  fmt_number(
    columns = vars(num),
    decimals = 3,
    use_seps = FALSE
  ) %>%
  cols_merge_uncert(
    col_val = vars(currency),
    col_uncert = vars(num)
  ) %>%
  cols_label(
    currency = "value + uncert.")