gt: cols_merge_uncert – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

cols_merge_uncert

Merge two columns to a value & uncertainty column

Description

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.

Usage

cols_merge_uncert(data, col_val, col_uncert, 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`	A single column name that contains the uncertainty values. These values will be combined with those in `col_val`. We have the option to automatically hide the `col_uncert` column through `autohide`.
`sep`	The separator text that contains the uncertainty mark. 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 base `I()` function.
`autohide`	An option to automatically hide the column specified as `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.

Details

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

NAs in col_val result in missing values for the merged column (e.g., NA + 0.1 = NA)
NAs in col_uncert (but not col_val) result in base values only for the merged column (e.g., 12.0 + NA = 12.0)
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 non-target columns can be optionally hidden from the output table through the hide_columns or autohide options.

Value

An object of class gt_tbl.

Figures

Function ID

4-8

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

gt

Easily Create Presentation-Ready Display Tables

v0.2.2

MIT + file LICENSE

Authors

Richard Iannone [aut, cre] (<https://orcid.org/0000-0003-3925-190X>), Joe Cheng [aut], Barret Schloerke [aut] (<https://orcid.org/0000-0001-9986-114X>), RStudio [cph, fnd]

Initial release