Sankey diagrams

TL;DR

Ask your agent

Use Plotwork to draw a sankey diagram of where our monthly cloud bill goes: from the bill to each service, then to the team that owns it, and then to the product it pays for, with the amounts in dollars.

Use Plotwork to draw a sankey diagram of what happens to 10,000 requests per second: served from the cache or from the origin, rejected, or failed, with failures in red and no amounts on the cards.

Example

PictureSourceOutline

The nodes take their tones in turn in the order they first appear, and tone= changes one: the cache is aqua, and what goes wrong is red. The ribbon from Edge to Blocked skips two columns, so it has a lane under the gateway and the services and never passes behind a card. Every node here balances, so what goes in comes out and no wedge is drawn. The line under the picture says the unit, the total that enters, and how much there is of it.

The language

One statement to a line. Text is always in double quotes, options are key=value, and # starts a comment. Indentation means nothing to the parser.

A node's name is its identity, so writing the same name in two flows is one node. Write each pair of nodes once, with the total: a second line for the same pair is refused with E130. A node line for a name that no flow uses is refused, because a node with no flow has no size.

1sankey "Orders" unit="orders"2
3"Visits" -> "Carts" : 30004"Visits" -> "Left" : 70005"Carts" -> "Paid" : 1400 tone=green6"Carts" -> "Abandoned" : 1600 tone=amber

Header options

Columns and order

A node sits one column to the right of the furthest node that flows into it. Within a column the order is chosen to cross as few ribbons as possible, and the same source always gives the same picture. A flow that skips a column gets a lane in each column it passes, so it runs between the cards.

With align=left a funnel reads from left to right, and each outcome sits beside the stage it leaves:

PictureSourceOutline

With values=off the picture shows the shapes and the line under it keeps the total. The text description still lists every amount.

Cost by service, team, and product

When many ribbons cross, the order keeps related nodes together and the gradient shows where each ribbon goes. Amounts of 10,000 and more are drawn compactly on a card ($42K), and in full in the text description.

PictureSourceOutline

A pipeline that narrows

A sankey shows where records go as stages drop some of them. Each stage here passes on what it received less what it set aside:

PictureSourceOutline

Flow that does not balance

What goes into a node should come out of it, with the rest drawn as a flow to a node of its own. When it does not, the card gets a dashed wedge as thick as the difference: on its right edge for flow lost, on its left edge for flow gained, with -60 or +80 beside it when there is room. Lint warns with W200, names the node, and says what to do. A difference of half a percent or less is rounding and draws nothing. A node with flow on one side only, a source or an end, never counts.

1sankey "Ingest" unit="MB/s"2
3"Web" -> "Ingest" : 10004"Ingest" -> "Validate" : 940

Here Ingest takes in 1,000 and passes on 940, so it loses 60. Add a flow such as "Ingest" -> "Duplicates" : 60 to account for it.

Colour

Each node takes the next of blue, orange, aqua, violet, amber, green, and neutral in the order the nodes first appear. Red is left out of the rotation because it is what you choose for a failure, so a node is never red by accident. tone= on a node changes it, and tone= on a flow colors that ribbon alone. A ribbon takes the tone of the node it leaves and fades to the tone of the node it reaches. Nobody writes a color value: the theme owns every color in light and dark.

What a card and a ribbon show

A card holds its icon on a chip, its name, and its amount. It is as wide as its widest word and its amount need, and its name wraps to three lines before it is cut with an ellipsis and W203. It is as tall as the amount through it, or as its content needs when that is more, and a small card keeps its ribbons in its middle. An amount appears on a ribbon at least 10px thick, where there is a clear place for it, and never over a card or another amount. The text description lists every flow with its amount and its share of what leaves its source.

Limits and warnings

The picture is 880px wide for up to four columns, the width a Markdown column keeps text readable at. More columns need more room, so a picture of eight columns is a little over 1,100px and lint says W202 when it would shrink text too far. The layout is plain arithmetic, so a sankey of 60 nodes and 150 flows is laid out in a few milliseconds.

Every mistake comes back as a result with a code, a line, a column, and a hint. Warnings never stop the drawing.

From Mermaid

Mermaid sankey-beta (and sankey, which Mermaid is renaming it to) converts to a sankey. Each line is Source,Target,Value, a name with a comma is in double quotes, and a %% comment or a blank line is skipped. Ask your agent to convert it, or use the convert_mermaid tool. The migration guide covers the converter in full.

1---2title: Product budget3config:4  sankey:5    showValues: false6---7sankey-beta8
9%% source,target,value10Budget,Engineering,60011Budget,Marketing,25012Budget,Support,15013Engineering,Platform,40014Engineering,Application,20015Marketing,Campaigns,20016Marketing,Events,5017Marketing,Events,018Support,"Help centre, docs",10019Support,Tooling,5020Support,Tooling,0

The converter reports the settings it dropped (M200) and the two flows of zero it dropped (M216):

1sankey "Product budget"2
3"Budget" -> "Engineering" : 6004"Budget" -> "Marketing" : 2505"Budget" -> "Support" : 1506"Engineering" -> "Platform" : 4007"Engineering" -> "Application" : 2008"Marketing" -> "Campaigns" : 2009"Marketing" -> "Events" : 5010"Support" -> "Help centre, docs" : 10011"Support" -> "Tooling" : 50

See also