plot_charmap {ds4psy}

Plot a character map as a tile plot with text labels.

Description

plot_charmap plots a character map and some aesthetics as a tile plot with text labels (using ggplot2).

Usage

plot_charmap(
  x = NA,
  file = "",
  lbl_tiles = TRUE,
  col_lbl = "black",
  angle = 0,
  cex = 3,
  fontface = 1,
  family = "sans",
  col_bg = "grey80",
  borders = FALSE,
  border_col = "white",
  border_size = 0.5
)

Arguments

x

A character map, as generated by map_text_coord or map_text_regex (as df). Alternatively, some 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_tiles

Add character labels to tiles? Default: lbl_tiles = TRUE (i.e., show labels).

col_lbl

Default color of text labels (unless specified as a column col_fg of x). Default: col_lbl = "black".

angle

Default angle of text labels (unless specified as a column of x). Default: angle = 0.

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_bg

Default color to fill background tiles (unless specified as a column col_bg of x). Default: col_bg = "grey80".

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_charmap is based on plot_chars. As it only contains the plotting-related parts, it assumes a character map generated by map_text_regex as input.

The plot generated by plot_charmap is character-based: Individual characters are plotted at equidistant x-y-positions and aesthetic variables are used for text labels and tile fill colors.

Value

A plot generated by ggplot2.

See Also

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

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

Examples

# (0) Prepare: 
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))  

# (1) From character map:
# (a) simple: 
cm_1 <- map_text_coord(x = ts, flip_y = TRUE)
plot_charmap(cm_1)

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

# (2) Alternative inputs:     
# (a) From text string(s):
plot_charmap(ts)

# (b) From user input:
# plot_charmap()  # (enter text in Console)
 
# (c) 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")

# plot_charmap(file = "test.txt")

# unlink("test.txt")  # clean up (by deleting file).