Flowgraph

D3Blocks.flowgraph(df, nodes=None, groups: dict = None, direction: str = None, layout: str = 'dagre', shape: str = 'process', color: str = 'group', cmap: str = 'Set2', edge_color: str = '#8c8c8c', nodesep: int = 40, ranksep: int = 70, edgesep: int = 20, ranker: str = 'network-simplex', curve: str = 'smooth', animate: bool = False, draggable: bool = True, show_edge_labels: bool = True, show_groups: bool = True, font: dict = {'size': 13}, title: str = 'Flowgraph - D3blocks', filepath: str = 'flowgraph.html', figsize=[None, None], showfig: bool = True, overwrite: bool = True, notebook: bool = False, save_button: bool = True, show_side_panel: bool = True, show_top_panel: bool = True, dark_mode: bool = True, color_background=None, return_html: bool = False, reset_properties: bool = True)

Flowgraph block: process flows and architecture diagrams.

Nodes are arranged in ranks along the flow direction with a layered layout, drawn as flowchart shapes and optionally nested in groups such as swimlanes, services or network boundaries. The input is either an edge list or a Mermaid flowchart.

Parameters:

  • df (pd.DataFrame, str or path-like) –

    • DataFrame with the edges. Required columns: ‘source’, ‘target’. Optional columns: ‘label’ (edge text), ‘weight’ (line width), ‘variant’, ‘style’ (‘solid’, ‘dashed’, ‘dotted’), ‘color’ and ‘animation’.

    • str: a Mermaid flowchart, e.g. ‘flowchart LR; A[Start] –> B{Valid?}’, or Markdown text containing a ```mermaid block.

    • Path to a Markdown file (.md, .markdown) with a ```mermaid block, so the same diagram renders on GitHub, or to a .mmd / .mermaid file. From Markdown, the first flowchart block is used.

    Node shapes, edge labels, dotted/thick links and (nested) subgraphs are converted; nodes, groups and direction override what it defines.

  • nodes (pd.DataFrame or dict, (default: None)) –

    Per-node attributes keyed by node name (a ‘name’ column or the index):

    • ’label’: display text; use ‘n’ for line breaks.

    • ’shape’: ‘process’, ‘decision’, ‘terminal’, ‘io’, ‘subprocess’, ‘database’, ‘queue’, ‘document’, ‘external’ or ‘circle’.

    • ’group’: group (swimlane / boundary) the node belongs to.

    • ’color’: node colour; overrides color.

    • ’tooltip’: extra text or HTML shown on hover below the label.

  • groups (dict, (default: None)) – Group settings: {group: {‘label’: str, ‘parent’: str, ‘color’: hex}}. Use ‘parent’ to nest groups (e.g. a subnet inside a VPC). The short form {group: parent} is also accepted.

  • direction (str, (default: None)) – Flow direction: ‘LR’, ‘TB’ (or ‘TD’), ‘RL’ or ‘BT’. None: the direction of the Mermaid header, otherwise ‘LR’.

  • layout (str, (default: 'dagre')) –

    • ‘dagre’: layered layout with smooth edges; small output (~0.5 MB).

    • ’elk’: ELK layered layout with orthogonal edge routing and native nested groups; tidier for architecture diagrams, adds ~1.5 MB to the HTML.

  • shape (str, (default: 'process')) – Default shape for nodes without one.

  • color (str, (default: 'group')) –

    • ‘group’: colour nodes by group.

    • ’shape’: colour nodes by shape.

    • ’#RRGGBB’: one colour for all nodes.

  • cmap (str, (default: 'Set2')) – Colormap for group / shape colouring.

  • edge_color (str, (default: '#8c8c8c')) – Default edge colour.

  • nodesep (int, (default: 40)) – Pixels between nodes in the same rank.

  • ranksep (int, (default: 70)) – Pixels between ranks.

  • edgesep (int, (default: 20)) – Pixels between parallel edges.

  • ranker (str, (default: 'network-simplex')) – dagre ranking algorithm: ‘network-simplex’, ‘tight-tree’ or ‘longest-path’.

  • curve (str, (default: 'smooth')) – Edge shape: ‘smooth’ (curved, or rounded corners with ELK) or ‘straight’.

  • animate (bool, (default: False)) – Animate pulses along the edges to show the direction of flow.

  • draggable (bool, (default: True)) – Nodes can be dragged; connected edges and groups follow.

  • show_edge_labels (bool, (default: True)) – Draw edge labels.

  • show_groups (bool, (default: True)) – Draw groups as containers (and keep their members together).

  • font (dict, (default: {'size': 13})) – Font properties.

  • title (str, (default: 'Flowgraph - D3blocks')) – Title of the figure.

  • filepath (str, (default: 'flowgraph.html')) – File path to save the output. None: return HTML only.

  • figsize (list, (default: [None, None])) – [width, height] in pixels. None: full window.

  • showfig (bool, (default: True)) – Open the chart in the browser.

  • overwrite (bool, (default: True)) – Overwrite an existing file.

  • notebook (bool, (default: False)) – Display inline in a Jupyter notebook, isolated in an iframe sized by figsize (default: full width x 650 px). The returned HTML is then that iframe.

  • save_button (bool, (default: True)) – Show the SVG/PNG save buttons.

  • show_side_panel (bool, (default: True)) – Show the left side panels (Export / Save, Layout, Legend).

  • show_top_panel (bool, (default: True)) – Show the top bar (logo, search, fit, theme).

  • dark_mode (bool, (default: True)) – Start in the dark theme.

  • color_background (list of str, str, or None, (default: None)) – Backgrounds for center / top / side panels as [dark_hex, light_hex]. Named themes: 'streamlit', 'darkblue'. None → ['#222222', '#ffffff'].

  • return_html (bool, (default: False)) – Return the HTML string.

  • reset_properties (bool, (default: True)) – Recompute node and edge properties from the input.

