map_text_regex {ds4psy}

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
)

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.

Value

A data frame describing a plot.

See Also

map_text_coord for mapping text to a table of character coordinates; plot_charmap for plotting character maps; plot_chars for creating and plotting character maps; plot_text for plotting characters and color tiles by frequency; read_ascii for reading text inputs into a character string.

Other text objects and functions: Umlaut, capitalize(), caseflip(), cclass, chars_to_text(), collapse_chars(), count_chars_words(), count_chars(), count_words(), invert_rules(), l33t_rul35, map_text_chars(), map_text_coord(), metachar, read_ascii(), text_to_chars(), text_to_sentences(), text_to_words(), transl33t(), words_to_text()

Examples

## (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).