Heatmap

A heatmap: a grid of cells, each in a shade that says how much its value is. It suits what has two names and a number: the hours of the days of a week, the months of several years, one list set against another. What is much and what is little is seen at a glance, where a table of the same numbers would have to be read.

import com.pantrixui.components.chart.heatmap.PantrixHeatmap

• Scale. HeatmapScale says how a value becomes a shade: its two ends (min, max; left out, the least and the most of the values), how many shades it has (steps; at nought each value has its own) and its colour (color). With one colour, a shade is a share of the colour on what the chart stands on: it reads in a light theme and a dark one. Given low, the scale goes from the least's colour low to color; the shades between are the two colours mixed in Oklab, each step changing as much as the one before.
• The value in a cell. With labels each cell has its value written in it, in the one of black and white that reads better on its shade; it is not written in a cell it has no room in.
• Scale bar. legend says where the scale of shades stands: the least and the most of the values are written at its ends.
• Names. xAxis is the names of the columns and yAxis of the rows: whether they are written (labels) and how (label). A name that has no room is left out by a rule.
• The cell pointed at. The cell under the pointer, or the one that is tapped, is ringed, and the tooltip writes its column, its row and its value.
• State and pressing. The cell that is pointed at is kept in ChartState, as a selection whose x is the datum's place in the list. onSelect gives the cell that is pressed: label is its column, name its row, value its value.
• Direction. In a language read from right to left the columns start from the right, and the rows' names are written at the right.
• Export. export puts a button over the chart: the chart is made, as it is on the screen and without the part that is pointed at or its tooltip, into a PNG, an SVG or a PDF file and handed to the app.
• Automation. Heatmap_<tagKey>; the cells are .Plot, a cell .Cell_<number>, the scale .Legend, the tooltip .Tooltip.

Examples

A week by the hour

A shop's visitors over a week, by the day and by the part of the day. A dark cell is a busy hour.

Move the pointer over a cell or tap it: the tooltip writes the visitors of that hour of that day.

PantrixHeatmap(
    data = weekVisits(),
    x = { it.hours },
    y = { it.day },
    value = { it.visits },
    description = "Visits by day and hour",
    tagKey = "plain"
)

internal fun weekVisits(): List<SlotVisits> {
    val days = listOf("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")
    val hours = listOf("09", "11", "13", "15", "17", "19")
    val visits = listOf(
        listOf(12, 18, 34, 22, 41, 30),
        listOf(10, 16, 31, 20, 38, 28),
        listOf(14, 21, 36, 25, 44, 33),
        listOf(11, 19, 35, 27, 47, 36),
        listOf(16, 24, 42, 31, 58, 52),
        listOf(28, 45, 61, 66, 72, 57),
        listOf(22, 39, 54, 60, 49, 26)
    )
    return days.flatMapIndexed { day, name -> hours.mapIndexed { slot, at -> SlotVisits(name, at, visits[day][slot]) } }
}

internal class SlotVisits(
    val day: String,
    val hours: String,
    val visits: Int
)

Five shades, with the values written

Exam scores, out of a hundred. The scale has five shades (steps): each twenty points are a shade. The values are written in the cells (labels), and the scale stands beside the chart. The cell of one who sat no exam is blank.

PantrixHeatmap(
    data = examScores(),
    x = { it.subject },
    y = { it.student },
    value = { it.score },
    scale = HeatmapScale(min = 0.0, max = 100.0, steps = 5),
    labels = ChartDataLabels(),
    legend = ChartLegend(position = ChartLegendPosition.End),
    description = "Students' scores by subject",
    tagKey = "steps"
)

internal fun examScores(): List<ExamScore> {
    val subjects = listOf("Maths", "Physics", "Chemistry", "History", "Language")
    val scores = mapOf(
        "Ada" to listOf(92, 85, 78, 64, 88),
        "Lin" to listOf(71, 58, null, 90, 95),
        "Can" to listOf(45, 62, 70, 81, 39),
        "Ece" to listOf(84, 97, 91, 55, 73)
    )
    return scores.flatMap { (student, row) ->
        subjects.mapIndexed { at, subject -> ExamScore(student, subject, row[at]) }
    }
}

internal class ExamScore(
    val student: String,
    val subject: String,
    val score: Int?
)

A scale of two colours

