feat: add composite marks: errorbar, significance, lollipop, dumbbell

- mark_errorbar: wraps geom_errorbar/geom_errorbarh (VL Errorbar)
  with vertical/horizontal orientation dispatch
- mark_significance: syntax-sugar combining geom_segment + geom_text
  for statistical significance brackets and labels
  Auto-computes y_positions from data range
  Documented with equivalent pipeline expansion
- mark_lollipop: syntax-sugar combining geom_segment + geom_point
  for lollipop charts with customizable stem/point styling
- mark_dumbbell: syntax-sugar combining geom_segment + 2x geom_point
  for before/after comparison charts
- All registered as unsupported on plotit_composite
- Tests: 12 new tests (3 per mark)
- All Rd files auto-generated by devtools::document()

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: zorrooz

NAMESPACE

@@ -23,15 +23,19 @@ export(mark_boxplot)
 export(mark_corr)
 export(mark_density)
 export(mark_density_2d)
+export(mark_dumbbell)
+export(mark_errorbar)
 export(mark_hex)
 export(mark_histogram)
 export(mark_line)
+export(mark_lollipop)
 export(mark_map)
 export(mark_path)
 export(mark_point)
 export(mark_polygon)
 export(mark_rect)
 export(mark_rule)
+export(mark_significance)
 export(mark_smooth)
 export(mark_text)
 export(mark_violin)

R/mark.R

@@ -779,6 +779,322 @@ S7::method(mark_corr, plotit_class) <- function(
   )
 }
 
