data_color: Set data cell colors using a palette or a color function

Description

It's possible to add color to data cells according to their values. The data_color() function colors all rows of any columns supplied. There are two ways to define how cells are colored: (1) through the use of a supplied color palette, and (2) through use of a color mapping function available from the scales package. The first method colorizes cell data according to whether values are character or numeric. The second method provides more control over how cells are colored since we provide an explicit color function and thus other requirements such as bin counts, cut points, or a numeric domain. Finally, we can choose whether to apply the cell-specific colors to either the cell background or the cell text.

Usage

data_color(
  data,
  columns,
  colors,
  alpha = NULL,
  apply_to = c("fill", "text"),
  autocolor_text = TRUE,
  contrast_algo = c("apca", "wcag")
)

Value

An object of class gt_tbl.

Arguments

data: A table object that is created using the gt() function.
columns: The columns wherein changes to cell data colors should occur.
colors: Either a color mapping function from the scales package or a vector of colors to use for each distinct value or level in each of the provided columns. The color mapping functions are: scales::col_quantile(), scales::col_bin(), scales::col_numeric(), and scales::col_factor(). If providing a vector of colors as a palette, each color value provided must either be a color name (in the set of colors provided by grDevices::colors()) or a hexadecimal string in the form of "#RRGGBB" or "#RRGGBBAA".
alpha: An optional, fixed alpha transparency value that will be applied to all of the colors provided (regardless of whether a color palette was directly supplied or generated through a color mapping function).
apply_to: Which style element should the colors be applied to? Options include the cell background (the default, given as "fill") or the cell text ("text").
autocolor_text: An option to let gt modify the coloring of text within cells undergoing background coloring. This will result in better text-to-background color contrast. By default, this is set to TRUE.
contrast_algo: The color contrast algorithm to use when autocolor_text = TRUE. By default this is "apca" (Accessible Perceptual Contrast Algorithm) and the alternative to this is "wcag" (Web Content Accessibility Guidelines).

Examples

Use countrypops to create a gt table. Apply a color scale to the population column with scales::col_numeric, four supplied colors, and a domain.

countrypops %>%
  dplyr::filter(country_name == "Mongolia") %>%
  dplyr::select(-contains("code")) %>%
  tail(10) %>%
  gt() %>%
  data_color(
    columns = population,
    colors = scales::col_numeric(
      palette = c("red", "orange", "green", "blue"),
      domain = c(0.2E7, 0.4E7)
    )
  )

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

Use pizzaplace to create a gt table. Apply colors from the "ggsci::red_material" palette (it's in the ggsci R package but more easily gotten from the paletteer package, info at info_paletteer()) to to sold and income columns. Setting the domain of scales::col_numeric() to NULL will use the bounds of the available data as the domain.

pizzaplace %>%
  dplyr::filter(type %in% c("chicken", "supreme")) %>%
  dplyr::group_by(type, size) %>%
  dplyr::summarize(
    sold = dplyr::n(),
    income = sum(price),
    .groups = "drop"
  ) %>%
  gt(
    rowname_col = "size",
    groupname_col = "type"
  ) %>%
  data_color(
    columns = c(sold, income),
    colors = scales::col_numeric(
      palette = paletteer::paletteer_d(
        palette = "ggsci::red_material"
      ) %>%
        as.character(),
      domain = NULL
    )
  )

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

Function ID

3-23

Details

The col_*() color mapping functions from the scales package can be used in the colors argument. These functions map data values (numeric or factor/character) to colors according to the provided palette.

scales::col_numeric(): provides a simple linear mapping from continuous numeric data to an interpolated palette.
scales::col_bin(): provides a mapping of continuous numeric data to value-based bins. This internally uses the base::cut() function.
scales::col_quantile(): provides a mapping of continuous numeric data to quantiles. This internally uses the stats::quantile() function.
scales::col_factor(): provides a mapping of factors to colors. If the palette is discrete and has a different number of colors than the number of factors, interpolation is used.

By default, gt will choose the ideal text color (for maximal contrast) when colorizing the background of data cells. This option can be disabled by setting autocolor_text to FALSE.

Choosing the right color palette can often be difficult because it's both hard to discover suitable palettes and then obtain the vector of colors. To make this process easier we can elect to use the paletteer package, which makes a wide range of palettes from various R packages readily available. The info_paletteer() information table allows us to easily inspect all of the discrete color palettes available in paletteer. We only then need to specify the package and palette when calling the paletteer::paletteer_d() function, and, we get the palette as a vector of hexadecimal colors.