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

View source: R/plot_fun.R

plot_charsR 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.

See Also

plot_charmap for plotting character maps; plot_text for plotting characters and color tiles by frequency; map_text_coord for mapping text to a table of character coordinates; map_text_regex for mapping text to a character table and matching patterns; read_ascii for reading text inputs into a character string; pal_ds4psy for default color palette.

Other plot functions: plot_charmap(), plot_fn(), plot_fun(), plot_n(), plot_text(), plot_tiles(), theme_clean(), theme_ds4psy(), theme_empty()

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.