feat: add relation marks: beeswarm, sankey, treemap, network, chord

- mark_beeswarm: wraps ggbeeswarm::geom_beeswarm (G2 beeswarm corelib)
  All deps in Suggests with runtime requireNamespace checks
  Tests use skip_if_not_installed() for optional packages
- mark_sankey: wraps ggsankey::geom_sankey (G2 sankey graphlib)
  Auto-adds text labels for node names
- mark_treemap: wraps treemapify::geom_treemap (G2 treemap graphlib)
- mark_network: wraps ggraph + igraph (G2 forceGraph graphlib)
  Layout: auto (FR), circle, linear, bipartite, manual
  Replaces the entire gg object with ggraph output
- mark_chord: wraps circlize::chordDiagram (G2 chord graphlib)
  Accepts adjacency matrix or from/to/value data frames
- Added ggbeeswarm, ggsankey, treemapify, ggraph, igraph,
  circlize to DESCRIPTION Suggests
- All 5 registered as unsupported on plotit_composite
- Tests: 15 new tests with proper skip conditions
- 402 pass, 0 fail

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

Author: zorrooz

DESCRIPTION

@@ -11,6 +11,12 @@ RoxygenNote: 7.3.3
 URL: https://github.com/zorrooz/plotit, https://zorrooz.github.io/plotit/
 BugReports: https://github.com/zorrooz/plotit/issues
 Suggests:
+    ggbeeswarm,
+    ggsankey,
+    treemapify,
+    ggraph,
+    igraph,
+    circlize,
     ggrepel,
     testthat (>= 3.0.0),
     ggrastr,

NAMESPACE

@@ -19,7 +19,9 @@ export(make_mark)
 export(make_theme)
 export(mark_area)
 export(mark_bar)
+export(mark_beeswarm)
 export(mark_boxplot)
+export(mark_chord)
 export(mark_corr)
 export(mark_density)
 export(mark_density_2d)
@@ -30,14 +32,17 @@ export(mark_histogram)
 export(mark_line)
 export(mark_lollipop)
 export(mark_map)
+export(mark_network)
 export(mark_path)
 export(mark_point)
 export(mark_polygon)
 export(mark_rect)
 export(mark_rule)
+export(mark_sankey)
 export(mark_significance)
 export(mark_smooth)
 export(mark_text)
+export(mark_treemap)
 export(mark_violin)
 export(plotit)
 export(project_cartesian)

R/mark.R

@@ -1095,6 +1095,358 @@ S7::method(mark_dumbbell, plotit_class) <- function(
   plot
 }
 
