connect: Connect boxes with arrows
In Gmisc: Descriptive Statistics, Transition Plots, and More

connectGrob

R Documentation

Connect boxes with arrows

Description

Creates connectors between boxes.

A convenient way to connect boxes in a 'Gmisc_list_of_boxes' or simple 'list' context, designed for piping ('|>').

Usage

connectGrob(
  start,
  end,
  type = c("vertical", "horizontal", "L", "-", "Z", "N", "fan_in_top", "fan_in_center"),
  subelmnt = c("right", "left"),
  lty_gp = getOption("connectGrob", default = gpar(fill = "black")),
  arrow_obj = getOption("connectGrobArrow", default = arrow(ends = "last", type =
    "closed")),
  split_pad = unit(2, "mm"),
  margin = unit(2, "mm"),
  label = NULL,
  label_gp = grid::gpar(cex = 0.9),
  label_bg_gp = grid::gpar(fill = "white", col = NA),
  label_pad = unit(1.5, "mm"),
  label_pos = c("mid", "near_start", "near_end"),
  label_offset = unit(2, "mm")
)

## S3 method for class 'connect_boxes'
print(x, ...)

## S3 method for class 'connect_boxes'
plot(x, ...)

## S3 method for class 'connect_boxes_list'
grid.draw(x, recording = TRUE)

## S3 method for class 'connect_boxes_list'
print(x, ...)

## S3 method for class 'connect_boxes_list'
plot(x, ...)

connect(x, ...)

## Default S3 method:
connect(x, ...)

## S3 method for class 'Gmisc_list_of_boxes'
connect(x, from = NULL, to = NULL, ...)

Arguments

`start`	A `boxGrob`/`boxPropGrob`, or a list of boxes (many-to-one).
`end`	A `boxGrob`/`boxPropGrob`, or a list of boxes (one-to-many).
`type`	Connector type, see Details.
`subelmnt`	For split boxes, which sub-element to anchor to: `"left"` or `"right"`.
`lty_gp`	A `grid::gpar()` controlling line appearance. Can also be set globally via `options(connectGrob = ...)`.
`arrow_obj`	Arrow specification created with `grid::arrow()`. Can also be set globally via `options(connectGrobArrow = ...)`.
`split_pad`	Padding around the shared bend point for multi-box connections. Numeric values are interpreted as millimeters.
`margin`	For `type = "fan_in_top"`, the margin applied at the left and right ends of the end box top edge before distributing attachment points. Numeric values are interpreted as millimeters.
`label`	Optional text label for one-to-one connectors (e.g. `"yes"` / `"no"`). Only supported when both `start` and `end` are single boxes.
`label_gp`	A `grid::gpar()` controlling label appearance.
`label_bg_gp`	A `grid::gpar()` controlling label background appearance. Defaults to a white background with no border.
`label_pad`	Padding inside the label background. Numeric values are interpreted as millimeters.
`label_pos`	Where to place the label along the connector: `"mid"`, `"near_start"`, or `"near_end"`.
`label_offset`	Offset for the label away from the connector line.
`x`	A 'list' of boxes (will be converted to 'Gmisc_list_of_boxes' if needed).
`...`	Arguments passed on to ['connectGrob'].
`recording`	Passed to [grid::grid.draw()] when rendering each element in the list. Defaults to 'TRUE' (record drawing for later replay).
`from`	The name (string) or index of the start box in 'x'. Multiple values allowed.
`to`	The name (string) or index of the end box in 'x'. Multiple values allowed.

Details

The function supports:

One-to-one: a single start box connected to a single end box.
One-to-many: a single start box connected to multiple end boxes.
Many-to-one: multiple start boxes connected to a single end box.

Many-to-many connections are not supported.

If either start or end is a list, a list of connector grobs is returned (one per connection). Otherwise a single connector grob is returned.

Each connector stores its computed geometry in attr(x, "line") (or for each element when a list is returned). This can be reused to construct custom connectors using the calculated coordinates.

Connector types

type controls the connector shape:

"vertical": straight vertical connector
"horizontal": straight horizontal connector
"L": vertical then horizontal (direction chosen automatically)
"-": straight horizontal connector at the end box y-position
"Z": horizontal connector with two 90-degree turns
"N": vertical connector with one horizontal segment When connecting to or from multiple boxes, all connectors share the same bend height.
"fan_in_top": many-to-one connector merging onto the top edge of the end box Attachment points are evenly distributed along the edge (with optional margin), and all connectors share a common bend height.
"fan_in_center": many-to-one connector that aggregates stems onto a horizontal bus (shared at the computed bend height) and then a single centered trunk with an arrow that points to the center of the end box. Useful when you want a single arrow to represent the merged flow (e.g. a middle trunk bus).

For type = "N" and type = "fan_in_top" with multi-box connections, a shared bend position is computed so that the horizontal segment aligns visually across all connectors.

Labels

For one-to-one connectors you can add a text label (for example "yes" / "no"). The label is placed near the midpoint of the connector. The label is drawn with a white background for readability. Use label_pad to control padding around the text and label_offset to move the label away from the connector.

Split boxes

When connecting to or from a boxPropGrob, subelmnt controls whether the left or right sub-box x-coordinate is used as the anchor point.

Value

One-to-one: a grid::grob() with class "connect_boxes".
One-to-many or many-to-one: a list of grobs with class "connect_boxes_list".

The original list 'x' (upgraded to 'Gmisc_list_of_boxes') with a new connection appended to its '"connections"' attribute. When printed, these connections are drawn.

Examples

library(grid)
grid.newpage()

# Initiate the boxes that we want to connect
boxes <- list(
  start = boxGrob("Top", x = .5, y = .8),
  end = boxGrob("Bottom", x = .5, y = .2),
  side = boxPropGrob("Side", "Left", "Right", prop = .3, x = .2, y = .8),
  exclude = boxGrob("Exclude:\n - Too sick\n - Prev. surgery", x = .8, y = .5, just = "left")
)

# Connect the boxes and print/plot them
connectGrob(boxes$start, boxes$end, "vertical")
connectGrob(boxes$start, boxes$side, "horizontal")
connectGrob(boxes$start, boxes$exclude, "L")

# We can also connect to/from lists
side_boxes <- list(
  left = boxGrob("Left", x = attr(boxes$side, "coords")$left_x, y = .5),
  right = boxGrob("Right", x = attr(boxes$side, "coords")$right_x, y = .5)
)

connectGrob(boxes$side, side_boxes$left, "v", "l")
connectGrob(boxes$side, side_boxes$right, "v", "r")

# Fan-in center example: multiple starts into one center bus and single trunk
list(
  boxes$start,
  boxGrob("S2", x = .3, y = .7),
  boxGrob("S3", x = .7, y = .7)
) |>
  connectGrob(boxes$end, type = "fan_in_center")

# Print the boxes
boxes
side_boxes

Gmisc documentation built on March 6, 2026, 9:09 a.m.