Returns:

  • d3.node_properties (DataFrame of dictionary) – Node properties; edit and call d3.show() to update.

  • d3.edge_properties (DataFrame) – Edge properties; edit and call d3.show() to update.

  • d3.config (dictionary) – Configuration. d3.config[‘groups’] holds the group settings (merged with Mermaid subgraphs); edit and call d3.show(). Labels, nesting and colours are resolved from it on every draw.

Examples

>>> # Edge list with shapes and edge labels
>>> import pandas as pd
>>> from d3blocks import D3Blocks
>>> d3 = D3Blocks(frame=False)
>>> df = pd.DataFrame({'source': ['Start', 'Valid?', 'Valid?', 'Fix'],
...                    'target': ['Valid?', 'Done', 'Fix', 'Valid?'],
...                    'label': ['', 'yes', 'no', 'retry']})
>>> nodes = {'Start': {'shape': 'terminal'}, 'Valid?': {'shape': 'decision'},
...          'Done': {'shape': 'terminal'}}
>>> d3.flowgraph(df, nodes=nodes, direction='TB')
>>> # Change a node and redraw
>>> d3.node_properties['Fix']['color'] = '#e15759'
>>> d3.show()
>>>
>>> # Mermaid diagram kept in a Markdown file (renders on GitHub too)
>>> d3.flowgraph('docs/process.md')
>>>
>>> # Mermaid flowchart with a subgraph, laid out with ELK
>>> d3.flowgraph('''
... flowchart LR
...   subgraph api [API]
...     gw[Gateway] --> svc[Orders]
...   end
...   svc --> db[(Postgres)]
...   svc -.->|events| q[[Worker]]
... ''', layout='elk')

References

Input Data

The input is either an edge list (DataFrame) or a Mermaid flowchart (string). The edge list needs the columns source and target; all other columns are optional.

#        source         target  label   variant animation
# 0       start          check                       None
# 1       check           pick    yes  emphasis     comet
# 2       check      backorder     no     error      None
# 3   backorder          check  retry     async      dots

Per-node attributes (label, shape, group, color, tooltip) are passed with nodes, and group settings (label, parent, color) with groups.

  • Shapes: process, decision, terminal, io, subprocess, database, queue, document, external, circle.

  • Edge variants: default, emphasis, security, async, error. Each sets a colour, line style and width; an edge’s own color and style override it.

  • Animations: pulse, dash, dots, comet for the whole chart (animate=) or per edge (animation column).

