vlightr

{vlightr} (read, “vector-highlighter”) makes it easy to identify elements of interest in a vector printed to the console. {vlightr} implements a <vlightr_highlight> vector superclass which enhances the format() and print() methods of generic vectors, allowing you to specify a custom conditional formatting method for (almost) any vector type in R.

Installation

⚠️ This package is still under construction. ⚠️

You can install the development version of vlightr from GitHub with:

# install.packages("devtools")
devtools::install_github("EthanSansom/vlightr")

Features

library(vlightr)
library(dplyr, warn.conflicts = FALSE)

Want to identify an element of a vector? Highlight it with highlight().

# Highlight the maximum element of `x`
x <- c(1, 8, 12, 4, 2)
maximum_hl <- vlightr::highlight(x, .t = ~ .x == max(.x))
print(maximum_hl)

Highlighted elements change as the highlighted vector changes, so you won’t lose them.

# `hl()` is shorthand for `highlight()`
sort(maximum_hl + vlightr::hl(10))

Highlighted vectors can be used as tibble::tibble() columns too.

iris |>
  as_tibble() |>
  mutate(
    species = vlightr::highlight_mult(
      Species,
      "setosa" ~ vlightr::color("purple"),
      "versicolor" ~ vlightr::color("violet"),
      "virginica" ~ vlightr::color("pink")
    )
  ) |>
  group_by(species) |>
  summarize(
    avg_petal_length = vlightr::highlight(mean(Petal.Length), ~ .x == max(.x)),
    avg_sepal_width = vlightr::highlight(mean(Sepal.Width), ~ .x == max(.x))
  ) |>
  ungroup()

Are you (or your boss) having a hard time finding that row you’re looking for? Use templight() to temporarily highlight a vector by index.

mtcars |>
  as_tibble(rownames = "model") |>
  mutate(across(everything(), ~ vlightr::templight(.x, model == "Datsun 710"))) |>
  select(model, mpg, disp, vs) |>
  head(5)

You can apply multiple conditional formats to a vector using highlight_mult(). The left-hand-side is a test function or a literal value that you want to match and the right-hand-side is a formatter function.

indicator <- vlightr::highlight_mult(
    c(1, 0, 1, NA, 5),
    is.na ~ vlightr::color("red"), # Color NA values red
    0 ~ vlightr::label("No"),      # Label 0 as "No"
    1 ~ vlightr::label("Yes"),     # Label 1 as "Yes"
    !(.x %in% c(NA, 0, 1)) ~ paste(.x, "[?]") # Label others with "?"
)
print(indicator)

highlight_case() provides a dplyr::case_when() style interface and conditionally formats elements using at most one formatter.

indicator <- vlightr::highlight_case(
    c(1, 0, 1, 0, 0, NA, 5),
    is.na ~ vlightr::color("red"),
    0 ~ vlightr::label("No"),
    1 ~ vlightr::label("Yes"),
    vlightr::true ~ paste(.x, "[?]") # Provide a default formatter
)
print(indicator)

To re-use a conditional format, make a highlighter() function.

indicator_highlighter <- vlightr::highlighter_case(
    is.na ~ vlightr::color("red"),
    0 ~ vlightr::label("No"),
    1 ~ vlightr::label("Yes"),
    vlightr::true ~ paste(.x, "[?]")
)
indicator_highlighter(c(0, 1, NA, -9))

Inspiration

The development of {vlightr} relied heavily on the following packages:

• purrr, which inspired the user interface of highlight()
• dplyr, whose case_when() inspired highlight_case()
• magrittr, whose %>% made the highlight pipe %hl>% possible
• cli, which is responsible for all of the colored text produced by {vlightr}
• vctrs, for making S3 vectors easy to work with
• usethis and pkgdown, which make every step of R-package and R-package-website development easier

This package is also heavily inspired by the ivs package, which (also powered by vctrs) implements generic right-open intervals defined by a pair of parallel start and end vectors.

As a testament to the genericity of the <ivs_iv>, here is an ill-advised but perfectly legal interval vector.

library(ivs)

# Prepare highlighted numeric start and end vectors
starts <- vlightr::highlight(-3:2, ~ .x %% 2 == 0, ~ label("Even"))
ends <- vlightr::highlight(c(-2, -1, 2, 5, 7, 8), ~ .x > 0, ~ paste0("+", .x))

# Make an iv() with highlighted `starts` and `ends`
iv(starts, ends)

The interval vector can be manipulated as you’d expect.

iv_groups(iv(starts, ends))

And the interval vector can itself be highlighted.

vlightr::highlight(
  iv(starts, ends), 
  ~ (iv_end(.x) - iv_start(.x)) > hl(1),
  vlightr::color("goldenrod")
)