A scale of two colours, like a temperature: the fewest visits in the low colour (the warning colour's container), the most in color (the danger colour); the shades between are the two colours mixed in Oklab. The colours come from the theme, so the scale reads in a light theme and a dark one.

val colors = PantrixTheme.colors
PantrixHeatmap(
    data = weekVisits(),
    x = { it.hours },
    y = { it.day },
    value = { it.visits },
    scale = HeatmapScale(low = colors.warning.container, color = colors.danger.color),
    labels = ChartDataLabels(),
    description = "Visits by day and hour",
    tagKey = "two_colours"
)

internal fun weekVisits(): List<SlotVisits> {
    val days = listOf("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")
    val hours = listOf("09", "11", "13", "15", "17", "19")
    val visits = listOf(
        listOf(12, 18, 34, 22, 41, 30),
        listOf(10, 16, 31, 20, 38, 28),
        listOf(14, 21, 36, 25, 44, 33),
        listOf(11, 19, 35, 27, 47, 36),
        listOf(16, 24, 42, 31, 58, 52),
        listOf(28, 45, 61, 66, 72, 57),
        listOf(22, 39, 54, 60, 49, 26)
    )
    return days.flatMapIndexed { day, name -> hours.mapIndexed { slot, at -> SlotVisits(name, at, visits[day][slot]) } }
}

internal class SlotVisits(
    val day: String,
    val hours: String,
    val visits: Int
)

Pressing a cell

onSelect gives the cell that is pressed: press a cell, or go to one with the keyboard and press Enter, and the line under the card writes what was pressed. The scale has a colour of its own (HeatmapScale.color), and there is no scale bar (legend = null).

val report = LocalExampleEvents.current
PantrixHeatmap(
    data = weekVisits(),
    x = { it.hours },
    y = { it.day },
    value = { it.visits },
    scale = HeatmapScale(color = PantrixTheme.colors.success.color),
    legend = null,
    onSelect = { cell -> report("${cell.name}, ${cell.label}: ${cell.text}") },
    description = "Visits by day and hour",
    tagKey = "pressed"
)

internal fun weekVisits(): List<SlotVisits> {
    val days = listOf("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")
    val hours = listOf("09", "11", "13", "15", "17", "19")
    val visits = listOf(
        listOf(12, 18, 34, 22, 41, 30),
        listOf(10, 16, 31, 20, 38, 28),
        listOf(14, 21, 36, 25, 44, 33),
        listOf(11, 19, 35, 27, 47, 36),
        listOf(16, 24, 42, 31, 58, 52),
        listOf(28, 45, 61, 66, 72, 57),
        listOf(22, 39, 54, 60, 49, 26)
    )
    return days.flatMapIndexed { day, name -> hours.mapIndexed { slot, at -> SlotVisits(name, at, visits[day][slot]) } }
}

internal class SlotVisits(
    val day: String,
    val hours: String,
    val visits: Int
)

Export

export = ChartExport(...) puts an export button over the chart: press it and choose the kind (PNG, SVG or PDF). The chart makes the file and hands it to onExport; below, its name and size show, and a PNG's picture, and "Save the file" hands it over in the platform's way.

The file has the cells and the names at their sides; the scale of colours stands under the cells in the file, wherever it stands on the screen.

var file by remember { mutableStateOf<ChartExportFile?>(null) }
PantrixHeatmap(
    data = weekVisits(),
    x = { it.hours },
    y = { it.day },
    value = { it.visits },
    description = "Visits by day and hour",
    tagKey = "exported",
    export = ChartExport(fileName = "hours-of-the-week") { file = it }
)
ExportedFile(file, tagKey = "exported")

internal fun weekVisits(): List<SlotVisits> {
    val days = listOf("Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun")
    val hours = listOf("09", "11", "13", "15", "17", "19")
    val visits = listOf(
        listOf(12, 18, 34, 22, 41, 30),
        listOf(10, 16, 31, 20, 38, 28),
        listOf(14, 21, 36, 25, 44, 33),
        listOf(11, 19, 35, 27, 47, 36),
        listOf(16, 24, 42, 31, 58, 52),
        listOf(28, 45, 61, 66, 72, 57),
        listOf(22, 39, 54, 60, 49, 26)
    )
    return days.flatMapIndexed { day, name -> hours.mapIndexed { slot, at -> SlotVisits(name, at, visits[day][slot]) } }
}

internal class SlotVisits(
    val day: String,
    val hours: String,
    val visits: Int
)

API

data

A heatmap: a grid of cells, each in a shade that says how much its value is. It suits what has two names and a number: the hours of the days of a week, the months of several years, one list set against another. What is much and what is little is seen at a glance, where a table of the same numbers would have to be read.

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

• Keyboard. The chart is one stop for Tab: the arrows go from cell to cell, past the blank cells; Home and End go to the first and the last cell, Escape lets go, Enter and Space press the cell that is pointed at.
• Screen reader. The chart says its description, then each cell, row after row, with its column, its row and its value. A chart of more than two hundred cells is told by its description alone.