Waterfall Chart

A waterfall chart: how an amount comes about, step by step. Each bar starts where the one before it ended, going up for what a row adds and down for what it takes away, and a total stands on nought and shows what the steps before it come to.

import com.pantrixui.components.chart.waterfall.PantrixWaterfallChart

• Steps. A row's value is the amount it adds; below zero, what it takes away. A step that adds is drawn in the chart's rising colour and one that takes away in its falling colour: the theme's success and danger colours, unless colors says otherwise.
• Totals. A row that total says is a total stands on zero and shows what the steps before it come to; its own value is not asked for. A total with a value of its own is where the count starts again: like the opening amount before the first step. Totals are drawn in the series' own colour (color).
• Connecting lines. A thin line goes from the end of each bar to where the next begins (connectors).
• Zero. The value axis takes zero in: the totals stand on it.
• Value labels. labels writes what each bar stands for at its end: over one that goes up, under one that goes down.
• Horizontal. horizontal = true sets the items down the side of the chart; each bar starts where the one above it ended, and one that adds goes right, one that takes away left (the other way about in a language read from the right). The values are written under the chart.
• Automation. The chart is tagged as the PantrixChart it is: Chart_<tagKey>. Its one series has the key steps.

Examples

From opening to closing

A quarter's cash flow: the opening amount, income, expenses and the closing. The opening is a total with a value of its own: the count starts from it. The closing has no value: it shows what the steps come to.

Move the pointer over a bar, or touch the bar: the tooltip writes the step with its sign. The thin lines between the bars show that each step starts where the one before it ended.

PantrixWaterfallChart(
    data = QUARTER_CASH,
    x = { it.name },
    y = { it.amount },
    name = "Cash (thousand TL)",
    total = { it.total },
    description = "A quarter's cash flow, from opening to closing",
    tagKey = "plain"
)

private data class CashMove(
    val name: String,
    val amount: Int?,
    val total: Boolean = false
)

private val QUARTER_CASH = listOf(
    CashMove("Opening", amount = 420, total = true),
    CashMove("Sales", amount = 310),
    CashMove("Services", amount = 120),
    CashMove("Salaries", amount = -260),
    CashMove("Rent", amount = -90),
    CashMove("Tax", amount = -70),
    CashMove("Closing", amount = null, total = true)
)

Subtotals

Subtotals along the way: at the end of each quarter, what has been reached so far. A subtotal stands on zero, and the count goes on after it from where it was.

PantrixWaterfallChart(
    data = HALF_YEAR_CASH,
    x = { it.name },
    y = { it.amount },
    name = "Cash (thousand TL)",
    total = { it.total },
    description = "Monthly change in cash over half a year, with a subtotal at the end of each quarter",
    tagKey = "subtotals"
)

private data class CashMove(
    val name: String,
    val amount: Int?,
    val total: Boolean = false
)

private val HALF_YEAR_CASH = listOf(
    CashMove("Jan", amount = 180),
    CashMove("Feb", amount = -60),
    CashMove("Mar", amount = 140),
    CashMove("Q1", amount = null, total = true),
    CashMove("Apr", amount = -110),
    CashMove("May", amount = 90),
    CashMove("Jun", amount = 210),
    CashMove("Q2", amount = null, total = true)
)

The values at the ends of the bars

What each bar stands for is written at its end (labels): over a step that adds and under a step that takes away, with its sign; over a total, as it is.

A label that has no room is left out; the value stays in the tooltip and for the screen reader.

PantrixWaterfallChart(
    data = QUARTER_CASH,
    x = { it.name },
    y = { it.amount },
    name = "Cash (thousand TL)",
    total = { it.total },
    labels = ChartDataLabels(),
    description = "A quarter's cash flow, with its values",
    tagKey = "labels"
)

private data class CashMove(
    val name: String,
    val amount: Int?,
    val total: Boolean = false
)

private val QUARTER_CASH = listOf(
    CashMove("Opening", amount = 420, total = true),
    CashMove("Sales", amount = 310),
    CashMove("Services", amount = 120),
    CashMove("Salaries", amount = -260),
    CashMove("Rent", amount = -90),
    CashMove("Tax", amount = -70),
    CashMove("Closing", amount = null, total = true)
)

Horizontal

The same quarter, horizontal (horizontal = true): the items are set down the side of the chart, and each bar starts where the one above it ended. Where the items have long names, or are many, a horizontal waterfall is easier to read.

PantrixWaterfallChart(
    data = QUARTER_CASH,
    x = { it.name },
    y = { it.amount },
    name = "Cash (thousand TL)",
    total = { it.total },
    horizontal = true,
    labels = ChartDataLabels(),
    description = "A quarter's cash flow, in horizontal bars",
    tagKey = "horizontal_steps"
)

private data class CashMove(
    val name: String,
    val amount: Int?,
    val total: Boolean = false
)

