hl {emphatic}

Highlight elements in a data.frame

Description

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

Usage

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

Value

An emphatic object suitable to output to console (for example)

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'))

# More involved example
mtcars |>
  head() |>
  hl(
    ggplot2::scale_colour_viridis_c(),
    rows = cyl == 6,
    cols = mpg,
    scale_apply = c(mpg, cyl)
  )