Recipes — Adjacency Flow — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

AI / Machine-readable docs: llms.txt · llms-full.txt · Full AI Reference · schema.json · API Reference · Examples

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/recipes/adjacency-flow

Adjacency Flow

Recipe

semioticreact

An adjacency matrix is compact, but many readers struggle to trace a path through its cells. A Sankey diagram makes flow tangible, but overlapping curves can make dense routes ambiguous. adjacencyFlowLayout combines their strongest ideas: nodes keep an explicit order along the diagonal, while weighted links travel through matrix cells as straight segments with tight rounded turns.

This recipe implements Richard Brath’sSankey Matrix proposal, itself inspired by Lawrence Hanley’s schematic treatment of the 1968–70 UK textile industry. Brath’s key observation is that each fillet occupies the same meaningful row × column location as an adjacency-matrix cell, while line width preserves the aggregate-flow reading of a Sankey.

Interactive preview

Switch between the nine-step journey and the three-phase summary. Individual phases can be expanded in place; click a diagonal node, use the phase chips, hover routes for exact totals, or toggle the directional and quantitative cues.

Level of detail

Flow color

Direction arrowsValues

Click a node or phase:

↗ Upper-right: forward in sequence↙ Lower-left: reversals and backtracking↻ Diagonal loops: within collapsed phases

How to read it

Diagonal squares preserve the authored sequence. This order is data, not a decoration: pass layoutConfig.order when input order is not authoritative.
Upper-right routes move forward in the sequence; lower-left routes move backward. Long jumps remain aligned to the destination’s column.
Line width encodes weight. Ports stack and fit all incident routes against a node side, so their combined thickness remains an aggregate input/output cue.
Rounded turns and value labels occupy row × column cells, preserving the lookup behavior of an adjacency matrix without asking the reader to decode isolated marks.

What the Semiotic recipe adds

Brath notes that the arrows in his generated prototype are too small. Here each route gets a translucent white arrow on its final leg, making forward, reverse, and self-flow unambiguous without relying on color. Each triangle is sized from its containing route, inset by at least one pixel on both sides, and omitted when two or fewer useful pixels remain. Override its fill with arrowColor or the scoped--semiotic-adjacency-flow-arrow-fill variable. Parallel records for the same source/target cell are summed before drawing, labels receive a halo over dense strokes, and the layout adapts its flow scale to the busiest node port.

The square footprint is particularly useful on mobile. A conventional arc diagram lays its ordered nodes across one long horizontal baseline, so labels and intervals quickly compress or require sideways scrolling. This squarified route uses both viewport dimensions, keeping more cell area available at the same phone width and fitting naturally into a responsive vertical page.

The visible geometry remains a native NetworkCustomChart scene: nodes and routes support canvas hit testing, tooltips, click observation, static SVG rendering, keyboard node navigation, and an accessible table. Supply title,description, and summary for the conclusion the visual arrangement alone cannot communicate.

Summary and drill-down

A square matrix has a hard perceptual limit. Brath suggests filtering or aggregation at roughly fifty ordered items; the more useful generic strategy is semantic grouping before that limit. The headless aggregateAdjacencyFlow transform accepts agroupAccessor and an expandedGroups set, then returns another valid node/edge list:

Collapsed groups become one diagonal node, ordered by their first member.
Parallel cross-group routes are summed.
Within-group movement becomes a self-flow, so summary activity is not silently erased.
Expanded groups restore their ordered members and original internal routes.

Grouping should normally come from the domain—journey phases, processing stages, teams, or communities already validated by an analysis—not an opaque layout heuristic. For larger data, combine groups with top-k filtering, a minimum-flow threshold, search, and coordinated detail views. The transform reports omitted invalid edges but deliberately leaves those analytical choices to the application.

Customization

