Sankey flow

Who it’s for

Whoever has to account for something that arrives, splits and leaves. An energy manager explaining where a site’s kilowatt-hours actually went, a water utility separating what was pumped from what was billed, a plant engineer showing that a third of the compressed air never reaches a machine. They can already total each meter; what they cannot do with a table is show the shape of the distribution, or make a loss visible as anything other than subtraction done off-screen.

What it does

A site takes 520 kWh from the grid and 180 from its own array. Seven hundred reaches the main board, and 670 leaves it: 430 to production, 180 to HVAC, 60 to lighting. Production splits 260 and 170 between two lines. Every band is as wide as the energy it carries, and the 30 kWh that entered the board and never came out the other side is visible as the gap it leaves.

• Draws the distribution, not the totals. Which consumer dominates, where a split happens and how unevenly, are all read from the shape rather than compared number by number.
• Makes losses visible as a gap. A node that takes in more than it lets out is drawn that way, so what is missing is shown rather than calculated.
• Builds the diagram from the data keys themselves. Each key carries the two nodes it runs between, so there is no separate map of the topology to keep in step with the keys as they change.
• Names each node with what passes through it, which is the larger of what arrives and what leaves.
• Refuses a diagram it cannot draw honestly. Flows that run in a circle are named in an error rather than quietly producing nothing.
• Shows measured flows. It will not divide one total among several consumers in proportion — that would be an invention, not a measurement.

How to set up

Data keys

One data key per flow. The number of keys is the number of bands you want; the nodes cost nothing and appear from the names you type.

• One key per band — Timeseries or Attribute. A measured flow, added on any datasource. Units and decimals come from the key. Negative readings are taken as magnitude, since the direction is set by the two node names rather than by the sign.

Each key carries its own two ends, set in the key’s own settings rather than in the widget’s: Flows from is the node the key leaves, Flows to the node it arrives at.

A worked example — one site meter, four keys:

• gridImport flows from Grid to Main board
• solarYield flows from Solar to Main board
• productionEnergy flows from Main board to Production
• hvacEnergy flows from Main board to HVAC

Four keys, five nodes. The names are matched exactly, so Main board and Main Board become two separate nodes and the diagram falls into two unconnected halves. A key with either end blank is left out; one whose two ends are the same is ignored.

Flows

• How each flow is taken from the time window — sum over the window by default. Sum is right when the keys are quantities over the period, which is what a flow usually is; set the dashboard aggregation to SUM to match, since summing averages is not a total. Change over the window suits meters that only climb.
• Leave out flows that came to zero — on by default. A flow of nothing draws a band of no width and still reserves a node.

How to customize

• To make a node easy to follow across the diagram — leave How the nodes are colored on a distinct color each. Where the bands cross, color is what lets the eye keep hold of one. One color for all is calmer and leans on position instead, and Nodes sets it.
• To follow where flows come from or go to — set How the bands are colored. A gradient carries the eye from source to target; coloring by source follows what produced a flow, by target what consumed it. Bands sets the single color when you pick one.
• To keep crossing bands readable — adjust Band opacity (%). Bands overlap by nature, so they have to be transparent enough that the one underneath still reads.
• To fit a busier diagram — reduce Node thickness (px) and Gap between nodes (px). A narrower gap leaves more height for the bands themselves; a wider one separates a crowded column.
• To free up room — turn off Name the nodes on the diagram, or just Put each node’s throughput beside its name. The tooltip still names a node on hover either way. Label font and Label style them.
• To change the headline — Show the busiest node beside the title and Caption for it. It is deliberately not the sum of every band: a flow crossing three stages would be counted three times, so the busiest node is the honest single number for how much moved. Caption font, Caption, Value font and Value style it.

Tips

• Draw the stages you can measure, and stop. A diagram with one invented split costs more trust than the three measured ones earn.
• Put the loss where it belongs by leaving it out. Do not add a “Losses” key unless something actually meters it — the gap between what a node takes in and lets out already says it, and says it honestly.
• Keep it under about twenty bands. Past that the labels collide and the shape stops being readable; two diagrams, one for sources and one for the floor, say more than one crowded diagram.
• Copy node names rather than retyping them. A single capital letter out of place silently splits one node into two, and the diagram will look plausible while being wrong.
• Wire a node click to a dashboard state so the diagram becomes the way into a stage rather than only a picture of one.