Process flow

import pandas as pd
from d3blocks import D3Blocks

edges = pd.DataFrame({
    'source': ['start', 'check', 'check', 'fix'],
    'target': ['check', 'done', 'fix', 'check'],
    'label':  ['', 'yes', 'no', 'retry'],
})
nodes = {
    'start': {'label': 'Start', 'shape': 'terminal'},
    'check': {'label': 'Valid?', 'shape': 'decision'},
    'fix':   {'label': 'Fix input'},
    'done':  {'label': 'Done', 'shape': 'terminal'},
}

d3 = D3Blocks(frame=False)
d3.flowgraph(edges, nodes=nodes, direction='TB')

# Change a node and redraw
d3.node_properties['fix']['color'] = '#e15759'
d3.show()

Mermaid input

Node shapes, edge labels, dotted (-.->) and thick (==>) links, &, chains, nested subgraphs and colours from style / classDef are converted.

d3.flowgraph('''
flowchart LR
    start([Order received]) --> check{In stock?}
    check -->|yes| pick[Pick & pack]
    check -- no --> back[[Backorder]] -.->|restocked| check
    subgraph wh [Warehouse]
        pick --> ship[/Ship parcel/]
    end
    ship ==> done([Delivered])
''')

The diagram can also live in a Markdown file as a fenced mermaid block, so GitHub renders it too; pass the file path (.md, .markdown, .mmd or .mermaid). From Markdown, the first flowchart block is used.

d3.flowgraph('docs/order_process.md')

Architecture diagram

Groups can be nested with parent. layout='elk' uses ELK’s layered layout with orthogonal edge routing; it suits nested architecture diagrams but adds about 1.5 MB to the HTML file.

groups = {
    'Cloud': {'label': 'Cloud account'},
    'VPC': {'parent': 'Cloud'},
    'App subnet': {'parent': 'VPC'},
    'Data subnet': {'parent': 'VPC'},
}
nodes = {
    'api': {'label': 'API', 'group': 'App subnet'},
    'worker': {'label': 'Worker', 'group': 'App subnet'},
    'db': {'label': 'PostgreSQL', 'shape': 'database', 'group': 'Data subnet'},
    'bus': {'label': 'Event bus', 'shape': 'queue', 'group': 'Data subnet'},
    'users': {'label': 'Users', 'shape': 'circle'},
}
edges = pd.DataFrame({
    'source':  ['users', 'api', 'api', 'bus'],
    'target':  ['api', 'db', 'bus', 'worker'],
    'label':   ['HTTPS', 'SQL', 'publish', 'consume'],
    'variant': ['emphasis', 'default', 'async', 'async'],
})
d3.flowgraph(edges, nodes=nodes, groups=groups, layout='elk', animate='dots')

Jupyter and Streamlit

In a notebook, pass notebook=True; the chart is shown inline, isolated in an iframe sized by figsize (default: full width x 650 px). See notebooks/flowgraph.ipynb.

d3 = D3Blocks(frame=False)
d3.flowgraph(edges, nodes=nodes, notebook=True, filepath=None, figsize=[None, 520])

In Streamlit, generate the HTML with return_html=True and embed it with st.iframe. streamlit/flowgraph_streamlit_demo.py edits a Mermaid flowchart in the sidebar and re-renders it with the chosen layout, direction and animation.

html = D3Blocks().flowgraph(flowchart, filepath=None, showfig=False, return_html=True)
st.iframe(html, height=700, width="stretch")

Interaction

  • Hover a node to trace everything upstream and downstream; click to pin.

  • ▶ Trace walks through the flow step by step (from the pinned node, or from all start nodes).

  • Drag nodes; edges and groups follow. Reset layout recomputes the layout.

  • The Layout panel changes direction, spacing, font size, edge curve and animation.

  • The Legend panel lists groups and the edge variants in use.

  • Export to SVG, PNG or JSON (including computed positions).