The cols_merge_uncert()
function is a specialized variant of the
cols_merge()
function. It takes as input a base value column (col_val
)
and either: (1) a single uncertainty column, or (2) two columns representing
lower and upper uncertainty bounds. These columns will be essentially merged
in a single column (that of col_val
). What results is a column with values
and associated uncertainties (e.g., 12.0 ± 0.1
), and any columns specified
in col_uncert
are hidden from appearing the output table.
Arguments
- data
A table object that is created using the
gt()
function.- col_val
A single column name that contains the base values. This is the column where values will be mutated.
- col_uncert
Either one or two column names that contain the uncertainty values. The most common case involves supplying a single column with uncertainties; these values will be combined with those in
col_val
. Less commonly, lower and upper uncertainty bounds may be different. For that case two columns (representing lower and upper uncertainty values away fromcol_val
, respectively) should be provided. Since we often don't want the uncertainty value columns in the output table, we can automatically hide anycol_uncert
columns through theautohide
option.- sep
The separator text that contains the uncertainty mark for a single uncertainty value. The default value of
" +/- "
indicates that an appropriate plus/minus mark will be used depending on the output context. Should you want this special symbol to be taken literally, it can be supplied within theI()
function.- autohide
An option to automatically hide any columns specified in
col_uncert
. Any columns with their state changed to 'hidden' will behave the same as before, they just won't be displayed in the finalized table. By default, this is set toTRUE
.
Details
This function could be somewhat replicated using cols_merge()
in the case
where a single column is supplied for col_uncert
, however,
cols_merge_uncert()
employs the following specialized semantics for NA
handling:
NA
s incol_val
result in missing values for the merged column (e.g.,NA
+0.1
=NA
)NA
s incol_uncert
(but notcol_val
) result in base values only for the merged column (e.g.,12.0
+NA
=12.0
)NA
s bothcol_val
andcol_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 sub_missing()
function.
This function is part of a set of four column-merging functions. The other
two are the general cols_merge()
function and the specialized
cols_merge_range()
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 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) using the cols_merge_uncert()
function.
exibble %>%
dplyr::select(currency, num) %>%
dplyr::slice(1:7) %>%
gt() %>%
fmt_number(
columns = num,
decimals = 3,
use_seps = FALSE
) %>%
cols_merge_uncert(
col_val = currency,
col_uncert = num
) %>%
cols_label(currency = "value + uncert.")
See also
Other Modify Columns:
cols_align()
,
cols_hide()
,
cols_label()
,
cols_merge_n_pct()
,
cols_merge_range()
,
cols_merge()
,
cols_move_to_end()
,
cols_move_to_start()
,
cols_move()
,
cols_unhide()
,
cols_width()