Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/coolbutuseless/emphatic
Highlighting R output in the console
https://github.com/coolbutuseless/emphatic
Last synced: 4 days ago
JSON representation
Highlighting R output in the console
- Host: GitHub
- URL: https://github.com/coolbutuseless/emphatic
- Owner: coolbutuseless
- License: other
- Created: 2020-10-29T20:17:47.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-07-23T03:28:27.000Z (4 months ago)
- Last Synced: 2024-10-26T20:35:45.998Z (18 days ago)
- Language: R
- Homepage: https://coolbutuseless.github.io/package/emphatic/
- Size: 32.3 MB
- Stars: 139
- Watchers: 6
- Forks: 5
- Open Issues: 2
-
Metadata Files:
- Readme: README.Rmd
- Changelog: NEWS.md
- License: LICENSE
Awesome Lists containing this project
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
library(dplyr)
library(ggplot2)
library(emphatic)
set.seed(1)
```
```{r echo = FALSE, eval = FALSE}
# Quick logo generation. Borrowed heavily from Nick Tierney's Syn logo process
library(magick)
library(showtext)
font_add_google("Alfa Slab One", "gf")
if (FALSE) {
pkgdown::build_site(override = list(destination = "../coolbutuseless.github.io/package/emphatic"))
}
```
```{r echo = FALSE, eval = FALSE}
img <- image_read("man/figures/white.png")
hexSticker::sticker(subplot = img,
s_x = 1,
s_y = 1.2,
s_width = 1.5,
s_height = 0.95,
package = "emphatic",
p_x = 1,
p_y = 1.05,
p_color = "#223344",
p_family = "gf",
p_size = 8,
h_size = 1.2,
h_fill = "#ffffff",
h_color = "#223344",
filename = "man/figures/logo.png")
image_read("man/figures/logo.png")
```
# emphatic
[](https://github.com/coolbutuseless/emphatic/actions/workflows/R-CMD-check.yaml)
`{emphatic}` is a tool for exploratory analysis of tabular data. It allows the user
to visually colour elements of the data, yet still keep all values visible.
Conceptually, `{emphatic}` highlighting could be considered to lie between *tabular output*
and *graphical output* - like a table it shows all values, but like graphs these
values are used to control appearance (i.e. colour).
`{emphatic}` follows the conventions
of `{dplyr}` for selecting rows and columns; advanced colouring is via
colour scales provided by `{ggplot2}`.
#### Supported output
This highlighting works
* in the **console**
* when output to **Excel** (using `write_xlsx()`)
* rendered in **Rmarkdown** documents (to `HTML`, `latex` and `typst` outputs)
* rendered in **Quarto** documents (to `HTML`, `latex` and `typst` outputs)
* rendered to **SVG**
* rendered as multiple frames to **animated SVG**
Click here to show/hide gif demo
#### What's in the box
* `hl()` for user-defined highlighting of data.frames
* `hl_diff()` for highlighting differences between two objects
* `hl_grep()` highlight regular expression matches in an object or string
* Manual conversion to other formats using:
* `as_html()`
* `as_svg()` and animated `as_svg_anim()`
* `as_typst()`
* `write_xlsx()` - Excel document
* Conversion to the correct output format is performed automatically when
knitting an Rmarkdown or Quarto document.
#### Installation
You can install from [GitHub](https://github.com/coolbutuseless/emphatic) with:
``` r
# install.packages('remotes')
remotes::install_github('coolbutuseless/emphatic')
```
## Highlighting of data.frames with `hl()`
`hl()` lets you specify a palette, and the rows/columns of the data.frame the
palette should apply to.
`hl()` calls are cumulative - so the required highlighting can be built up one-step-at-a-time.
To add highlighing to a data.frame:
* **Specify a palette**
* a single colour or vector of colours
* a `ggplot2` *Scale* object e.g. `scale_colour_continuous()`
* **Specify rows and columns**
* default: highlight all rows and all columns.
* numeric vector giving row/column indices e.g. `c(1, 2, 8)`, `1:8`
* character vector giving row/column names e.g. `c('mpg', 'wt')`
* vector of bare column names e.g. `c(mpg, wt)`, `mpg:wt`
* tidyselect-style selectors: `starts_with()`, `ends_with()`, `everything()`,
`all_of()`, `any_of()`, `matches()`, `contains()`, `row_number()`, `n()`
* row selection using filtering operations e.g. `cyl == 6 & mpg > 20`
#### Simple example
By default, colouring will be applied to all rows and columns, and the
supplied vector of colours will be recycled to meet the required length.
```{r example, eval = FALSE}
mtcars |>
head(15) |>
hl(c('red', 'white', 'blue'))
```
```{r eval = TRUE, echo = FALSE}
mtcars |>
head(15) |>
hl(c('red', 'white', 'blue')) |>
as_svg(650, 350) |>
cat(file = "man/figures/example1.svg")
```
#### Complex example
A more complex example showing how to highlight the `mtcars` dataset where:
* Highlight the row for the car with the minimum horsepower
* Determine an expressive colouring for `mpg` using `scale_colour_viridis_c()` -
where low values are darker, and high values are a bright yellow
* Apply the scale's colouring to all columns from `mpg` to `disp`
```{r eval = FALSE}
mtcars |>
head(15) |>
hl('hotpink', rows = hp == min(hp)) |>
hl(
palette = ggplot2::scale_colour_viridis_c(option = 'A'),
cols = mpg, # Where the colour scale is calculated
scale_apply = mpg:disp, # Where the colour scale is applied
show_legend = TRUE
)
```
```{r echo = FALSE}
mtcars |>
head(15) |>
hl(
palette = ggplot2::scale_colour_viridis_c(option = 'A'),
cols = mpg, # Where the colour scale is calculated
scale_apply = mpg:disp, # Where the colour scale is applied
show_legend = TRUE
) |>
hl('hotpink', rows = hp == min(hp), cols = hp:carb) |>
as_svg(650, 380) |>
cat(file = "man/figures/example2.svg")
```
## Highlight difference between two objects with `hl_diff()`
The Levenshtein edit distance is calculated between the string representation
of two objects and these edits are then coloured 🟢 = insert, 🔴 = delete,
🔵 = substitute.
```{r eval = FALSE}
x <- "Paris in the the spring?"
y <- "Not Paris in the spring!"
hl_diff(x, y)
```
```{r echo = FALSE}
x <- "Paris in the the spring?"
y <- "Not Paris in the spring!"
hl_diff(x, y) |>
as_svg(600, 80) |>
cat(file = "man/figures/example-strdiff-3.svg")
```
Levenshtein's edit distance naturally applies to strings, but `hl_diff()` can
visualise the difference between arbitrary objects by first converting them
to a string representation. Coercion to a string is controlled by the
`coerce` argument, and defaults to the output if the objects were `print()`ed.
In this example, the difference between the `mean()` and `median()` function
definitions is highlighted.
```{r eval=FALSE}
hl_diff(mean, median, coerce = 'print', sep = " ")
```
```{r echo=FALSE}
hl_diff(mean, median, coerce = 'print', sep = " ") |>
as_svg(600, 200) |>
cat(file = "man/figures/example-strdiff-4.svg")
```
## Highlight regular expression matches in objects with `hl_grep()`
`hl_grep()` highlights the regular expression matches within a string or
objects coerced into a string representation.
#### Highlight regular expression matches in a character string
```{r eval = FALSE}
txt <- "Among the few possessions he left to his heirs was a set of
Encyclopedia Britannica in storage at the Lindbergh Palace Hotel under
the names Ari and Uzi Tenenbaum. No-one spoke at the funeral, and
Father Petersen's leg had not yet mended, but it was agreed among them
that Royal would have found the event to be most satisfactory.
[Chas, now wearing a black Adidas tracksuit, nods to his sons]"
hl_grep(txt, "event.*satisfactory", coerce = 'character')
```
```{r echo = FALSE}
txt <- "Among the few possessions he left to his heirs was a set of
Encyclopedia Britannica in storage at the Lindbergh Palace Hotel under
the names Ari and Uzi Tenenbaum. No-one spoke at the funeral, and
Father Petersen's leg had not yet mended, but it was agreed among them
that Royal would have found the event to be most satisfactory.
[Chas, now wearing a black Adidas tracksuit, nods to his sons]"
hl_grep(txt, "event.*satisfactory", coerce = 'character')|>
as_svg(600, 200) |>
cat(file = "man/figures/example-hlgrep-1.svg")
```
#### Highlight regular expression matches within an object
Other R objects (functions, lists, data.frames, etc) can also be highlighted
with regular expressions. How an object is coerced into string representation is
controlled by the `coerce` argument.
In this example, the function body for `mode()` is searched for the word `switch`:
```{r eval = FALSE}
hl_grep(mode, 'switch')
```
```{r echo = FALSE}
hl_grep(mode, 'switch') |>
as_svg(600, 250) |>
cat(file = "man/figures/example-hlgrep-2.svg")
```
# Animated SVG
Multiple *emphatic* objects may be rendered to an svg animation using `as_svg_anim()`
```{r eval = FALSE}
objs <- list(
hl_grep("hello", "there"),
hl_grep("goodbye", "good boy")
)
svg <- as_svg_anim(objs, width = 600, height = 300, duration = 2,
playback = 'infinite', font_size = "2em")
```
```{r echo = FALSE}
objs <- list(
hl_diff("hello", "there"),
hl_diff("goodbye", "good boy")
)
svg <- as_svg_anim(objs, width = 600, height = 100, duration = 2,
playback = 'infinite', font_size = "2em")
writeLines(svg, "man/figures/example-svg-anim.svg")
```
## Options
* `hl_opts()` create a named list of default options accepted by the functions
in this package
* `hl_adjust()` to adjust options after creation.
* These options are initialised at package start time using `Sys.getenv()`.
Set these values as environment variables in your `.Rprofile` to save
your preferred settings across different sessions. e.g.
* `Sys.setenv(HL_NA = "")` prior to loading package or in `.Rprofile`
* `options(HL_NA = ".")` at any time
| Option | Description |
|:-----------|:------------------|
| `HL_NA` | String to use for NA values. Default "NA" |
| `HL_FULL_COLOUR` | Should full colour ANSI codes be used when outputting to the console? Default: FALSE on Rstudio, but TRUE on all other R consoles |
| `HL_TEXT_MODE` | How to handle text if no text colour has been explicitly specified by the user |
| | `"contrast"` (default) automatically select a colour which contrasts with the background |
| | `"asis"` do not change the colour from the console's default |
| | `"remove"` remove all text without a user-defined colour |
| `HL_TEXT_CONTRAST` | When `text_mode = "contrast"` this numeric value (in range [0, 1]) adjusts the visibility of the text. Default: 1 (high contrast) |
| `HL_GREP_COL` |The fill colour to use with `hl_grep()` if no colour is specified. Default: "#0F19F0"|
| `HL_SUB_COL`, `HL_INS_COL`, `HL_DEL_COL` | the default colours to use with `hl_diff()` for substitution, insertion and deletion (respectively). |
## Vignettes
See the [online documentation](https://coolbutuseless.github.io/package/emphatic/index.html) for
vignettes and more examples.
* [Highlighting data.frames](https://coolbutuseless.github.io/package/emphatic/articles/aaa-data-frames.html)
* Specifying rows, columns and colours
* [Specifying rows](https://coolbutuseless.github.io/package/emphatic/articles/specify-rows.html)
* [Specifying columns](https://coolbutuseless.github.io/package/emphatic/articles/specify-columns.html)
* [Specifying colours](https://coolbutuseless.github.io/package/emphatic/articles/specify-colours.html)
* Worked Examples
* [Space Shuttle O-ring dataset - Challenger Disaster](https://coolbutuseless.github.io/package/emphatic/articles/challenger.html)
```{r echo = FALSE}
knitr::knit_exit()
```