plot_chars: Plot text characters (from file or user input) and match...
In ds4psy: Data Science for Psychologists

plot_chars

R Documentation

Plot text characters (from file or user input) and match patterns.

Description

plot_chars parses text (from a file or user input) into a table and then plots its individual characters as a tile plot (using ggplot2).

Usage

plot_chars(
  x = NA,
  file = "",
  lbl_hi = NA,
  lbl_lo = NA,
  bg_hi = NA,
  bg_lo = "[[:space:]]",
  lbl_rotate = NA,
  case_sense = TRUE,
  lbl_tiles = TRUE,
  angle_fg = c(-90, 90),
  angle_bg = 0,
  col_lbl = "black",
  col_lbl_hi = pal_ds4psy[[1]],
  col_lbl_lo = pal_ds4psy[[9]],
  col_bg = pal_ds4psy[[7]],
  col_bg_hi = pal_ds4psy[[4]],
  col_bg_lo = "white",
  col_sample = FALSE,
  rseed = NA,
  cex = 3,
  fontface = 1,
  family = "sans",
  borders = FALSE,
  border_col = "white",
  border_size = 0.5
)

Arguments

`x`	The text to plot (as a character vector). Different elements denote different lines of text. If `x = NA` (as per default), the `file` argument is used to read a text file or user input from the Console.
`file`	A text file to read (or its path). If `file = ""` (as per default), `scan` is used to read user input from the Console. If a text file is stored in a sub-directory, enter its path and name here (without any leading or trailing "." or "/").
`lbl_hi`	Labels to highlight (as regex). Default: `lbl_hi = NA`.
`lbl_lo`	Labels to de-emphasize (as regex). Default: `lbl_lo = NA`.
`bg_hi`	Background tiles to highlight (as regex). Default: `bg_hi = NA`.
`bg_lo`	Background tiles to de-emphasize (as regex). Default: `bg_lo = "[[:space:]]"`.
`lbl_rotate`	Labels to rotate (as regex). Default: `lbl_rotate = NA`.
`case_sense`	Boolean: Distinguish lower- vs. uppercase characters in pattern matches? Default: `case_sense = TRUE`.
`lbl_tiles`	Add character labels to tiles? Default: `lbl_tiles = TRUE` (i.e., show labels).
`angle_fg`	Angle(s) for rotating character labels matching the pattern of the `lbl_rotate` expression. Default: `angle_fg = c(-90, 90)`. If `length(angle_fg) > 1`, a random value in uniform `range(angle_fg)` is used for every character.
`angle_bg`	Angle(s) of rotating character labels not matching the pattern of the `lbl_rotate` expression. Default: `angle_bg = 0` (i.e., no rotation). If `length(angle_bg) > 1`, a random value in uniform `range(angle_bg)` is used for every character.
`col_lbl`	Default color of text labels. Default: `col_lbl = "black"`.
`col_lbl_hi`	Highlighting color of text labels. Default: `col_lbl_hi = pal_ds4psy[[1]]`.
`col_lbl_lo`	De-emphasizing color of text labels. Default: `col_lbl_lo = pal_ds4psy[[9]]`.
`col_bg`	Default color to fill background tiles. Default: `col_bg = pal_ds4psy[[7]]`.
`col_bg_hi`	Highlighting color to fill background tiles. Default: `col_bg_hi = pal_ds4psy[[4]]`.
`col_bg_lo`	De-emphasizing color to fill background tiles. Default: `col_bg_lo = "white"`.
`col_sample`	Boolean: Sample color vectors (within category)? Default: `col_sample = FALSE`.
`rseed`	Random seed (number). Default: `rseed = NA` (using random seed).
`cex`	Character size (numeric). Default: `cex = 3`.
`fontface`	Font face of text labels (numeric). Default: `fontface = 1`, (from 1 to 4).
`family`	Font family of text labels (name). Default: `family = "sans"`. Alternative options: "sans", "serif", or "mono".
`borders`	Boolean: Add borders to tiles? Default: `borders = FALSE` (i.e., no borders).
`border_col`	Color of tile borders. Default: `border_col = "white"`.
`border_size`	Size of tile borders. Default: `border_size = 0.5`.

Details

plot_chars blurs the boundary between a text and its graphical representation by combining options for matching patterns of text with visual features for displaying characters (e.g., their color or orientation).

plot_chars is based on plot_text, but provides additional support for detecting and displaying characters (i.e., text labels, their orientation, and color options) based on matching regular expression (regex).

Internally, plot_chars is a wrapper that calls (1) map_text_regex for creating a character map (allowing for matching patterns for some aesthetics) and (2) plot_charmap for plotting this character map.

However, in contrast to plot_charmap, plot_chars invisibly returns a description of the plot (as a data frame).

The plot generated by plot_chars is character-based: Individual characters are plotted at equidistant x-y-positions and the aesthetic settings provided for text labels and tile fill colors.

Five regular expressions and corresponding color and angle arguments allow identifying, marking (highlighting or de-emphasizing), and rotating those sets of characters (i.e, their text labels or fill colors). that match the provided patterns.

Value

An invisible data frame describing the plot.

Examples

# (A) From text string(s):
plot_chars(x = c("Hello world!", "Does this work?", 
                 "That's good.", "Please carry on..."))

# (B) From user input:
# plot_chars()  # (enter text in Console)

# (C) From text file:
# Create and use a text file: 
# cat("Hello world!", "This is a test file.", 
#     "Can you see this text?", 
#     "Good! Please carry on...", 
#     file = "test.txt", sep = "\n")

# plot_chars(file = "test.txt")  # default
# plot_chars(file = "test.txt", lbl_hi = "[[:upper:]]", lbl_lo = "[[:punct:]]", 
#            col_lbl_hi = "red", col_lbl_lo = "blue")
 
# plot_chars(file = "test.txt", lbl_hi = "[aeiou]", col_lbl_hi = "red", 
#            col_bg = "white", bg_hi = "see")  # mark vowels and "see" (in bg)
# plot_chars(file = "test.txt", bg_hi = "[aeiou]", col_bg_hi = "gold")  # mark (bg of) vowels

## Label options:
# plot_chars(file = "test.txt", bg_hi = "see", lbl_tiles = FALSE)
# plot_chars(file = "test.txt", cex = 5, family = "mono", fontface = 4, lbl_angle = c(-20, 20))

## Note: plot_chars() invisibly returns a description of the plot (as df):
# tb <- plot_chars(file = "test.txt", lbl_hi = "[aeiou]", lbl_rotate = TRUE)
# head(tb)

# unlink("test.txt")  # clean up (by deleting file).


## (B) From text file (in subdir):
# plot_chars(file = "data-raw/txt/hello.txt")  # requires txt file
# plot_chars(file = "data-raw/txt/ascii.txt", lbl_hi = "[2468]", bg_lo = "[[:digit:]]", 
#            col_lbl_hi = "red", cex = 10, fontface = 2)
           
## (C) User input:
# plot_chars()  # (enter text in Console)

ds4psy documentation built on Sept. 15, 2023, 9:08 a.m.