Plot Method for Gradient Flow Graph Objects

Creates a visualization of a gradient flow graph showing basins as vertices and their intersections as edges. The plot uses different visual encoding to distinguish ascending from descending basins and to represent edge weights.

Usage

# S3 method for class 'gflow_graph'
plot(
  x,
  layout = c("extremum", "force", "circular", "bipartite"),
  vertex.size.scale = 1,
  edge.width.scale = 1,
  vertex.color.ascending = "lightblue",
  vertex.color.descending = "lightcoral",
  vertex.label = TRUE,
  vertex.label.cex = 0.7,
  edge.color = "gray60",
  edge.transparency = 0.5,
  add.legend = TRUE,
  main = "Gradient Flow Graph",
  ...
)

Arguments

x

An object of class "gflow_graph" as created by construct.gflow.graph.

layout

Character string specifying the layout algorithm. Options are:

"extremum": Position vertices by extremum value (default). X-coordinates are random jitter, Y-coordinates reflect function values.
"force": Use force-directed layout algorithm (requires igraph).
"circular": Arrange vertices in a circle.
"bipartite": Arrange ascending and descending basins in two rows.

vertex.size.scale

Numeric scaling factor for vertex sizes (default: 1.0).

edge.width.scale

Numeric scaling factor for edge widths (default: 1.0).

vertex.color.ascending

Color for ascending basin vertices (default: "lightblue").

vertex.color.descending

Color for descending basin vertices (default: "lightcoral").

vertex.label

Logical indicating whether to show vertex labels (default: TRUE).

vertex.label.cex

Numeric character expansion for labels (default: 0.7).

edge.color

Color for edges (default: "gray60").

edge.transparency

Numeric in \([0,1]\) controlling edge transparency, where 0 is fully transparent and 1 is fully opaque (default: 0.5).

add.legend

Logical indicating whether to add a legend (default: TRUE).

main

Character string for plot title (default: "Gradient Flow Graph").

...

Additional graphical parameters passed to plot().

Value

Invisibly returns the coordinates used for vertex placement as a two-column matrix with rownames matching basin labels.

Details

The visualization problem for gradient flow graphs differs from standard graph drawing because the vertices carry semantic meaning beyond mere connectivity. We wish to represent not only which basins intersect but also the orientation of gradient flow (ascending versus descending) and the relative importance of different connections.

We address this through a layered visual encoding. Vertex position reflects the extremum function value, creating a natural vertical ordering that mirrors the gradient flow structure. Ascending basins (minima) appear toward the bottom of the plot while descending basins (maxima) appear toward the top. This spatial arrangement helps viewers immediately grasp the relationship between basins and the underlying function landscape.

Vertex size encodes basin extent, with larger circles representing basins that capture more vertices from the original graph. This allows quick identification of major versus minor topological features. Color distinguishes basin type, with one palette for minima and another for maxima, making the bipartite structure evident when Morse-Smale edges predominate.

Edge styling communicates connection strength through both width and transparency. Edges representing larger intersections appear thicker and more opaque, drawing attention to regions where basins substantially overlap. Weak intersections fade into the background, preventing visual clutter while preserving the complete connectivity structure for careful examination.

Examples

gflow.graph <- list(
  adjacency.list = list(c(3L), integer(0), c(1L)),
  weight.list = list(0.8, numeric(0), 0.8),
  n.ascending = 2L,
  n.descending = 1L,
  basin.metadata = data.frame(
    label = c("m1", "m2", "M1"),
    type = c("ascending", "ascending", "descending"),
    size = c(4, 3, 5),
    extremum.vertex = c(2L, 5L, 3L),
    extremum.value = c(0.7, 1.1, 3.2)
  ),
  intersection.matrix = matrix(
    c(4, 0, 2,
      0, 3, 0,
      2, 0, 5),
    nrow = 3, byrow = TRUE
  ),
  edge.type = "all",
  min.intersection = 1L
)
class(gflow.graph) <- "gflow_graph"

plot(gflow.graph, layout = "extremum", add.legend = FALSE)
plot(gflow.graph, layout = "bipartite", edge.transparency = 0.3)

Usage

Arguments

Value

Details

See also

Examples