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)



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


A single column name that contains the base values.


A single column name that contains the uncertainty values.


An object of class gt_tbl.


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).


See also


# 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." )