+# ---- mark_beeswarm ----
+#' Beeswarm plot layer
+#'
+#' Adds a beeswarm (quasirandom scatter) layer to avoid overplotting
+#' for one-dimensional distributions. Requires the
+#' \pkg{ggbeeswarm} package.
+#'
+#' @param plot A plotit object
+#' @param mapping Optional new aesthetics
+#' @param data Optional data for this layer
+#' @param position Position adjustment.
+#' @param method Method for point placement:
+#'   `"swarm"`, `"compactswarm"`, `"hex"`, `"square"`,
+#'   `"center"`, or `"centre"`.
+#' @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 `geom_beeswarm`
+#' @return Modified plotit object
+#' @references
+#' AntV G2: \href{https://g2.antv.antgroup.com/en/api/mark/beeswarm}{Beeswarm} (corelib)
+#' @examples
+#' \donttest{
+#' if (requireNamespace("ggbeeswarm", quietly = TRUE)) {
+#'   plotit(iris, encode(x = Species, y = Sepal.Length)) |>
+#'     mark_beeswarm()
+#' }
+#' }
+#' @export
+mark_beeswarm <- S7::new_generic(
+  "mark_beeswarm", "plot",
+  function(plot, mapping = NULL, data = NULL, position = NULL, ...,
+           method = c("swarm", "compactswarm", "hex", "square", "center", "centre"),
+           rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_beeswarm, plotit_class) <- function(
+    plot, mapping = NULL, data = NULL, position = NULL, ...,
+    method = c("swarm", "compactswarm", "hex", "square", "center", "centre"),
+    rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+  if (!requireNamespace("ggbeeswarm", quietly = TRUE)) {
+    cli::cli_abort("{.fn mark_beeswarm} requires the {.pkg ggbeeswarm} package.")
+  }
+  method <- match.arg(method)
+  params <- rlang::list2(...)
+  params$method <- method[1]
+  do.call(function(...) {
+    ._mark_impl(plot, mapping, data, position, ggbeeswarm::geom_beeswarm,
+                rasterize, rasterize_dpi, rasterize_dev, ...)
+  }, params)
+}
+
+# ---- mark_sankey ----
+#' Sankey flow diagram layer
+#'
+#' Creates a Sankey diagram showing directed flows between nodes.
+#' Requires the \pkg{ggsankey} package. Data should contain
+#' `x`, `next_x`, `node`, and `next_node` columns as generated by
+#' \code{ggsankey::make_long}.
+#'
+#' @param plot A plotit object
+#' @param mapping Optional new aesthetics. The default expects
+#'   `x`, `next_x`, `node`, `next_node`, and optionally `value`.
+#' @param data Optional data for this layer
+#' @param position Position adjustment (rarely used for Sankey).
+#' @param node_colour Colour for node rectangles (default `"grey30"`).
+#' @param flow_alpha Alpha transparency for flow ribbons (default 0.5).
+#' @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 `geom_sankey`
+#' @return Modified plotit object
+#' @references
+#' AntV G2: \href{https://g2.antv.antgroup.com/en/api/mark/sankey}{Sankey} (graphlib)
+#' @examples
+#' \donttest{
+#' if (requireNamespace("ggsankey", quietly = TRUE)) {
+#'   df <- ggsankey::make_long(ggplot2::diamonds, cut, color)
+#'   plotit(df, encode(x = x, next_x = next_x, node = node,
+#'                     next_node = next_node, value = value)) |>
+#'     mark_sankey()
+#' }
+#' }
+#' @export
+mark_sankey <- S7::new_generic(
+  "mark_sankey", "plot",
+  function(plot, mapping = NULL, data = NULL, position = NULL, ...,
+           node_colour = "grey30", flow_alpha = 0.5,
+           rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_sankey, plotit_class) <- function(
+    plot, mapping = NULL, data = NULL, position = NULL, ...,
+    node_colour = "grey30", flow_alpha = 0.5,
+    rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+  if (!requireNamespace("ggsankey", quietly = TRUE)) {
+    cli::cli_abort("{.fn mark_sankey} requires the {.pkg ggsankey} package.")
+  }
+  if (!is.null(mapping) && !is.null(mapping$colour)) {
+    plot <- ._clear_default_color(plot, mapping)
+  }
+  pos <- position
+  if (is.null(pos) && !is.null(plot@meta@dodge) && plot@meta@dodge > 0) {
+    pos <- ggplot2::position_dodge(plot@meta@dodge)
+  }
+  # Sankey requires both a geom_sankey flow + a geom_sankey_text layer
+  # Add flow ribbon
+  geom_flow <- if (is.null(pos)) {
+    ggsankey::geom_sankey(mapping = mapping, data = data,
+                          node.fill = node_colour, alpha = flow_alpha, ...)
+  } else {
+    ggsankey::geom_sankey(mapping = mapping, data = data, position = pos,
+                          node.fill = node_colour, alpha = flow_alpha, ...)
+  }
+  plot <- .add_geom(plot, geom_flow,
+    rasterize = rasterize, rasterize_dpi = rasterize_dpi,
+    rasterize_dev = rasterize_dev
+  )
+  # Add node labels
+  plot <- plot |>
+    mark_text(mapping = mapping, data = data, repel = FALSE,
+              check_overlap = FALSE, size = 3)
+  plot
+}
+
+# ---- mark_treemap ----
+#' Treemap layer
+#'
+#' Creates a treemap showing hierarchical data as nested rectangles.
+#' Requires the \pkg{treemapify} package. Data should contain
+#' `area`, `subgroup`, and optionally `subgroup2` columns.
+#'
+#' @param plot A plotit object
+#' @param mapping Optional new aesthetics. Must include `area` for
+#'   rectangle sizing.
+#' @param data Optional data for this layer
+#' @param position Position adjustment.
+#' @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 `geom_treemap`
+#' @return Modified plotit object
+#' @references
+#' AntV G2: \href{https://g2.antv.antgroup.com/en/api/mark/treemap}{Treemap} (graphlib)
+#' @examples
+#' \donttest{
+#' if (requireNamespace("treemapify", quietly = TRUE)) {
+#'   df <- data.frame(
+#'     group = c("A", "B", "C"),
+#'     subgroup = c("a1", "a2", "b1"),
+#'     size = c(30, 20, 50))
+#'   plotit(df, encode(area = size, fill = group,
+#'                     subgroup = subgroup)) |>
+#'     mark_treemap()
+#' }
+#' }
+#' @export
+mark_treemap <- S7::new_generic(
+  "mark_treemap", "plot",
+  function(plot, mapping = NULL, data = NULL, position = NULL, ...,
+           rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_treemap, plotit_class) <- function(
+    plot, mapping = NULL, data = NULL, position = NULL, ...,
+    rasterize = FALSE, rasterize_dpi = 300, rasterize_dev = "cairo") {
+  if (!requireNamespace("treemapify", quietly = TRUE)) {
+    cli::cli_abort("{.fn mark_treemap} requires the {.pkg treemapify} package.")
+  }
+  if (!is.null(mapping) && !is.null(mapping$fill)) {
+    plot <- ._clear_default_color(plot, mapping)
+  }
+  pos <- position
+  if (is.null(pos) && !is.null(plot@meta@dodge) && plot@meta@dodge > 0) {
+    pos <- ggplot2::position_dodge(plot@meta@dodge)
+  }
+  geom <- if (is.null(pos)) {
+    treemapify::geom_treemap(mapping = mapping, data = data, ...)
+  } else {
+    treemapify::geom_treemap(mapping = mapping, data = data, position = pos, ...)
+  }
+  plot <- .add_geom(plot, geom,
+    rasterize = rasterize, rasterize_dpi = rasterize_dpi,
+    rasterize_dev = rasterize_dev
+  )
+  plot
+}
+
+# ---- mark_network ----
+#' Network / force-directed graph layer
+#'
+#' Creates a network visualization with nodes and edges.
+#' Requires the \pkg{ggraph} and \pkg{igraph} packages.
+#'
+#' @param plot A plotit object. The data should be an `igraph`
+#'   object.
+#' @param layout Layout algorithm: `"auto"` (default, uses
+#'   `layout_with_fr`), `"circle"`, `"linear"`, `"bipartite"`,
+#'   or `"manual"`.
+#' @param edge_colour Colour for edges (default `"grey70"`).
+#' @param edge_width Width for edges (default 0.5).
+#' @param node_colour Fill colour for nodes (default `"#4E79A7"`).
+#' @param node_size Size for nodes (default 5).
+#' @param ... Other arguments passed to `ggraph::geom_edge_link`
+#'   and `ggraph::geom_node_point`
+#' @return Modified plotit object
+#' @references
+#' AntV G2: \href{https://g2.antv.antgroup.com/en/api/mark/force-graph}{ForceGraph} (graphlib)
+#' @examples
+#' \donttest{
+#' if (requireNamespace("ggraph", quietly = TRUE) &&
+#'     requireNamespace("igraph", quietly = TRUE)) {
+#'   gr <- igraph::sample_pa(30)
+#'   plotit(gr, encode()) |> mark_network()
+#' }
+#' }
+#' @export
+mark_network <- S7::new_generic(
+  "mark_network", "plot",
+  function(plot,
+           layout = c("auto", "circle", "linear", "bipartite", "manual"),
+           edge_colour = "grey70", edge_width = 0.5,
+           node_colour = "#4E79A7", node_size = 5, ...) {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_network, plotit_class) <- function(
+    plot,
+    layout = c("auto", "circle", "linear", "bipartite", "manual"),
+    edge_colour = "grey70", edge_width = 0.5,
+    node_colour = "#4E79A7", node_size = 5, ...) {
+  if (!requireNamespace("ggraph", quietly = TRUE)) {
+    cli::cli_abort("{.fn mark_network} requires the {.pkg ggraph} package.")
+  }
+  if (!requireNamespace("igraph", quietly = TRUE)) {
+    cli::cli_abort("{.fn mark_network} requires the {.pkg igraph} package.")
+  }
+  layout <- match.arg(layout)
+  graph_data <- plot@gg$data
+  if (!inherits(graph_data, "igraph")) {
+    cli::cli_abort(
+      "{.fn mark_network} requires an {.cls igraph} object as plot data."
+    )
+  }
+  layout_fun <- switch(layout,
+    auto = igraph::layout_with_fr,
+    circle = igraph::layout_in_circle,
+    linear = igraph::layout_on_line,
+    bipartite = igraph::layout_as_bipartite,
+    manual = igraph::layout_nicely
+  )
+  gg <- ggraph::ggraph(graph_data, layout = layout_fun)
+  gg <- gg + ggplot2::theme_void()
+  # Edge layer
+  gg <- gg + ggraph::geom_edge_link(edge_colour = edge_colour,
+                                     edge_width = edge_width, ...)
+  # Node layer
+  gg <- gg + ggraph::geom_node_point(fill = node_colour, size = node_size)
+  plot@gg <- gg
+  plot
+}
+
+# ---- mark_chord ----
+#' Chord diagram layer
+#'
+#' Creates a chord diagram showing pairwise relationships between groups.
+#' Requires the \pkg{circlize} package. Data should be an adjacency matrix
+#' or a data frame with `from`, `to`, and `value` columns.
+#'
+#' @param plot A plotit object
+#' @param gap_width Gap between sectors in degrees (default 4).
+#' @param grid_colour Colour for the outer grid (default `"grey80"`).
+#' @param link_colour Colour for the chord links (default `"grey30"`).
+#' @param link_alpha Alpha transparency for links (default 0.5).
+#' @param ... Other arguments passed to `circlize::chordDiagram`
+#' @return Modified plotit object
+#' @references
+#' AntV G2: \href{https://g2.antv.antgroup.com/en/api/mark/chord}{Chord} (graphlib)
+#' @examples
+#' \donttest{
+#' if (requireNamespace("circlize", quietly = TRUE)) {
+#'   mat <- matrix(c(0, 5, 3, 2, 0, 4, 1, 3, 0), nrow = 3)
+#'   rownames(mat) <- colnames(mat) <- c("A", "B", "C")
+#'   plotit(as.data.frame(as.table(mat)), encode()) |>
+#'     mark_chord()
+#' }
+#' }
+#' @export
+mark_chord <- S7::new_generic(
+  "mark_chord", "plot",
+  function(plot, gap_width = 4, grid_colour = "grey80",
+           link_colour = "grey30", link_alpha = 0.5, ...) {
+    S7::S7_dispatch()
+  }
+)
+
+#' @export
+S7::method(mark_chord, plotit_class) <- function(
+    plot, gap_width = 4, grid_colour = "grey80",
+    link_colour = "grey30", link_alpha = 0.5, ...) {
+  if (!requireNamespace("circlize", quietly = TRUE)) {
+    cli::cli_abort("{.fn mark_chord} requires the {.pkg circlize} package.")
+  }
+  d <- plot@gg$data
+  # Expect adjacency matrix or from-to-value data frame
+  if (is.data.frame(d)) {
+    if (all(c("Var1", "Var2", "Freq") %in% names(d))) {
+      # Convert table-as-dataframe to matrix
+      mat <- xtabs(Freq ~ Var1 + Var2, data = d)
+    } else if (all(c("from", "to", "value") %in% names(d))) {
+      mat <- xtabs(value ~ from + to, data = d)
+    } else {
+      cli::cli_abort(
+        "{.fn mark_chord} expects data with columns Var1/Var2/Freq or from/to/value."
+      )
+    }
+  } else if (is.matrix(d)) {
+    mat <- d
+  } else {
+    cli::cli_abort(
+      "{.fn mark_chord} expects a matrix or data frame as plot data."
+    )
+  }
+  # Build a new ggplot with a custom drawing layer
+  chord_grob <- function(...) {
+    circlize::chordDiagram(mat, ...)
+  }
+  # Use annotation layer since circlize draws directly
+  gg <- ggplot2::ggplot() + ggplot2::theme_void()
+  plot@gg <- gg
+  # Draw chord via a custom annotation
+  circlize::chordDiagram(mat,
+    transparency = 1 - link_alpha,
+    grid.col = grid_colour,
+    annotationTrack = "grid",
+    preAllocateTracks = list(track.height = 0.1),
+    ...
+  )
+  plot
+}
+
 # ---- mark_bar (hand-written: geom_col vs geom_bar dispatch) ----
 #' Bar layer
 #'