heatmap
A grid of cells, one value each, painted from a ramp.
heatmapxyplaneOn this page


#Cells
A heatmap is a grid of cells, one value each. x and y say which cell and value what it holds — three series paired by row, written out or bound, so a long-format table of a, b, r rows is the whole mark: heatmap(x: #corr.a; y: #corr.b; value: #corr.r). A cell no row names is not drawn and the plot shows through; where two rows name one cell, the last wins. slice reads long-format data over periods, as a bar's does.
#Axes ruled in stops
Both axes are ruled in stops: names, or numbers under format: discrete, which stands each distinct value at its own evenly spaced stop. A cell fills the band at its stop. An axis carrying nothing but cells rules itself discrete under auto, so a grid of loads by speeds needs no format: line. An axis that other marks share, or one written continuous, is refused:
graph{
heatmap(x: 800, 1200, 800, 1200; y: 10, 10, 20, 20; value: 0.8, 1.1, 1.4, 2.0)
scatter(x: 900; y: 15)
}[canvas/heatmap-axis]'heatmap' lays its cells out on stops, and the x axis is ruled in numbers, continuously — a continuous axis rules off no cells. Write 'x format: discrete' to rule it at the values the cells give, or name the stops ('x format: North, South, East')
half: lower or upper keeps one side of the leading diagonal, the diagonal in both, which drops the mirrored half of a symmetric matrix. It is refused unless both axes are ruled alike — the same names in the same order, or both in numbers (canvas/heatmap-half).
#Colour and the key
colour is multicolour (violet low to red high, the default), temperature (blue through white to red), a hue, shading its own ramp, or a list of stops, low end first; invert flips it. The ramp spans the values present, and re-spans as a slice changes. The value column applied to an interval and a ramp fixes the values at its two ends: colour: #corr.r -> -1..1 -> temperature on a correlation matrix puts white at no correlation. Applied to bands, #corr.r -> (..<0: blue; 0..: red), it paints each cell flat. show-labels writes each value in its cell, and gap insets every cell by a share of its size.
The footer carries the ramp as a key. Over the grid a dot slides along it to the value of the cell under the cursor, with the number beside it unless the cells show their own; over a place no cell covers, the key reads nothing.


@data#corr{
a | b | r
force | force | 1
force | wear | 0.62
force | load | 0.17
force | life | -0.39
wear | force | 0.62
wear | wear | 1
wear | load | 0.31
wear | life | -0.48
load | force | 0.17
load | wear | 0.31
load | load | 1
load | life | 0.32
life | force | -0.39
life | wear | -0.48
life | load | 0.32
life | life | 1
}
graph{
heatmap(
x: #corr.a
y: #corr.b
value: #corr.r
colour: #corr.r -> -1..1 -> temperature
half: lower
show-labels
)
}#Attributes
xdiscrete axis, written out or a column bound whole (#corr.a). Paired by row with y: and value:.yx: is.valueheatmap:valueslicecolourvalue: column pins the window, colour: #m.r -> -1..1 -> temperature putting white at no correlation rather than at the middle of this sample. A map paints each cell flat: bands, colour: #m.r -> (..<0: blue; 0..: red), or a column's categories.value-colour-stylecolormulticolourinvertfalsehalfcanvas/heatmap-half).fulllowerupperfullgap0show-labelslabelsfalselabelopacity1hiddenhidden: true !cue.to{false}(at: 2) is its reveal.falselocklockedfalsetext-size20layergroupgroup: Treated, Projected. It is drawn in the colour of the first group that has one, over its own colour:, and the footer's key names every group. A stroke the graph's key: gives a group does not change it.#Derived attributes
Computed while the element renders — read one with #id.name in attribute position or {{#id.name}} in prose, never set.
minhalf: and a repeated cell's last row — at the slice the reader stands at; a dash with no cells.maxhalf: and a repeated cell's last row — at the slice the reader stands at; a dash with no cells.mean#Allowed in
#Examples


graph{
heatmap(x: #corr.a; y: #corr.b; value: #corr.r; colour: #corr.r -> -1..1 -> temperature)
}

graph{
heatmap(x: a, a, b, b; y: a, b, a, b; value: 1, 0.3, 0.3, 1; show-labels)
}