type_text() (#281)

* type_text()

* type_text() respects `cex`

* text legend color

* type_text() snapshot tests + allow single label

* legend character for type_text()

* type_text() doc

NAMESPACE

@@ -37,6 +37,7 @@ export(type_segments)
 export(type_spineplot)
 export(type_spline)
 export(type_summary)
+export(type_text)
 export(type_vline)
 importFrom(grDevices,adjustcolor)
 importFrom(grDevices,as.raster)

NEWS.md

@@ -60,6 +60,7 @@ New plot types:
     (#252 @vincentarelbundock, @zeileis, and @grantmcdermott)
     - `type_rug()` (shortcut: `"rug"`) adds a rug to an existing plot. (#276
     @grantmcdermott)
+    - `type_text()` (shortcut: `"text"`) adds text annotations. (@vincentarelbundock)
   - Models:
     - `type_glm()` (shortcut: `"glm"`) (@vincentarelbundock)
     - `type_lm()` (shortcut: `"lm"`) (@vincentarelbundock)

R/by_aesthetics.R

@@ -123,7 +123,9 @@ by_col = function(ngrps = 1L, col = NULL, palette = NULL, gradient = NULL, order
 
 by_pch = function(ngrps, type, pch = NULL) {
   no_pch = FALSE
-  if (!type %in% c("p", "b", "o", "pointrange", "errorbar", "boxplot", "qq")) {
+  if (identical(type, "text")) {
+    pch <- rep(15, ngrps)
+  } else if (!type %in% c("p", "b", "o", "pointrange", "errorbar", "boxplot", "qq")) {
     no_pch = TRUE
     pch = NULL
 

R/sanitize.R

@@ -17,7 +17,7 @@ sanitize_type = function(type, x, y, dots) {
     "abline", "area", "boxplot", "errorbar", "function", "glm", "hist",
     "histogram", "hline", "j", "jitter", "lines", "lm", "loess", "pointrange",
     "points", "polygon", "polypath", "qq", "rect", "ribbon", "ridge", "rug",
-    "segments", "spineplot", "spline", "vline"
+    "segments", "spineplot", "spline", "text", "vline"
   )
   assert_choice(type, types, null.ok = TRUE)
 
@@ -60,6 +60,7 @@ sanitize_type = function(type, x, y, dots) {
     "segments"   = type_segments,
     "spineplot"  = type_spineplot,
     "spline"     = type_spline,
+    "text"       = type_text,
     "vline"      = type_vline,
     type           # default case
   )

R/tinyplot.R

@@ -100,6 +100,7 @@
 #'       - `"rect"` / [`type_rect()`]: Draws rectangles; requires `xmin`, `xmax`, `ymin`, and `ymax`.
 #'       - `"ribbon"` / [`type_ribbon()`]: Creates a filled area between `ymin` and `ymax`.
 #'       - `"segments"` / [`type_segments()`]: Draws line segments between pairs of points.
+#'       - `"text"` / [`type_text()`]: Add text annotations.
 #'     - Visualizations:
 #'       - `"boxplot"` / [`type_boxplot()`]: Creates a box-and-whisker plot.
 #'       - `"density"`: Plots the density estimate of a variable.
@@ -118,7 +119,7 @@
 #'       - [`type_abline()`]: line(s) with intercept and slope.
 #'       - [`type_hline()`]: horizontal line(s).
 #'       - [`type_vline()`]: vertical line(s).
-#'       - [`type_function()`]: arbitrary function. 
+#'       - [`type_function()`]: arbitrary function.
 #'       - [`type_summary()`]: summarize `y` by unique values of `x`.
 #' @param xmin,xmax,ymin,ymax minimum and maximum coordinates of relevant area
 #'   or interval plot types. Only used when the `type` argument is one of
@@ -500,11 +501,12 @@
 #'
 #' # It's possible to customize the look of your plots by setting graphical
 #' # parameters (e.g., via `(t)par`)... But a more convenient way is to just use
-#' # built-in themes (see `?tinytheme`). 
+#' # built-in themes (see `?tinytheme`).
 #'
 #' tinytheme("clean2")
 #' tinyplot(
-#'   Temp ~ Day | Month, data = aq,
+#'   Temp ~ Day | Month,
+#'   data = aq,
 #'   type = "b",
 #'   alpha = 0.5,
 #'   main = "Daily temperatures by month",
@@ -1170,6 +1172,7 @@ tinyplot.default = function(
       ixmax = idata[[ii]]$xmax
       iymin = idata[[ii]]$ymin
       iymax = idata[[ii]]$ymax
+      ilabels = idata[[ii]][["labels"]]
 
       if (isTRUE(by_continuous)) {
         icol = idata[[ii]]$col
@@ -1230,6 +1233,7 @@ tinyplot.default = function(
           iy = iy,
           iymax = iymax,
           iymin = iymin,
+          ilabels = ilabels,
           iz = iz,
           cex = cex,
           dots = dots,

R/type_text.R

@@ -0,0 +1,49 @@
+#' Text annotations plot type
+#'
+#' @description Type function for adding text annotations to a plot. This function allows
+#' you to draw text at specified (x,y) coordinates. If no label is provided, the y-values
+#' will be used as the text labels.
+#'
+#' @param labels Character vector of the same length as the number of x,y coordinates.
+#' @param font Font to be used, following [graphics::par()]
+#' @inheritParams graphics::text
+#' @examples
+#'
+#' tinyplot(mpg ~ hp | factor(cyl),
+#'   data = mtcars,
+#'   type = type_text(
+#'     labels = row.names(mtcars),
+#'     font = 2,
+#'     adj = 0))
+#'
+#' @export
+type_text = function(labels, adj = NULL, pos = NULL, offset = 0.5, vfont = NULL, font = NULL) {
+  out = list(
+    draw = draw_text(adj = adj, pos = pos, offset = offset, vfont = vfont, font = font),
+    data = data_text(labels = labels),
+    name = "text"
+  )
+  class(out) = "tinyplot_type"
+  return(out)
+}
+
+data_text = function(labels) {
+  fun = function(datapoints, ...) {
+    assert_character(labels, name = "labels")
+    if (length(labels) != 1 && length(labels) != nrow(datapoints)) {
+      msg <- sprintf("`labels` must be of length 1 or %s.", nrow(datapoints))
+      stop(msg, call. = FALSE)
+    }
+    datapoints$labels = labels
+    out = list(datapoints = datapoints)
+    return(out)
+  }
+  return(fun)
+}
+
+draw_text = function(adj = NULL, pos = NULL, offset = 0.5, vfont = NULL, font = NULL) {
+  fun = function(ix, iy, ilabels, icol, cex, ...) {
+    text(x = ix, y = iy, labels = ilabels, col = icol, adj = adj, pos = pos, offset = offset, vfont = vfont, font = font, cex = cex)
+  }
+}
+

altdoc/quarto_website.yml

@@ -59,6 +59,8 @@ website:
               file: man/type_rect.qmd
             - text: type_ribbon
               file: man/type_ribbon.qmd
+            - text: type_text
+              file: man/type_text.qmd
             - text: type_segments
               file: man/type_segments.qmd
           - section: Visualizations