Goal	Option	Guidance
Preserve a known sequence	`order`	Prefer an authored event/stage order over an automatic network ordering.
Make direction redundant	`showArrows`, `arrowColor`	Keep arrows on unless a tiny summary has no ambiguous routes. Thin routes omit arrows automatically; use the CSS fill variable for theme-scoped overrides.
Control density	`maxCellSize`, `flowGap`	Cap sparse summaries and preserve a small gap between stacked paths.
Encode route categories	`colorMode`	Use `"single"` for weight-first reading. With `"source"`, each source node and its outgoing routes share one palette color for tracing.
Collapse detail	`aggregateAdjacencyFlow`	Drive `expandedGroups` from click, search, or application state.

Sankey Diagram — conventional layered flow layout
StreamNetworkFrame — lower-level network scene API
Custom Layouts — authoring and renderer contract

Source Code

Abbreviated for readability — data arrays and steps are truncated. See the full runnable source in docs/src/examples/recipes/.

JSX

1 import { useMemo, useState } from "react"
2 import { NetworkCustomChart } from "semiotic/network"
3 import { adjacencyFlowLayout, aggregateAdjacencyFlow } from "semiotic/recipes"
4 
5 const nodes = [
6  { id: "A", label: "A", group: "ABC" },
7  { id: "B", label: "B", group: "ABC" },
8  { id: "C", label: "C", group: "ABC" },
9  { id: "D", label: "D", group: "DEF" },
10  { id: "E", label: "E", group: "DEF" },
11  { id: "F", label: "F", group: "DEF" },
12  { id: "G", label: "G", group: "GHI" },
13  { id: "H", label: "H", group: "GHI" },
14  { id: "I", label: "I", group: "GHI" },
15 ]
16 
17 const edges = [
18  { source: "A", target: "B", value: 10 },
19  { source: "B", target: "C", value: 25 },
20  { source: "C", target: "A", value: 3 },
21  { source: "C", target: "D", value: 8 },
22  { source: "D", target: "E", value: 7 },
23  { source: "E", target: "F", value: 12 },
24  { source: "F", target: "D", value: 2 },
25  { source: "F", target: "G", value: 9 },
26  { source: "G", target: "H", value: 22 },
27  { source: "H", target: "I", value: 14 },
28  { source: "I", target: "G", value: 5 },
29 ]
30 
31 export default function AdjacencyFlowExample() {
32  const [expandedGroups, setExpandedGroups] = useState(
33  () => new Set(["ABC", "DEF", "GHI"])
34  )
35  const { nodes: visibleNodes, edges: visibleEdges } = useMemo(
36  () => aggregateAdjacencyFlow(nodes, edges, {
37  groupAccessor: "group",
38  expandedGroups,
39  includeInternalFlows: true,
40  }),
41  [expandedGroups]
42  )
43  const toggleGroup = (group) => {
44  if (!group) return
45  setExpandedGroups((current) => {
46  const next = new Set(current)
47  if (next.has(group)) next.delete(group)
48  else next.add(group)
49  return next
50  })
51  }
52 
53  return (
54  <NetworkCustomChart
55  nodes={visibleNodes}
56  edges={visibleEdges}
57  nodeIDAccessor="id"
58  sourceAccessor="source"
59  targetAccessor="target"
60  layout={adjacencyFlowLayout}
61  layoutConfig={{
62  showArrows: true,
63  showValues: true,
64  colorMode: "single",
65  maxCellSize: 92,
66  cornerRadius: 9,
67  }}
68  style={{
69  "--semiotic-adjacency-flow-arrow-fill": "rgba(255, 255, 255, 0.72)",
70  }}
71  tooltip={(d) => d.source
72  ? <strong>{d.source} → {d.target}: {d.value}</strong>
73  : <strong>{d.label}</strong>}
74  onClick={(d) => toggleGroup(d.group)}
75  title="Adjacency flow journey"
76  description="Ordered weighted flows; forward routes are upper-right and reversals lower-left."
77  summary="Three phases dominate, with backtracking concentrated in the middle phase."
78  accessibleTable
79  width={900}
80  height={700}
81  />
82  )
83 }
84