schrodinger.seam.viz.flowchart module

class schrodinger.seam.viz.flowchart.FlowDirection

Bases: Enum

Direction of flow between connected nodes in a chart.

HORIZONTAL = 0

VERTICAL = 1

class schrodinger.seam.viz.flowchart.FlowChartGenerator(graph: DiGraph, sources: list, text_rotation: float = 0, text_size: int = 7)

Bases: object

Generate a flow-chart style image of a directed acyclic graph (DAG).

Nodes are drawn as vertical bars whose height is proportional to a numeric value attribute, and connected by curved ribbons that visualize the flow of data through a pipeline.

Visualization philosophy:

• Main chain first: the longest path through the DAG is placed on lane 0, giving the reader a clear left-to-right narrative.

• Branches stay close: side branches are placed on adjacent lanes so the chart remains compact and easy to scan vertically.

• Labels never overlap rectangles: lane spacing is computed with a closed-form formula that accounts for text height scaling with the data range, guaranteeing clearance even when node values span several orders of magnitude.

Example:

----> 2 ----------|
|                 v
0 --> 1 --> 3 --> 4

>>> G = nx.DiGraph()
>>> for i in range(5):
...     G.add_node(i, value=i + 1)
>>> G.add_edges_from([(0, 1), (0, 2), (1, 3), (2, 4), (3, 4)])
>>> generator = FlowChartGenerator(graph=G, sources=[0])
>>> generator.generate(Path("test.pdf"))

Graph terminology:

Source node

A node with no predecessors in the subgraph being laid out. Sources are the entry points of the pipeline; each is placed in column 0 on its own lane.

Split node

A node with multiple successors (out-degree > 1). The successor with the longest downstream path inherits the parent’s lane; the remaining successors are assigned fresh lanes to form side branches.

Merge node

A node with multiple predecessors (in-degree > 1). The merge follows the predecessor with the longest upstream path so the main chain stays on a single lane. If all predecessors share a lane and a skip edge is involved, the merge is pushed to a higher lane to avoid overlapping the intermediate nodes.

Layout terminology:

Lane

Horizontal band across the chart. Nodes on the same lane share a y-baseline. Lane 0 is the main chain; higher lane numbers are drawn above it. Each node’s lane is stored in its LANE_KEY attribute; its y-offset is lane * spacing.

Column (layer)

Horizontal position in the chart. All nodes in the same column are drawn at the same x-coordinate. Columns are determined by the topological order of the DAG (see _getLayers).

Skip edge

An edge whose source and target are more than one column apart (i.e., not in adjacent columns).

Ribbon

The bezier-curve connector drawn between two nodes to visualize flow. Its vertical extent reflects the nodes’ values.

VALUE_KEY = 'value'

DISPLAY_NAME_KEY = 'display_name'

LANE_KEY = 'lane'

COLUMN_KEY = 'col'

MAX_HEIGHT = 1

CENTER_HEIGHT = 0.5

NODE_WIDTH = 0.01

NODE_WIDTH_SPACER = 0.075

DEFAULT_NODE_HEIGHT = 0.5

DEFAULT_FIGSIZE = (8, 5.33)

NODE_EDGE_COLOR = 'black'

NODE_FACE_COLOR = '#005AAA'

RIBBON_COLOR = '#54C9EF'

TEXT_COLOR = 'black'

__init__(graph: DiGraph, sources: list, text_rotation: float = 0, text_size: int = 7)

Parameters:

• graph – A directed acyclic graph (DAG) to visualize. Each node must have a ‘value’ attribute that is an integer. Optionally a ‘display_name’ attribute can be provided to use instead of the node key.

• sources – A list of source nodes to use as the starting point of the flow chart.

• text_rotation – The rotation in degrees to use for text in the flow chart.

• text_size – The font size to use for text in the flow chart.

generate(image_path: Path, figsize: tuple[float, float] = (8, 5.33)) → None

Parameters:

• image_path – Path to save the generated image.

• figsize – Size of the figure to create in inches (width, height).

customAdjustments(graph: DiGraph) → None

Hook for subclasses to make any custom adjustments to the graph before rendering.

Nodes are laid out by their self.LANE_KEY and self.COLUMN_KEY attributes. A default layout is provided, but subclasses can modify these attributes in this method to change the layout of the flow chart.

Parameters:

graph – The graph to make any custom adjustments to before rendering.