Process flows
Visualize how quantities move between stages, categories, or entities.
Plotly · Class
go.Sankey
go.Sankey creates an interactive flow diagram in Plotly. Nodes are named with labels, while indexed links connect sources to targets and use values to control flow width.
How it works
go.Sankey constructs a Sankey trace for a Plotly figure. Define nodes with labels and links with parallel source, target, and value arrays; each link uses zero-based node indices, and its rendered width reflects the corresponding flow value.
Syntax
go.Sankey(arg=None, arrangement=None, customdata=None, domain=None, hoverinfo=None, hoverlabel=None, hovertemplate=None, ids=None, link=None, meta=None, name=None, node=None, orientation=None, selectedpoints=None, stream=None, textfont=None, uid=None, uirevision=None, valueformat=None, valuesuffix=None, visible=None)Returns
A Plotly Sankey trace object suitable for inclusion in a Figure.
Key points
- Sankey traces visualize flows by making link widths proportional to their associated quantities.
- Links use source and target node references plus value for the flow amount.
- Node labels provide the names displayed for the nodes.
- Source and target values refer to positions in the node-label sequence.
- The trace is available through Plotly's graph_objects module.
Common mistakes
- The link arrays are index-based: source and target identify nodes, while value supplies each flow amount; keep their lengths aligned.
Example: Basic Sankey diagram
import plotly.graph_objects as go
fig = go.Figure(go.Sankey(
node=dict(label=["A", "B", "C"]),
link=dict(source=[0, 1], target=[1, 2], value=[8, 4])
))
fig.show()Creates a Sankey figure whose node labels identify entities and whose links connect source and target indices with widths based on their values.
When to use it
Energy or resource accounting
Show contributions from inputs to outputs across multiple levels.
Quantitative relationship maps
Communicate transfers where magnitude matters as much as connectivity.
Interview questions
QWhat data model does a Plotly Sankey trace use?
A Sankey diagram represents flow quantities between nodes. In Plotly, node labels name the nodes, while each link connects indexed source and target nodes and uses value to determine flow volume.
Follow-up: How would you encode a link from the first node to the third? Use source=[0] and target=[2], because the node references are zero-based indices into the label list.
QHow are links associated with nodes and quantities?
The source and target arrays contain node indices, and the value array contains the corresponding flow quantities. The arrays are paired by position, so source[i], target[i], and value[i] describe one link.
Follow-up: What should be checked when adding links? Verify that every referenced index exists in the node labels and that the three link arrays describe the same number of flows.
QHow do you display a Sankey chart in Plotly Python?
Add the trace to a go.Figure and render it with fig.show(). The trace can be created directly as go.Sankey(...) inside the figure constructor.
Follow-up: How can node presentation be customized? Supply additional node attributes such as pad, thickness, line, label, or color in the node dictionary.
Related
plotly.graph_objects.FigureSankey.nodeSankey.link