emphatic

{emphatic} augments the output of data.frames, matrices and simple vectors in R by adding user-defined ANSI highlighting.

See the online documentation for vignettes and more examples.

What’s in the box

There are separate high-level functions for highlighting data.frames, matrices and simple vectors. There is also a low-level highlghting function which can be used on data.frames and matrices.

The hl_ prefix can be read as highlight.

• hl() for highlighting data.frames
• hl_mat() for highlighting matrices
• hl_vec() for highlighting simple atomic vectors
• hl_loc() for low-level control of highlighting of both data.frames and matrices
• hl_opt() to set some local options on the current emphatic object e.g. full_colour option sets 24-bit colour mode.
• hl_opt_global() sets global options for highlighting. These values will be the default unless overridden with a call to hl_opt() for the given emphatic object.
• hl_str_diff() for highlighting string differences.
• General highlighting for regular expressions.
  • hl_grep(x, pattern) where x is a character string.
  • hl_grep_character() where the general object x is converted to a string using as.character().
  • hl_grep_print() as above, but converstion to character via print()
  • hl_grep_deparse() as above, but using deparse1() to create string representation of object.
  • hl_grep_str() as above, but using str() to create string representation of object.

Installation

You can install from GitHub with:

# install.package('remotes')
remotes::install_github('coolbutuseless/emphatic', ref = 'main')

Warning

• This package calls eval() on user-supplied code and extreme caution should be taken before exposing functions in this package to the internet (e.g. via shiny)

Vignettes

Intro

• Highlighting data.frames
• Highlighting matrices
• Highlighting vectors

Specifying rows, columns and colours

• Specifying rows
• Specifying columns
• Specifying colours

Test cases on Real data

• Space Shuttle O-ring dataset - Challenger Disaster
• Southern Sea Ice Area
• volcano dataset
• Correlation matrix

Advanced:

• Low level highlighting with hl_loc()

Example: Highlighting a data.frame with alternating row colours

library(emphatic)
emphatic::hl_opt_global(dark_mode = FALSE)

mtcars |>
  hl(c('red', 'white')) 

Example of highlighting a data.frame and include a legend

Use {emphatic} to highlight the mtcars dataset where:

• colour each row to indicate the miles-per-gallon rating
• do not colour the gear or carb columns
• highlight the car with the maximum miles per gallon in hotpink

mtcars |>
  hl(ggplot2::scale_colour_viridis_c(),
     cols = mpg, dest_cols = mpg:am, show_legend = TRUE) |>
  hl('hotpink', rows = mpg == max(mpg)) |>
  hl_opt(text_contrast = 0.25)

Example: Highlighting a data.frame with rainbows!

mtcars |> 
  hl(rainbow(32)) |>
  hl_opt(text_contrast = 0.5)

Example: Highlighting a matrix - Correlation matrix

Create a correlation matrix of some of the variables in mtcars.

Colour the values using red for negative correlations and blue for positive correlations. Values in-between are coloured using a gradient between red and blue. This colouring is applied using ggplot2::scale_colour_gradient2().

mtcars |>
  select(cyl, mpg, hp, disp, vs) |>
  cor() |>
  hl_mat(scale_colour_gradient2(), selection = abs(.x) > 0.7 & row(.x) != col(.x)) 

Example: Highlighting a numeric vector

Highlight locations in a numeric vector which match an expression.

sample(10, 30, replace = TRUE, prob = 1:10) |>
  hl_vec('green', .x < 3) |>
  hl_vec('blue', .x > 7)

Example: Highlighting the difference between strings

x <- 'hell there!'
y <- 'hello there?'
hl_str_diff(x, y)

x <- 'hello there?'
y <- 'hell there!'
hl_str_diff(x, y)

x <- "Paris in the the spring?"
y <- "Not Paris in the spring!"
hl_str_diff(x, y)

Highlighting grep() matches in character representations of objects

Example: Highlight a string in a data.frame

mtcars |> 
  head(20) |>
  hl_grep_print("Merc")

Highlight a row in a data.frame which matches a word

mtcars |> 
  head(20) |>
  hl_grep_print("(?m)^.*wood.*?$", fg = 'blue', bg = 'hotpink')

Highlight text in a string

string <- 
"<xml>
   <this is='not'>a real XML doc</this>
   <this is='not'>a real HTML doc</this>
   <this is='not'>a real XML doc</this>
   <this is='not'>a real XML doc</this>
</xml>"

hl_grep(string, "html", ignore.case = TRUE)

Highlighting within a character vector

vals <- c('hello', 'there', '#rstats', 'on', 'mastodon')

hl_grep(vals, "rstats")

Highlighting within a numeric vector

hl_grep_character(pi, "589")

Related Software

• crayon Colored terminal output on terminals that support ‘ANSI’ color and highlight codes. It also works in ‘Emacs’ ‘ESS’. ‘ANSI’ color support is automatically detected.
• fansi Counterparts to R string manipulation functions that account for the effects of ANSI text formatting control sequences.

Acknowledgements

• R Core for developing and maintaining the language.
• CRAN maintainers, for patiently shepherding packages onto CRAN and maintaining the repository