sub_large_vals: Substitute large values in the table body

Description

Wherever there is numerical data that are very large in value, replacement text may be better for explanatory purposes. The sub_large_vals() function allows for this replacement through specification of a threshold, a large_pattern, and the sign of the values to be considered.

Usage

sub_large_vals(
  data,
  columns = everything(),
  rows = everything(),
  threshold = 1e+12,
  large_pattern = ">={x}",
  sign = "+"
)

Value

An object of class gt_tbl.

Arguments

data: A table object that is created using the gt() function.
columns: The columns to format. Can either be a series of column names provided in c(), a vector of column 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().
rows: Optional rows to format. Providing everything() (the default) results in all rows in columns being formatted. Alternatively, we can supply a vector of row captions 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 expressions to filter down to the rows we need (e.g., [colname_1] > 100 & [colname_2] < 50).
threshold: The threshold value with which values should be considered large enough for replacement.
large_pattern: The pattern text to be used in place of the suitably large values in the rendered table.
sign: The sign of the numbers to be considered in the replacement. By default, we only consider positive values ("+"). The other option ("-") can be used to consider only negative values.

Examples

Let's generate a simple, single-column tibble that contains an assortment of values that could potentially undergo some substitution.

tbl <- dplyr::tibble(num = c(0, NA, 10^(8:14)))
tbl
#> # A tibble: 9 x 1
#>     num
#>   <dbl>
#> 1  0   
#> 2 NA   
#> 3  1e 8
#> 4  1e 9
#> 5  1e10
#> 6  1e11
#> 7  1e12
#> 8  1e13
#> 9  1e14

The tbl contains a variety of smaller numbers and some might be small enough to reformat with a threshold value. With sub_small_vals() we can do just that:

tbl %>%
  gt() %>%
  fmt_number(columns = num) %>%
  sub_large_vals()

This image of a table was generated from the first code example in the `sub_large_vals()` help file.

Large negative values can also be handled but they are handled specially by the sign parameter. Setting that to "-" will format only the large values that are negative. Notice that with the default large_pattern value of ">={x}" the ">=" is automatically changed to "<=".

tbl %>%
  dplyr::mutate(num = -num) %>%
  gt() %>%
  fmt_number(columns = num) %>%
  sub_large_vals(sign = "-")

This image of a table was generated from the second code example in the `sub_large_vals()` help file.

You don't have to settle with the default threshold value or the default replacement pattern (in large_pattern). This can be changed and the "{x}" in large_pattern (which uses the threshold value) can even be omitted.

tbl %>%
  gt() %>%
  fmt_number(columns = num) %>%
  sub_large_vals(
    threshold = 5E10,
    large_pattern = "hugemongous"
  )

This image of a table was generated from the third code example in the `sub_large_vals()` help file.

Function ID

3-19

Details

Targeting of values is done through columns and additionally by rows (if nothing is provided for rows then entire columns are selected). Conditional formatting is possible by providing a conditional expression to the rows argument. See the Arguments section for more information on this.