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.

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)

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