plot_text {ds4psy}

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
)

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

Value

An invisible data frame describing the plot.

See Also

plot_charmap for plotting character maps; plot_chars for creating and plotting character maps; 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 parsing text from file or user input; pal_ds4psy for default color palette.

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

Examples

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

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