heatmap

A grid of cells, one value each, painted from a ramp.

heatmapNode
Only withxyplane
On this page
A three-by-three grid of cells on the blue-to-red temperature ramp, deep red down the diagonal and pale blue at two corners.A three-by-three grid of cells on the blue-to-red temperature ramp, deep red down the diagonal and pale blue at two corners.

#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.

A four-variable correlation matrix drawn as cells on the blue-to-red temperature ramp, its lower triangle only, each cell holding its coefficient.A four-variable correlation matrix drawn as cells on the blue-to-red temperature ramp, its lower triangle only, each cell holding its coefficient.
@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

xAnimatable
Which cell along the x axis: a name, or a number on a discrete axis, written out or a column bound whole (#corr.a). Paired by row with y: and value:.
yAnimatable
Which cell, along the y axis — read exactly as x: is.
valueRequiredImplicitAnimatable
What each cell holds: the number its colour stands for.
Can be written as shorthand: heatmap:value
slice
The column this mark is SLICED by — long-format data, one row per thing per slice, showing the one the scene's parameter over that column holds. A column with a number line interpolates, so a reader stopped between two values sees half way; a column of names selects the rows carrying the name they picked.
colour
multicolour (the default) runs the full spectrum, violet low to red high; temperature is the blue → white → red wash; any ordinary hue shades its own intensity ramp instead; a list is the ramp's stops, low end first. Both ramps are fixed colours, identical in light and dark mode. The ramp spans the values given, which re-normalises as a period slides; applying the value: 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-style
Also written: color
Defaultmulticolour
invertAnimatable
Flip the ramp, putting deep colour at low values rather than high.
Defaultfalse
halfAnimatable
Which side of the leading diagonal to keep, the diagonal staying in both — for a symmetric matrix the other half is the same numbers again. Refused unless both axes are ruled alike: the same names in the same order, or both in numbers (canvas/heatmap-half).
fulllowerupper
Defaultfull
gapAnimatable
How much of each cell to leave unpainted at its edge, as a share of the cell.
Default0
show-labelsAnimatable
Write each cell's value inside it. A correlation matrix is hard to read without them.
Also written: labels
Defaultfalse
label
Words naming the mark, placed above the grid.
opacityAnimatable
How heavy the cells sit over the plot.
Default1
hiddenAnimatable
Declared but not drawn — animatable, so hidden: true !cue.to{false}(at: 2) is its reveal.
Defaultfalse
lock
A reader may not edit it on an editable graph.
Also written: locked
Defaultfalse
text-sizeAnimatable
The size of the values written in the cells.
Default20
layerAnimatable
Paint order among the marks: a higher layer is drawn later, on top; equal or omitted, the marks stack in document order (later on top).
group
The groups this heatmap belongs to, comma-separated: group: 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.

minDerived
The smallest value among the cells drawn — after half: and a repeated cell's last row — at the slice the reader stands at; a dash with no cells.
maxDerived
The largest value among the cells drawn — after half: and a repeated cell's last row — at the slice the reader stands at; a dash with no cells.
meanDerived
The mean of the values in the cells drawn, each cell once, at the slice the reader stands at; a dash with no cells.

#Allowed in

#Examples

A four-by-four correlation matrix on the blue-to-red temperature ramp from −1 to 1, deep red down the diagonal.A four-by-four correlation matrix on the blue-to-red temperature ramp from −1 to 1, deep red down the diagonal.
graph{
    heatmap(x: #corr.a; y: #corr.b; value: #corr.r; colour: #corr.r -> -1..1 -> temperature)
}
A two-by-two grid of cells for a and b, each holding its value: 1 on the diagonal and 0.3 off it.A two-by-two grid of cells for a and b, each holding its value: 1 on the diagonal and 0.3 off it.
graph{
    heatmap(x: a, a, b, b; y: a, b, a, b; value: 1, 0.3, 0.3, 1; show-labels)
}

Last updated