map_text_regex: Map text to character table (allowing for matching patterns).

Description

map_text_regex parses text (from a file or user input) into a data frame that contains a row for each character of x.

Usage

map_text_regex(
  x = NA,
  file = "",
  lbl_hi = NA,
  lbl_lo = NA,
  bg_hi = NA,
  bg_lo = "[[:space:]]",
  lbl_rotate = NA,
  case_sense = TRUE,
  lbl_tiles = TRUE,
  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,
  angle_fg = c(-90, 90),
  angle_bg = 0
)

Value

A data frame describing a plot.

Arguments

x: The text to map or 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: Are character labels shown? This enables pattern matching for (fg) color and angle aesthetics. Default: lbl_tiles = TRUE (i.e., show labels).
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).
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.

Details

map_text_regex allows for regular expression (regex) to match text patterns and create corresponding variables (e.g., for color or orientation).

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.

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.

map_text_regex returns a plot description (as a data frame). Using this output as an input to plot_charmap plots text in a character-based fashion (i.e., individual characters are plotted at equidistant x-y-positions). Together, both functions replace the over-specialized plot_chars and plot_text functions.

Examples

Run this code

## (1) From text string(s): 
ts <- c("Hello world!", "This is a test to test this splendid function",
        "Does this work?", "That's good.", "Please carry on.")
sum(nchar(ts))

# (a) simple use:
map_text_regex(ts) 

# (b) matching patterns (regex):
map_text_regex(ts, lbl_hi = "\\b\\w{4}\\b", bg_hi = "[good|test]",
               lbl_rotate = "[^aeiou]", angle_fg = c(-45, +45))

## (2) From user input:
# map_text_regex()  # (enter text in Console)
 
## (3) From text file:
# cat("Hello world!", "This is a test file.",
#     "Can you see this text?",
#     "Good! Please carry on...",
#     file = "test.txt", sep = "\n")
# 
# map_text_regex(file = "test.txt")  # default
# map_text_regex(file = "test.txt", lbl_hi = "[[:upper:]]", lbl_lo = "[[:punct:]]",
#                col_lbl_hi = "red", col_lbl_lo = "blue")
# 
# map_text_regex(file = "test.txt", lbl_hi = "[aeiou]", col_lbl_hi = "red",
#                col_bg = "white", bg_hi = "see")  # mark vowels and "see" (in bg)
# map_text_regex(file = "test.txt", bg_hi = "[aeiou]", col_bg_hi = "gold")  # mark (bg of) vowels
# 
# # Label options:
# map_text_regex(file = "test.txt", bg_hi = "see", lbl_tiles = FALSE)
# map_text_regex(file = "test.txt", angle_bg = c(-20, 20))
# 
# unlink("test.txt")  # clean up (by deleting file).