Text annotations plot type

Description

Type function for adding text annotations to a plot at the specified (x,y) coordinates.

Usage

type_text(
  labels = NULL,
  labeller = NULL,
  adj = NULL,
  pos = NULL,
  offset = 0.5,
  family = NULL,
  font = NULL,
  vfont = NULL,
  xpd = NULL,
  srt = 0,
  repel = FALSE,
  clim = c(0.5, 2.5)
)

Arguments

labels	Character vector of length 1 or the same length as the number of x,y coordinates. If left as NULL, then the labels will automatically inherit the corresponding y values. Can also be supplied as a top-level tinyplot argument, which additionally supports non-standard evaluation against data and takes precedence if both are given. See Examples.
labeller	A formatting function, convenience string, or dictionary (named vector or list) passed to tinylabel for formatting or relabelling the labels. Useful for ensuring that the text labels match the formatting of an axis, e.g. labeller = “%” to display the labels as percentages. Default is NULL, i.e. no formatting. See Examples.
adj	one or two values in \([0, 1]\) which specify the x (and optionally y) adjustment (‘justification’) of the labels, with 0 for left/bottom, 1 for right/top, and 0.5 for centered. On most devices values outside \([0, 1]\) will also work. See below.
pos	a position specifier for the text. If specified this overrides any adj value given. Values of 1, 2, 3 and 4, respectively indicate positions below, to the left of, above and to the right of the specified (x,y) coordinates.
offset	when pos is specified, this value controls the distance (‘offset’) of the text label from the specified coordinate in fractions of a character width.
family	The name of a font family. Default of NULL means that the family will be the same as the main plot text, following par. Note that if a family argument is provided, then vfont (below) will automatically be ignored.
font	Integer giving the font face to be used, following par. On most devices, the mapping is: 1 = regular, 2 = bold, 3 = italic, 4 = bold italic, and 5 = symbol.
vfont	NULL for the current font family, or a character vector of length 2 for Hershey vector fonts. The first element of the vector selects a typeface and the second element selects a style. Ignored if labels is an expression.
xpd	Logical value or NA denoting text clipping behaviour, following par.
srt	Numeric giving the desired string rotation in degrees.
repel	Logical or numeric controlling automatic repulsion of overlapping text labels. The default FALSE draws the labels at their exact (x,y) coordinates. TRUE nudges overlapping labels apart using a force-directed algorithm (labels are pushed off each other and then sprung back toward their original positions). A numeric value does the same but additionally enforces that much minimum padding (in user coordinates) between labels. Works best with the default centered text placement (i.e. without pos). Caveat: The repulsion logic currently operates within each group rather than across groups. So the text of different groups may still overlap. See Examples.
clim	Numeric giving the lower and upper limits of the character expansion (cex) normalization for bubble charts.

Examples

library("tinyplot")

# simplest case (no labels), will auto revert to y labels
tinyplot(1:12, type = "text")

# pass explicit `labels` arg if you want specific text
tinyplot(1:12, type = "text", labels = month.abb)

# you can also use a labeller function (passed to `tinylabel`) to
# customize
tinyplot(1:12, type = "text", labels = month.abb, labeller = toupper)

# tip: use `xpd = NA` to avoid clipping text at the plot region
tinyplot(1:12, type = "text", labels = month.name, xpd = NA)

# for advanced customization, it's safer to pass args through `type_text()`
tinyplot(
  1:12,
  type = type_text(
  labels = month.abb,
  family = "HersheyScript",
  srt = -20)
)

# some formula + data.frame examples...

mt = transform(mtcars[1:20,], cyl = factor(cyl), model = rownames(mtcars[1:20,]))

# as a top-level argument, `labels` supports non-standard evaluation, so a
# bare column name is resolved against `data` (just like the plot variables)

# tinyplot(mpg ~ wt, data = mt, type = type_text(labels = mt$model))
tinyplot(mpg ~ wt, data = mt, type = "text", labels = model) # same

# tip: use `repel = TRUE` to automatically nudge overlapping labels apart
tinyplot(
  mpg ~ wt, data = mt,
  type = "text", labels = model,
  repel = TRUE, xpd = NA
)

# limitation: `repel` logic currently works per group, so grouped text data
# may still overlap
tinyplot(
  mpg ~ wt | cyl, data = mt,
  type = "text", labels = model,
  repel = TRUE, xpd = NA
)

# an advantage of the top-level `labels` approach is that data subsetting and 
# sanitizing ops pass through automatically
tinyplot(hp ~ wt, data = mt)
tinyplot_add(subset = carb==2, col = "red", pch = 16)
tinyplot_add(subset = carb==2, col = "red", type = "text", labels = model, pos = 4)

# fancier plot that combines a theme and some other customizations
tinyplot(
  mpg ~ hp | cyl,
  data = mt,
  legend = list(title = "Cylinders"),
  theme = "web"
)
tinyplot_add(
  labels = model,
  type = type_text(
    family = "HersheySans",
    font = 2,
    pos = 4,
    repel = TRUE,
    xpd = NA
  )
)