private val QUARTER_CASH = listOf(
    CashMove("Opening", amount = 420, total = true),
    CashMove("Sales", amount = 310),
    CashMove("Services", amount = 120),
    CashMove("Salaries", amount = -260),
    CashMove("Rent", amount = -90),
    CashMove("Tax", amount = -70),
    CashMove("Closing", amount = null, total = true)
)

Your own colours

The two colours of the steps come from the chart's colours (the rising and falling fields of ChartColors), and the totals' colour from the series itself (color). Turn the switch: the lines between the bars go away (connectors).

Colour should not carry the meaning alone: which way a step goes is also read from where its bar starts and ends, and from the sign of its value.

var connectors by remember { mutableStateOf(true) }
val theme = PantrixTheme.colors
PantrixSwitchButton(
    checked = connectors,
    onCheckedChange = { connectors = it },
    label = "Connecting lines",
    tagKey = "waterfall_connectors"
)
PantrixWaterfallChart(
    data = QUARTER_CASH,
    x = { it.name },
    y = { it.amount },
    name = "Cash (thousand TL)",
    total = { it.total },
    connectors = connectors,
    color = theme.neutral.color,
    colors = ChartColors(rising = theme.info.color, falling = theme.warning.color),
    description = "A quarter's cash flow, in its own colours",
    tagKey = "own_colors"
)

private data class CashMove(
    val name: String,
    val amount: Int?,
    val total: Boolean = false
)

private val QUARTER_CASH = listOf(
    CashMove("Opening", amount = 420, total = true),
    CashMove("Sales", amount = 310),
    CashMove("Services", amount = 120),
    CashMove("Salaries", amount = -260),
    CashMove("Rent", amount = -90),
    CashMove("Tax", amount = -70),
    CashMove("Closing", amount = null, total = true)
)

Pressing a step

A press is handed the step and the level it starts from: the point's value is what the step adds and its from the level the step starts from; the two together are what is reached after the step. A total has no from. Press a bar: the line below writes what was pressed.

var pressed by remember { mutableStateOf<String?>(null) }
val strings = PantrixTheme.strings
PantrixWaterfallChart(
    data = QUARTER_CASH,
    x = { it.name },
    y = { it.amount },
    name = "Cash (thousand TL)",
    total = { it.total },
    onSelect = { point ->
        val start = point.from
        pressed = if (start == null) {
            "${point.label}: total ${point.text}"
        } else {
            "${point.label}: ${point.text}, then ${strings.decimal(start + point.value)}"
        }
    },
    description = "A quarter's cash flow",
    tagKey = "press"
)
PantrixText(text = pressed ?: "Press a bar")

private data class CashMove(
    val name: String,
    val amount: Int?,
    val total: Boolean = false
)

private val QUARTER_CASH = listOf(
    CashMove("Opening", amount = 420, total = true),
    CashMove("Sales", amount = 310),
    CashMove("Services", amount = 120),
    CashMove("Salaries", amount = -260),
    CashMove("Rent", amount = -90),
    CashMove("Tax", amount = -70),
    CashMove("Closing", amount = null, total = true)
)

The long form

The chart the short form stands for: a PantrixChart with one WaterfallSeries. The short form's horizontal = true is orientation = ChartOrientation.Horizontal in the long form, and the series carries its key and its name itself. A screen that wants the waterfall together with other things writes it this way: here a line for the closing target.

PantrixChart(
    series = listOf(
        WaterfallSeries(
            key = "cash",
            name = "Cash (thousand TL)",
            data = QUARTER_CASH,
            x = { it.name },
            y = { it.amount },
            total = { it.total }
        )
    ),
    orientation = ChartOrientation.Horizontal,
    marks = listOf(ChartReferenceLine(y = 500, label = "Target")),
    description = "A quarter's cash flow and the closing target, in horizontal bars",
    tagKey = "as_series"
)

private data class CashMove(
    val name: String,
    val amount: Int?,
    val total: Boolean = false
)

private val QUARTER_CASH = listOf(
    CashMove("Opening", amount = 420, total = true),
    CashMove("Sales", amount = 310),
    CashMove("Services", amount = 120),
    CashMove("Salaries", amount = -260),
    CashMove("Rent", amount = -90),
    CashMove("Tax", amount = -70),
    CashMove("Closing", amount = null, total = true)
)

API

data

A waterfall chart: how an amount comes about, step by step. Each bar starts where the one before it ended, going up for what a row adds and down for what it takes away, and a total stands on nought and shows what the steps before it come to.

ChartStyle

A chart's geometry: how tall it is where nothing says, how thick its lines and how large its marks are, and the room between its parts; and whether its fills have textures besides their colours.

ChartColors

What a chart is painted with, for a chart that does not take the theme's colours: a colour that is set is used, and one that is left out stays the theme's.

Accessibility

• Tooltip and screen reader. A step is written as what it adds, with its sign ("+310"); a total as what it comes to. A press is handed the step as the point's value and the level the step starts from as its from.