Bundle edges using edge path bundling

This geom performs edge bundling using the edge path algorithm. This approach uses the underlying graph structure to find shortest paths for each edge in a graph the is gradually removed of it's edges. Since it is based on the topology of the graph it should lead to less spurious bundling of unrelated edges compared to geom_edge_bundle_force() and also has a simpler parameter space.

geom_edge_bundle_path(
  mapping = NULL,
  data = get_edges(),
  position = "identity",
  arrow = NULL,
  n = 100,
  directed = NULL,
  max_distortion = 2,
  weight_fac = 2,
  tension = 1,
  lineend = "butt",
  linejoin = "round",
  linemitre = 1,
  label_colour = "black",
  label_alpha = 1,
  label_parse = FALSE,
  check_overlap = FALSE,
  angle_calc = "rot",
  force_flip = TRUE,
  label_dodge = NULL,
  label_push = NULL,
  show.legend = NA,
  ...
)

geom_edge_bundle_path2(
  mapping = NULL,
  data = get_edges("long"),
  position = "identity",
  arrow = NULL,
  n = 100,
  directed = NULL,
  max_distortion = 2,
  weight_fac = 2,
  tension = 1,
  lineend = "butt",
  linejoin = "round",
  linemitre = 1,
  label_colour = "black",
  label_alpha = 1,
  label_parse = FALSE,
  check_overlap = FALSE,
  angle_calc = "rot",
  force_flip = TRUE,
  label_dodge = NULL,
  label_push = NULL,
  show.legend = NA,
  ...
)

geom_edge_bundle_path0(
  mapping = NULL,
  data = get_edges(),
  position = "identity",
  arrow = NULL,
  directed = NULL,
  max_distortion = 2,
  weight_fac = 2,
  tension = 1,
  lineend = "butt",
  show.legend = NA,
  ...
)

Arguments

mapping: Set of aesthetic mappings created by ggplot2::aes() or ggplot2::aes_(). By default x, y, xend, yend, group and circular are mapped to x, y, xend, yend, edge.id and circular in the edge data.
data: The return of a call to get_edges() or a data.frame giving edges in correct format (see details for for guidance on the format). See get_edges() for more details on edge extraction.
position: Position adjustment, either as a string naming the adjustment (e.g. "jitter" to use position_jitter), or the result of a call to a position adjustment function. Use the latter if you need to change the settings of the adjustment.
arrow: Arrow specification, as created by grid::arrow().
n: The number of points to create along the path.
directed: Logical. Should the shortest paths be calculated using direction information of the graph. Setting this to TRUE can help split up bundles that flows in opposite directions. Ignored for undirected graphs
max_distortion: A multiplication factor to determine the maximum allowed distortion of the path during bundling. If the new edge is longer than max_distortion times the old length it is rejected.
weight_fac: The exponent used to assign weights to the graph when calculating the shortest path. The final weights are given as edge_length ^ weight_fac meaning that sorter edges are prioritised when calculating the weights.
tension: A loosening factor when calculating the b-spline of the edge based on the shortest path. Will move control points closer and closer to the direct line as it approaches 0
lineend: Line end style (round, butt, square).
linejoin: Line join style (round, mitre, bevel).
linemitre: Line mitre limit (number greater than 1).
label_colour: The colour of the edge label. If NA it will use the colour of the edge.
label_alpha: The opacity of the edge label. If NA it will use the opacity of the edge.
label_parse: If TRUE, the labels will be parsed into expressions and displayed as described in grDevices::plotmath().
check_overlap: If TRUE, text that overlaps previous text in the same layer will not be plotted. check_overlap happens at draw time and in the order of the data. Therefore data should be arranged by the label column before calling geom_text(). Note that this argument is not supported by geom_label().
angle_calc: Either 'none', 'along', or 'across'. If 'none' the label will use the angle aesthetic of the geom. If 'along' The label will be written along the edge direction. If 'across' the label will be written across the edge direction.
force_flip: Logical. If angle_calc is either 'along' or 'across' should the label be flipped if it is on it's head. Default to TRUE.
label_dodge: A grid::unit() giving a fixed vertical shift to add to the label in case of angle_calc is either 'along' or 'across'
label_push: A grid::unit() giving a fixed horizontal shift to add to the label in case of angle_calc is either 'along' or 'across'
show.legend: logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display.
...: Other arguments passed on to layer(). These are often aesthetics, used to set an aesthetic to a fixed value, like colour = "red" or size = 3. They may also be parameters to the paired geom/stat.

