kuva sankey

Sankey / alluvial flow diagram.

kuva sankey supports two input modes:

  • Edge-list Sankey input: source node, target node, flow value.
  • Wide alluvium input: one ordered --axis-col per stage, plus an optional --value-col.
FlagDefaultDescription
--axis-col <COL>repeatableOrdered alluvium axis columns; switches the parser into wide alluvium mode
--source-col <COL>0Source node column
--target-col <COL>1Target node column
--value-col <COL>2Flow value column
--link-gradientoffFill each link with a gradient from source node colour to target node colour
--opacity <F>0.5Link opacity
--legend <LABEL>—Show legend
--node-order <MODE>inputNode ordering within columns: input, crossings, or neighbornet
--node-order-seed <N>42RNG seed for crossing-reduction ordering
--coloring <MODE>labelNode coloring mode: label or left
--flow-labelsoffShow absolute flow values on ribbons
--flow-percentoffShow each ribbon as a percent of source outflow
--flow-label-format <FMT>autoFlow label number format: auto, sci, integer, fixed2
--flow-label-unit <UNIT>—Unit suffix appended to absolute flow labels
--flow-label-min-height <F>8.0Minimum ribbon height required to render a label

Edge-list mode

Use classic source-target-value input when your flow table is already stored as edges:

kuva sankey sankey.tsv \
    --source-col source --target-col target --value-col value

kuva sankey sankey.tsv \
    --source-col source --target-col target --value-col value \
    --link-gradient --legend "read flow"

Alluvium mode

Use repeated --axis-col flags for ordered categorical stages. kuva will build full alluvia, aggregate adjacent links, and optionally apply wompwomp-style ordering and left-to-right color propagation:

kuva sankey alluvium.tsv \
    --axis-col tissue --axis-col cluster --axis-col sex \
    --value-col count \
    --node-order crossings \
    --node-order-seed 42 \
    --coloring left \
    --title "Ordered Alluvium"

kuva sankey alluvium.tsv \
    --axis-col tissue --axis-col cluster --axis-col sex \
    --value-col count \
    --node-order neighbornet \
    --coloring label \
    --title "NeighborNet Alluvium"

--node-order crossings uses a TSP-based weighted crossing-reduction algorithm: it builds a co-occurrence distance matrix, finds a node cycle via nearest-neighbour + 2-opt, then tries every rotation to minimise the weighted ribbon-crossing count. The axis column order you specify with --axis-col is always preserved exactly — only the vertical stacking of nodes within each column is changed.

--node-order neighbornet switches to the neighbornet backend for cycle generation; try it when the default layout is still cluttered, especially on data with tree-like co-occurrence structure.

--coloring left propagates colors from dominant parents left-to-right; --coloring label assigns one palette color per visible label.

See also: Shared flags — output, appearance, axes, log scale.