+# ---- mark_errorbar ----
+#' Error bar layer
+#'
+#' Adds error bars showing confidence intervals, standard errors,
+#' or other variability measures. Data should include columns for
+#' `ymin`/`ymax` (vertical) or `xmin`/`xmax` (horizontal).
+#'
+#' @param plot A plotit object
+#' @param mapping Optional new aesthetics (must include `ymin`/`ymax`
+#'   or `xmin`/`xmax`)
+#' @param data Optional data for this layer
+#' @param position Position adjustment.
+#' @param width Width of the error bar caps (default 0.5).
+#' @param orientation `"vertical"` (default) or `"horizontal"`.
+#' @param rasterize If `TRUE`, rasterize via `ggrastr::rasterise()`.
+#' @param rasterize_dpi DPI for rasterization (default 300).
+#' @param rasterize_dev Graphics device for rasterization (default `"cairo"`).
+#' @param ... Other arguments passed to the underlying geom
+#' @return Modified plotit object
+#' @references
+#' Vega-Lite: \href{https://vega.github.io/vega-lite/docs/errorbar.html}{Errorbar} (composite mark)
+#' @examples
+#' df <- data.frame(
+#'   x = c("A", "B"), y = c(10, 20), ymin = c(8, 18), ymax = c(12, 22))
+#' plotit(df, encode(x = x, y = y, ymin = ymin, ymax = ymax)) |>
+#'   mark_errorbar(width = 0.3)
+#' @export
+mark_errorbar <- S7::new_generic(
+  "mark_errorbar", "plot",
+  function(plot, mapping = NULL, data = NULL, position = NULL, ...,
+           width = 0.5, orientation = c("vertical", "horizontal"),
+           rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_errorbar, plotit_class) <- function(
+    plot, mapping = NULL, data = NULL, position = NULL, ...,
+    width = 0.5, orientation = c("vertical", "horizontal"),
+    rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+  orientation <- match.arg(orientation)
+  geom_fun <- if (orientation == "horizontal") {
+    ggplot2::geom_errorbarh
+  } else {
+    ggplot2::geom_errorbar
+  }
+  params <- rlang::list2(...)
+  params$width <- width
+  do.call(function(...) {
+    ._mark_impl(plot, mapping, data, position, geom_fun,
+                rasterize, rasterize_dpi, rasterize_dev, ...)
+  }, params)
+}
+
+# ---- mark_significance ----
+#' Significance annotation layer
+#'
+#' Adds statistical significance brackets and labels between groups.
+#' This is a **syntax-sugar composite mark** that combines
+#' `mark_rule` and `mark_text` internally.
+#'
+#' Equivalent expansion:
+#' \preformatted{
+#'   p |> mark_rule(x = comp$group1, xend = comp$group2,
+#'                  y = comp$y_position, yend = comp$y_position) |>
+#'        mark_text(x = midpoint, y = comp$y_position + y_offset,
+#'                  label = comp$label)
+#' }
+#'
+#' @param plot A plotit object
+#' @param comparisons A data frame with columns: `group1`, `group2`,
+#'   `label`, and optionally `y_position`. Character columns are
+#'   matched against the x-axis variable.
+#' @param y_position Numeric vector of y-positions for the brackets.
+#'   If omitted, auto-computed from data range.
+#' @param y_offset Text offset above the bracket line (default 0.5).
+#'   In data units.
+#' @param line_colour Colour for the bracket lines (default `"grey30"`).
+#' @param line_width Width of bracket lines (default 0.3).
+#' @param text_size Size of significance label text (default 3.5).
+#' @param tip_length Length of bracket end-tick lines (default 0.02
+#'   as fraction of x-axis range).
+#' @param ... Additional arguments passed to `mark_text()`
+#' @return Modified plotit object
+#' @examples
+#' df <- data.frame(group = c("A", "B", "C"), value = c(5, 8, 4))
+#' comp <- data.frame(
+#'   group1 = c("A", "A"), group2 = c("B", "C"),
+#'   label = c("**", "ns"))
+#' plotit(df, encode(x = group, y = value)) |>
+#'   mark_bar() |>
+#'   mark_significance(comp, y_position = c(9, 6))
+#' @export
+mark_significance <- S7::new_generic(
+  "mark_significance", "plot",
+  function(plot, comparisons, y_position = NULL, y_offset = NULL,
+           line_colour = "grey30", line_width = 0.3,
+           text_size = 3.5, tip_length = 0.02, ...) {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_significance, plotit_class) <- function(
+    plot, comparisons, y_position = NULL, y_offset = NULL,
+    line_colour = "grey30", line_width = 0.3,
+    text_size = 3.5, tip_length = 0.02, ...) {
+  if (!is.data.frame(comparisons)) {
+    cli::cli_abort("{.arg comparisons} must be a data frame.")
+  }
+  required <- c("group1", "group2", "label")
+  missing_cols <- setdiff(required, names(comparisons))
+  if (length(missing_cols) > 0) {
+    cli::cli_abort(
+      "{.arg comparisons} must have columns: {.val {required}}."
+    )
+  }
+  # Extract data range for auto y_position
+  d <- plot@gg$data
+  y_var <- rlang::eval_tidy(plot@gg$mapping$y, d)
+  y_range <- range(y_var, na.rm = TRUE)
+  y_span <- diff(y_range)
+  if (is.null(y_offset)) y_offset <- y_span * 0.02
+  # Auto-compute y_position if not provided
+  if (is.null(y_position)) {
+    y_position <- y_range[2] + y_span * 0.1 + seq_len(nrow(comparisons)) * y_span * 0.08
+  }
+  # Get x positions (handle factor/character group1/group2)
+  x_var <- rlang::eval_tidy(plot@gg$mapping$x, d)
+  x_levels <- if (is.factor(x_var)) levels(x_var) else sort(unique(as.character(x_var)))
+  x_positions <- seq_along(x_levels)
+  names(x_positions) <- x_levels
+  # Draw brackets
+  for (i in seq_len(nrow(comparisons))) {
+    g1 <- as.character(comparisons$group1[i])
+    g2 <- as.character(comparisons$group2[i])
+    x1 <- if (g1 %in% names(x_positions)) x_positions[[g1]] else as.numeric(g1)
+    x2 <- if (g2 %in% names(x_positions)) x_positions[[g2]] else as.numeric(g2)
+    if (is.na(x1) || is.na(x2)) next
+    y_pos <- if (i <= length(y_position)) y_position[i] else y_position[1] + (i - 1) * y_span * 0.08
+    # Bracket line
+    geome <- ggplot2::geom_segment(
+      mapping = encode(x = x1, xend = x2, y = y_pos, yend = y_pos),
+      colour = line_colour, linewidth = line_width
+    )
+    plot <- .add_geom(plot, geome)
+    # Left tick
+    tick_len <- if (is.factor(x_var)) tip_length * length(x_levels) else tip_length * diff(range(x_positions))
+    geome <- ggplot2::geom_segment(
+      mapping = encode(
+        x = x1, xend = x1, y = y_pos - tick_len, yend = y_pos
+      ),
+      colour = line_colour, linewidth = line_width
+    )
+    plot <- .add_geom(plot, geome)
+    # Right tick
+    geome <- ggplot2::geom_segment(
+      mapping = encode(
+        x = x2, xend = x2, y = y_pos - tick_len, yend = y_pos
+      ),
+      colour = line_colour, linewidth = line_width
+    )
+    plot <- .add_geom(plot, geome)
+    # Label
+    geome <- ggplot2::geom_text(
+      mapping = encode(
+        x = (x1 + x2) / 2, y = y_pos + y_offset, label = comparisons$label[i]
+      ),
+      size = text_size, ...
+    )
+    plot <- .add_geom(plot, geome)
+  }
+  plot
+}
+
+# ---- mark_lollipop ----
+#' Lollipop chart layer
+#'
+#' Creates a lollipop chart: a point anchored by a stem to a reference
+#' line. This is a **syntax-sugar composite mark** combining
+#' `geom_segment` and `geom_point`.
+#'
+#' Equivalent expansion:
+#' \preformatted{
+#'   p |> mark_rule(x = x, xend = x, y = ref, yend = y) |>
+#'        mark_point(x = x, y = y)
+#' }
+#'
+#' @param plot A plotit object
+#' @param mapping Optional new aesthetics
+#' @param data Optional data for this layer
+#' @param stem_colour Colour for the stem lines (default `"grey50"`).
+#' @param stem_width Line width for stems (default 0.5).
+#' @param point_size Point size for the lollipop head (default 3).
+#' @param ... Other arguments passed to `mark_point()`
+#' @return Modified plotit object
+#' @examples
+#' df <- data.frame(cat = LETTERS[1:5], val = c(3, 7, 2, 9, 5))
+#' plotit(df, encode(x = cat, y = val)) |>
+#'   mark_lollipop(point_size = 4, stem_colour = "grey70")
+#' @export
+mark_lollipop <- S7::new_generic(
+  "mark_lollipop", "plot",
+  function(plot, mapping = NULL, data = NULL,
+           stem_colour = "grey50", stem_width = 0.5,
+           point_size = 3, ...) {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_lollipop, plotit_class) <- function(
+    plot, mapping = NULL, data = NULL,
+    stem_colour = "grey50", stem_width = 0.5,
+    point_size = 3, ...) {
+  d <- data %||% plot@gg$data
+  m <- mapping %||% plot@gg$mapping
+  # Extract x and y from mapping
+  x_col <- rlang::eval_tidy(m$x, d)
+  y_col <- rlang::eval_tidy(m$y, d)
+  # Stem: segment from 0 to y
+  stem_mapping <- encode(x = x_col, xend = x_col, y = 0, yend = y_col)
+  geome <- ggplot2::geom_segment(
+    mapping = stem_mapping,
+    colour = stem_colour, linewidth = stem_width
+  )
+  plot <- .add_geom(plot, geome)
+  # Point at the top
+  point_mapping <- encode(x = x_col, y = y_col)
+  # Determine fill from mapping or default
+  fill_val <- if (!is.null(m$fill)) {
+    rlang::eval_tidy(m$fill, d)
+  } else {
+    NULL
+  }
+  plot <- plot |> mark_point(
+    mapping = m, data = d, size = point_size, ...
+  )
+  plot
+}
+
+# ---- mark_dumbbell ----
+#' Dumbbell comparison chart layer
+#'
+#' Creates a dumbbell chart with two connected points showing before/after
+#' or paired comparisons. This is a **syntax-sugar composite mark**
+#' combining two `mark_point` calls and a `geom_segment`.
+#'
+#' Equivalent expansion:
+#' \preformatted{
+#'   p |> mark_rule(x = x, xend = x, y = y_start, yend = y_end) |>
+#'        mark_point(x = x, y = y_start, colour = colour_start) |>
+#'        mark_point(x = x, y = y_end, colour = colour_end)
+#' }
+#'
+#' @param plot A plotit object
+#' @param mapping Optional new aesthetics
+#' @param data Optional data for this layer
+#' @param colour_start Colour for the start point (default `"#4E79A7"`).
+#' @param colour_end Colour for the end point (default `"#E15759"`).
+#' @param line_colour Colour for the connecting line (default `"grey50"`).
+#' @param point_size Size for both dumbbell points (default 3).
+#' @param line_width Width for the connecting line (default 1).
+#' @param ... Other arguments passed to `mark_point()` calls
+#' @return Modified plotit object
+#' @examples
+#' df <- data.frame(cat = LETTERS[1:5], before = c(3, 5, 2, 8, 4),
+#'                  after = c(7, 6, 5, 10, 6))
+#' plotit(df, encode(x = cat, y = before, yend = after)) |>
+#'   mark_dumbbell()
+#' @export
+mark_dumbbell <- S7::new_generic(
+  "mark_dumbbell", "plot",
+  function(plot, mapping = NULL, data = NULL,
+           colour_start = "#4E79A7", colour_end = "#E15759",
+           line_colour = "grey50", point_size = 3,
+           line_width = 1, ...) {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_dumbbell, plotit_class) <- function(
+    plot, mapping = NULL, data = NULL,
+    colour_start = "#4E79A7", colour_end = "#E15759",
+    line_colour = "grey50", point_size = 3,
+    line_width = 1, ...) {
+  d <- data %||% plot@gg$data
+  m <- mapping %||% plot@gg$mapping
+  x_col <- rlang::eval_tidy(m$x, d)
+  y_col <- rlang::eval_tidy(m$y, d)
+  yend_col <- rlang::eval_tidy(m$yend, d)
+  # Connecting line
+  segment_mapping <- encode(
+    x = x_col, xend = x_col,
+    y = y_col, yend = yend_col
+  )
+  geome <- ggplot2::geom_segment(
+    mapping = segment_mapping,
+    colour = line_colour, linewidth = line_width
+  )
+  plot <- .add_geom(plot, geome)
+  # Start point
+  start_mapping <- encode(x = x_col, y = y_col)
+  plot <- plot |>
+    mark_point(mapping = start_mapping, data = d,
+               colour = colour_start, size = point_size, ...)
+  # End point
+  end_mapping <- encode(x = x_col, y = yend_col)
+  plot <- plot |>
+    mark_point(mapping = end_mapping, data = d,
+               colour = colour_end, size = point_size, ...)
+  plot
+}
+
 # ---- mark_bar (hand-written: geom_col vs geom_bar dispatch) ----
 #' Bar layer
 #'

R/zzz.R

@@ -71,6 +71,8 @@ for (.generic_name in c(
   "mark_violin", "mark_map", "mark_rect", "mark_rule",
   "mark_path", "mark_polygon", "mark_smooth", "mark_hex",
   "mark_density_2d", "mark_corr",
+  "mark_errorbar", "mark_significance",
+  "mark_lollipop", "mark_dumbbell",
   "scale_color", "scale_fill", "scale_size", "scale_alpha",
   "scale_shape", "scale_linetype", "scale_x", "scale_y",
   "project_cartesian", "project_polar", "project_parallel",