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,
  colour,
  rows = NULL,
  cols = NULL,
  dest_cols,
  calc_scale = "first",
  elem = "fill",
  show_legend = FALSE
)

Arguments

.data

emphatic data.frame

colour

colour to use for highlighting. This may be an 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. See documentation for hl() for the valid types of row/column specifcations.

dest_cols

specification of destination columns to colour. If missing (the default), this function will only colour the columns specified in the cols argument. Use NULL to colour all columns. See documentation for hl() for the valid types of column specifcations.

calc_scale

If colour is a ggplot2 "Scale" object, this option defines how the scale should be applied.

first: (default)the colours to use are calculated using the scale applied to the first specified column in cols. The colours calculated on this first column are then copied to the other columns specified in dest_cols
each: the colour scale is applied individually to each column in turn. calc_scale = 'each' can only be applied if dest_cols is identical to cols

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

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

if (FALSE) {
hl(mtcars, ggplot2::scale_colour_viridis_c(), rows = cyl == 6, cols = mpg, dest_cols = c(mpg, cyl))
}