Waterfall chart

Who it’s for

Anyone who has a total and has to explain it. An energy manager asked why the site bill moved, a water utility accounting for the difference between what was pumped and what was billed, a production lead breaking a shift’s output into what was made and what was lost. They already know the number. What they are asked in the meeting is where it came from, and a column chart of the parts does not answer that, because it never shows the parts adding up.

What it does

Four keys on a site meter over one shift: grid import contributes +40 kWh, solar +18, export takes 7 back and losses another 4. The chart draws them as four bars that each start where the last one finished, joined by a line carrying the running total, and closes with a dark bar at 47 kWh. The header repeats it as +47 kWh, so the answer is readable from across the room.

• Turns a set of keys into the story of a total — what added, what took away, and what it came to.
• Colors each step by direction and marks which keys subtract, so a positive losses reading counts against the total instead of inflating it.
• Sums, averages or differences each key over the dashboard time window, so the same chart serves a live balance and a monthly one by changing the time picker.
• Reads keys from one entity or from many, and names the bars after whichever of the two actually varies, keeping the axis legible when the names are long.
• Optionally opens with a balance the period started from, turning a breakdown of change into a full opening-to-closing statement.
• Charts what the keys report. It does not compute a key from other keys, so a step that is itself a calculation belongs in a calculated field first.

How to set up

Data keys

Each data key on each datasource becomes one bar, in the order the keys are configured. That order is the order of the story, so arrange the keys the way the total should be read.

• One key per step — Timeseries or Attribute. A contribution to the total. Decimals and units are taken from the keys themselves. Steps with no reading in the window are skipped, and steps that come to zero are left out unless you ask for them. When no key has a reading the chart shows its no-data message.

Each key also carries its own Which way this step runs setting, in the key’s configuration rather than the widget’s:

• Use the sign in the data — the series is already signed, as a net value or a calculated field that returns negatives usually is.
• Adds to the total — the key contributes, whatever sign it arrives with.
• Subtracts from the total — the key takes away. Most telemetry needs this: losses, exported and scrap all arrive as plain positive numbers.

Steps

• How each step is taken from the time window — sum over the window by default. Sum for quantities over a period, such as kWh imported or units scrapped; set the dashboard aggregation to SUM to match, since summing averages is not a total. Change over the window for counters that only climb, paired with NONE or MAX aggregation. The rest read one value per key.
• What each bar is called on the axis — automatic by default, which names whatever varies between the steps: the entity when several are charted, the key when one entity contributes several, and both when both do. The axis prints as many of these names as fit side by side and leaves out the rest rather than crowding or shortening them. The tooltip always gives entity and key in full.
• Leave out steps that came to zero — on by default. A step worth nothing still takes a slot on the axis.

Opening and total

• Start from an opening balance — off by default. Adds a first bar measured from zero, so the steps build on the value the period started with.
• Opening value — 0 by default. The balance the period began with, in the same units as the steps.
• Close with a total bar — on by default. Adds a final bar from zero showing where the steps land. Without it the chart shows the movements but never states the result.

How to customize

• To change the direction colors — set Steps that add and Steps that subtract. Opening and total bars colors the two absolute bars, which are deliberately a different color from the steps because they are measured from zero rather than from each other.
• To rename the anchor bars — set Opening bar label and Total bar label. Closing, Result or Net all read better than Total in some reports.
• To fit more bars — reduce Bar width (% of the slot). Narrower bars also leave more room for the connecting lines to read.
• To drop the connecting lines — turn off Join the steps with a line. They carry the running total from one bar to the next; without them the chart is a row of floating bars and the sequence has to be inferred. Connecting line sets their color.
• To hide the values above the bars — turn off Print each step’s value above its bar. Value label font and Value label set how they look. Once the bars are too narrow for the values to sit side by side they come off together rather than half of them surviving, and the legend and the tooltip carry the numbers instead.
• To reclaim the width the axis takes — turn off Show the value axis. Keep the printed values on if you do, or the chart loses its scale entirely.
• To hide the legend — turn off Show a legend under the chart, which gives the chart the whole widget. On by default, it lists every step with its full name and its value, and clicking an entry takes that step out of the waterfall or puts it back — the fastest way to see what the total would be without one contributor.
• To match a dashboard’s typography — set Axis font and Axis, which also style the no-data message.
• To change the total in the header — Result caption names it and Caption font, Caption, Result font and Result style it. Turn off Show the result beside the title to leave the chart to speak for itself.

Tips

• Set the dashboard aggregation to match the step mode. Sum over the window with AVG aggregation sums a series of averages, which is not the total — the two settings have to agree or the numbers are quietly wrong.
• Mark the subtracting keys before reading anything into the result. Left on the sign in the data, a positive losses key adds to the total and the chart looks right while saying the opposite.
• Put the keys in the order the total is explained, not alphabetically or by size. A waterfall is a sentence, and the bars are its words.
• Past about eight bars the chart stops being a story and becomes a list. If the legend is carrying most of the meaning, the question is usually whether every one of those keys deserves its own step, or whether some of them belong grouped into one.
• Click steps off in the legend to answer “what would the total be without this?” without touching the configuration. It is the fastest way to size a single contributor against everything else, and clicking again puts it back.
• Use Start from an opening balance with a tank, a battery or a stock level, where the period starts from something rather than from nothing. Rename the result caption to Closing balance when you do.
• Keep the units the same across every key. Mixing kWh with m³ produces a total that means nothing, and the chart drops the unit from the result to say so.