heatmap

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 to dataset columns, so a long-format table of a, b, r rows is the whole mark. A correlation matrix is what it exists for, and a confusion matrix, a payoff matrix and a co-occurrence table are the same picture. BOTH AXES MUST BE RULED IN STOPS — names, or format: discrete for numbers — because a cell is the box an axis rules off and a continuous axis rules off none; a continuous axis beside a heatmap is refused (canvas/heatmap-axis). auto gets there by itself: an axis carrying nothing but cells rules itself at their values, so a grid of five loads by four speeds needs no format: line at all. Each cell then fills the band at its stop. Not a surface, which samples an expression over the whole window and has no cells at all. A cell no row names is not drawn and the plot shows through; where two rows name the same cell, the last one wins.

heatmapNode
Only withxyplane
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.

A heatmap is a grid of cells, one value each. x and y say which cell and value says what it holds, three series paired by row — written out, or bound to dataset columns, so a table of a, b, r rows is the whole mark. A correlation matrix is what it is for.

Both axes must be ruled in stops: names, or discrete numbers. A cell is the box an axis rules off, and a continuous axis rules off none — it has a value everywhere, so there is nowhere for one cell to end and the next to begin, and writing x format: numbers beside a heatmap is refused for that reason. You rarely have to say anything: an axis carrying nothing but cells rules itself at their values, so a grid of five loads by four speeds needs no format: line at all. Each cell then fills the band at its stop.

colour takes the same hues and ramps a surface does, and range pins what the ends of the ramp mean — write range: [-1, 1] for correlations, so white falls at no correlation rather than at the middle of this particular sample. show-labels writes each value in its cell, and half: lower drops the mirrored triangle of a symmetric matrix.

The footer carries the key, and prices the cursor against it: moving over the grid slides a dot along the ramp to the value of the cell underneath, exactly as it does over a surface. A cell the data has no row for prices 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.
canvas.graph{
    heatmap(
        x: force, force, force, force, wear, wear, wear, wear, load, load, load, load, life, life, life, life
        y: force, wear, load, life, force, wear, load, life, force, wear, load, life, force, wear, load, life
        value: 1, 0.62, 0.17, -0.39, 0.62, 1, 0.31, -0.48, 0.17, 0.31, 1, 0.32, -0.39, -0.48, 0.32, 1
        colour: temperature
        range: [-1, 1]
        half: lower
        show-labels: true
    )
}

#Attributes

xAnimatable
Which cell, along the x axis: a name on an axis ruled in names, a number on a discrete one, written out or a column bound whole (#corr.a). Paired by row with y: and value:.
series
yAnimatable
Which cell, along the y axis — read exactly as x: is.
series
valueRequiredImplicitAnimatable
What each cell holds: the number its colour stands for.
series
Also written: valuesCan 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.
reference
colourAnimatable
multicolour (the default) runs the full spectrum, violet low to red high; temperature is the blue → white → red wash — pair it with a symmetric range: to pin white at zero; any ordinary hue shades its own intensity ramp instead. Both ramps are fixed colours, identical in light and dark mode.
blueredorangeyellowtealgreenpinkpurplegreyhex(…)rgb(…)multicolourtemperature
Also written: color
Defaultmulticolour
invertAnimatable
Flip the ramp, putting deep colour at low values rather than high.
boolean
Defaultfalse
rangeAnimatable
The value window the ramp spans, e.g. [-1, 1] for correlations — so white falls at no correlation rather than at the middle of this sample. Absent, it spans the values given, which re-normalises as a period slides.
parametised-interval
halfAnimatable
Which side of the leading diagonal to keep, the diagonal itself 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.
fulllowerupper
Defaultfull
gapAnimatable
How much of each cell to leave unpainted at its edge, as a share of the cell; cells touch by default.
number
Default0
show-labelsAnimatable
Write each cell's value inside it. A correlation matrix is hard to read without them.
boolean
Also written: labels
Defaultfalse
label
Words naming the mark, placed above the grid.
rich-text
opacityAnimatable
How heavy the cells sit over the plot.
number
Default1
hiddenAnimatable
Declared but not drawn — animatable, so hidden: true !cue.to{false}(at: 2) is its reveal.
boolean
Defaultfalse
lock
A reader may not edit it on an editable graph.
boolean
Also written: locked
Defaultfalse
text-sizeAnimatable
The size of the values written in the cells.
number
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).
parametised-number

#Allowed in

canvas.graph { }cue { }cue.draw { }cue.trace { }cue.highlight { }cue.spotlight { }

#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.
canvas.graph{
    heatmap(x: #corr.a; y: #corr.b; value: #corr.r; colour: temperature; range: [-1, 1])
}
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.
canvas.graph{
    heatmap(x: a, a, b, b; y: a, b, a, b; value: 1, 0.3, 0.3, 1; show-labels: true)
}

Last updated