plot_text: Plot text characters (from file or user input).

Description

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

Usage

plot_text(
  x = NA,
  file = "",
  char_bg = " ",
  lbl_tiles = TRUE,
  lbl_rotate = FALSE,
  cex = 3,
  fontface = 1,
  family = "sans",
  col_lbl = "black",
  col_bg = "white",
  pal = pal_ds4psy[1:5],
  pal_extend = TRUE,
  case_sense = FALSE,
  borders = TRUE,
  border_col = "white",
  border_size = 0.5
)

Value

An invisible data frame describing the plot.

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 scan user input (entering text in 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 "/").
char_bg: Character used as background. Default: char_bg = " ". If char_bg = NA, the most frequent character is used.
lbl_tiles: Add character labels to tiles? Default: lbl_tiles = TRUE (i.e., show labels).
lbl_rotate: Rotate character labels? Default: lbl_rotate = FALSE (i.e., no rotation).
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".
col_lbl: Color of text labels. Default: col_lbl = "black" (if lbl_tiles = TRUE).
col_bg: Color of char_bg (if defined), or the most frequent character in text (typically " "). Default: col_bg = "white".
pal: Color palette for filling tiles of text (used in order of character frequency). Default: pal = pal_ds4psy[1:5] (i.e., shades of Seeblau).
pal_extend: Boolean: Should pal be extended to match the number of different characters in text? Default: pal_extend = TRUE. If pal_extend = FALSE, only the tiles of the length(pal) most frequent characters will be filled by the colors of pal.
case_sense: Boolean: Distinguish lower- vs. uppercase characters? Default: case_sense = FALSE.
borders: Boolean: Add borders to tiles? Default: borders = TRUE (i.e., use borders).
border_col: Color of borders (if borders = TRUE). Default: border_col = "white".
border_size: Size of borders (if borders = TRUE). Default: border_size = 0.5.

Details

plot_text blurs the boundary between a text and its graphical representation by adding visual options for coloring characters based on their frequency counts. (Note that plot_chars provides additional support for matching regular expressions.)

plot_text is character-based: Individual characters are plotted at equidistant x-y-positions with color settings for text labels and tile fill colors.

By default, the color palette pal (used for tile fill colors) is scaled to indicate character frequency.

plot_text invisibly returns a description of the plot (as a data frame).

Examples

Run this code

# (A) From text string(s):
plot_text(x = c("Hello", "world!"))
plot_text(x = c("Hello world!", "How are you today?"))

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

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

# plot_text(file = "test.txt")

## Set colors, pal_extend, and case_sense:
# cols <- c("steelblue", "skyblue", "lightgrey")
# cols <- c("firebrick", "olivedrab", "steelblue", "orange", "gold")
# plot_text(file = "test.txt", pal = cols, pal_extend = TRUE)
# plot_text(file = "test.txt", pal = cols, pal_extend = FALSE)
# plot_text(file = "test.txt", pal = cols, pal_extend = FALSE, case_sense = TRUE)

## Customize text and grid options:
# plot_text(file = "test.txt", col_lbl = "darkblue", cex = 4, family = "sans", fontface = 3,
#           pal = "gold1", pal_extend = TRUE, border_col = NA)
# plot_text(file = "test.txt", family = "serif", cex = 6, lbl_rotate = TRUE,  
#           pal = NA, borders = FALSE)
# plot_text(file = "test.txt", col_lbl = "white", pal = c("green3", "black"),
#           border_col = "black", border_size = .2)

## Color ranges:
# plot_text(file = "test.txt", pal = c("red2", "orange", "gold"))
# plot_text(file = "test.txt", pal = c("olivedrab4", "gold"))

# unlink("test.txt")  # clean up.
 
# \donttest{
## (B) From text file (in subdir):
# plot_text(file = "data-raw/txt/hello.txt")  # requires txt file
# plot_text(file = "data-raw/txt/ascii.txt", cex = 5, 
#           col_bg = "grey", char_bg = "-")
         
## (C) From user input:
# plot_text()  # (enter text in Console)
# }