cols_merge_uncert: Merge columns to a value-with-uncertainty column

In gt: Easily Create Presentation-Ready Display Tables

Merge columns to a value-with-uncertainty column

Description

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.

Usage

cols_merge_uncert(
  data,
  col_val,
  col_uncert,
  rows = everything(),
  sep = " +/- ",
  autohide = TRUE
)

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 from col_val, respectively) should be provided. Since we often don't want the uncertainty value columns in the output table, we can automatically hide any col_uncert columns through the autohide option.
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 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 the I() 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 to TRUE.

Value

An object of class gt_tbl.

Comparison with other column-merging functions

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:

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 sub_missing() function.

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

Function ID

5-12

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_range(), 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.