Highlight elements in a data.frame

Highlight elements in a data.frame by specifying rows and columns, and the colour to be applied. The colour can be either a vector of colours expressed as characters (e.g. 'red', '#ff0000'), or a ggplot2 Scale object e.g. scale_colour_viridis_c().

hl(
  .data,
  palette,
  rows = NULL,
  cols = NULL,
  scale_apply,
  elem = "fill",
  show_legend = FALSE,
  opts = hl_opts()
)

Arguments

.data: emphatic data.frame
palette: colours to use for highlighting. This may be a single R colour, a vector of R colours, or a ggplot2 style "Scale" object e.g. scale_colour_continuous().
rows, cols: specification for rows and columns to target. Default is NULL for both rows and columns, which will target all columns/rows. When palette argument is a scale object, then cols indicates the columns which will be used to calculate the extents of the scale.
scale_apply: Only valid when palette is a scale object, specify the target columns to colour. If missing (the default), this function will only colour the column specified in the cols argument. Use NULL to colour all columns.
elem: Apply the highlighting to the 'fill' (the background) or the 'text'. Default: 'fill'
show_legend: if a scale object is used for colour, and show_legend = TRUE, then a colourbar legend will be added to the bottom of the output. Default: FALSE
opts: create options list

Row and Column Specifications

Specifying rows and columns can be done in a number of ways. These methods are similar to the ideas of tidyselect and dplyr commands such as filter() and select()

numeric vector: row or column indices specified as a numeric vector e.g. c(1, 2, 8)
character vector: vector of names matching row or column names e.g. c('mpg', 'wt')
vector of symbols/names: vector of symbols which will be evaluated as column names e.g. c(mpg, wt)
numeric range: range of indices specified using the : operator e.g. 1:8
symbolic range: range of columns specified using the : operator e.g. mpg:wt
tidyselect-style selectors: starts_with(), ends_with(), everything(), all_of(), any_of(), matches() contains(), row_number(), n(). These work similar to dplyr and tidyselect but are bespoke implementations so there may be some differences
NULL: specifying NULL means that all rows/columns will be selected
all(): specifying all() means that all rows/columns will be selected
code that will evaluate to row positions: For row selection only, the user can specify code which will evaluate to a logical vector of rows which the highlighting should apply to. These will look like statements used in dplyr::filter(). E.g. cyl == 6 & mpg > 20

Examples

# Simple
mtcars |>
  head() |>
  hl(c('red', 'blue'))
#>                      mpg cyl disp  hp drat    wt  qsec vs am gear carb
#> Mazda RX4           21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
#> Mazda RX4 Wag       21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
#> Datsun 710          22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
#> Hornet 4 Drive      21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
#> Hornet Sportabout   18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
#> Valiant             18.1   6  225 105 2.76 3.460 20.22  1  0    3    1

# More involved example
mtcars |>
  head() |>
  hl(
    ggplot2::scale_colour_viridis_c(),
    rows = cyl == 6,
    cols = mpg,
    scale_apply = c(mpg, cyl)
  )
#>                      mpg cyl disp  hp drat    wt  qsec vs am gear carb
#> Mazda RX4           21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
#> Mazda RX4 Wag       21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
#> Datsun 710          22.8   4  108  93 3.85 2.320 18.61  1  1    4    1
#> Hornet 4 Drive      21.4   6  258 110 3.08 3.215 19.44  1  0    3    1
#> Hornet Sportabout   18.7   8  360 175 3.15 3.440 17.02  0  0    3    2
#> Valiant             18.1   6  225 105 2.76 3.460 20.22  1  0    3    1