Aesthetics

geom_edge_force_path and geom_edge_force_path0 understand the following aesthetics. Bold aesthetics are automatically set, but can be overwritten.

x
y
xend
yend
edge_id (should not be overwritten)
edge_colour
edge_width
edge_linetype
edge_alpha
filter

geom_edge_force_path2 understand the following aesthetics. Bold aesthetics are automatically set, but can be overwritten.

x
y
group
edge_id (should not be overwritten)
edge_colour
edge_width
edge_linetype
edge_alpha
filter

geom_edge_force_path and geom_edge_force_path2 furthermore takes the following aesthetics.

start_cap
end_cap
label
label_pos
label_size
angle
hjust
vjust
family
fontface
lineheight

Computed variables

index: The position along the path (not computed for the *0 version)

Edge variants

Many geom_edge_* layers comes in 3 flavors depending on the level of control needed over the drawing. The default (no numeric postfix) generate a number of points (n) along the edge and draws it as a path. Each point along the line has a numeric value associated with it giving the position along the path, and it is therefore possible to show the direction of the edge by mapping to this e.g. colour = after_stat(index). The version postfixed with a "2" uses the "long" edge format (see get_edges()) and makes it possible to interpolate node parameter between the start and end node along the edge. It is considerable less performant so should only be used if this is needed. The version postfixed with a "0" draws the edge in the most performant way, often directly using an appropriate grob from the grid package, but does not allow for gradients along the edge.

Often it is beneficial to stop the drawing of the edge before it reaches the node, for instance in cases where an arrow should be drawn and the arrowhead shouldn't lay on top or below the node point. geom_edge_* and geom_edge_*2 supports this through the start_cap and end_cap aesthetics that takes a geometry() specification and dynamically caps the termini of the edges based on the given specifications. This means that if end_cap = circle(1, 'cm') the edges will end at a distance of 1cm even during resizing of the plot window.

All geom_edge_* and geom_edge_*2 have the ability to draw a label along the edge. The reason this is not a separate geom is that in order for the label to know the location of the edge it needs to know the edge type etc. Labels are drawn by providing a label aesthetic. The label_pos can be used to specify where along the edge it should be drawn by supplying a number between 0 and 1. The label_size aesthetic can be used to control the size of the label. Often it is needed to have the label written along the direction of the edge, but since the actual angle is dependent on the plot dimensions this cannot be calculated beforehand. Using the angle_calc argument allows you to specify whether to use the supplied angle aesthetic or whether to draw the label along or across the edge.

Edge aesthetic name expansion

In order to avoid excessive typing edge aesthetic names are automatically expanded. Because of this it is not necessary to write edge_colour within the aes() call as colour will automatically be renamed appropriately.

References

Wallinger, M., Archambault, D., Auber, D., Nöllenburg, M., and Peltonen, J. (2022). Edge-Path Bundling: A Less Ambiguous Edge Bundling Approach. IEEE Transactions on Visualization and Computer Graphics 28(1) 313-323. https://doi.org/10.1109/TVCG.2021.3114795

Author

Thomas Lin Pedersen and David Schoch

Examples

ggraph(highschool) +
  geom_edge_bundle_path()
#> Using "stress" as default layout


# Use tension to lessen the effect
ggraph(highschool) +
  geom_edge_bundle_path(tension = 0.8)
#> Using "stress" as default layout