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.frameshl_mat()
for highlighting matriceshl_vec()
for highlighting simple atomic vectorshl_loc()
for low-level control of highlighting of both data.frames and matriceshl_opt()
to set some local options on the currentemphatic
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 tohl_opt()
for the givenemphatic
object.hl_str_diff()
for highlighting string differences.- General highlighting for regular expressions.
hl_grep(x, pattern)
wherex
is a character string.hl_grep_character()
where the general objectx
is converted to a string usingas.character()
.hl_grep_print()
as above, but converstion to character viaprint()
hl_grep_deparse()
as above, but usingdeparse1()
to create string representation of object.hl_grep_str()
as above, but usingstr()
to create string representation of object.
data.frame | matrix | vector | |
---|---|---|---|
High Level | hl() |
hl_mat() |
hl_vec() |
Low Level | hl_loc() |
hl_loc() |
NA |
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. viashiny
)
Vignettes
Intro
Specifying rows, columns and colours
Test cases on Real data
- Space Shuttle O-ring dataset - Challenger Disaster
- Southern Sea Ice Area
volcano
dataset- Correlation matrix
Advanced:
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
orcarb
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