histogram

A sample drawn as bars over the values it takes. Written two ways: the READINGS, which the mark bins itself — histogram(x: #sample.height; bins: 12), where bins is how many — or the counts of an already-tallied sample in values, with bins the edges they fall between (one more number than there are counts). Which coordinate carries the readings is the axis the bins land on, and so which way the bars grow; orientation says the same thing for the counts form. Bars meet at their shared edges, take a colour each, and can print their value.

histogramNode
Only withxypolarplane
A teal histogram of four bins from 0 to 40, tallest in the second.A teal histogram of four bins from 0 to 40, tallest in the second.

A histogram is a rectangle mark and a different thing from a bar: its bins are edges, so its width is data, and it draws on a numeric axis. It takes the readings themselves — histogram(x: #sample.height; bins: 12) — and bins them, bins saying how many; parametised (bins: k) the reader re-bins the sample for themselves, which is the quickest way to see how much of the shape was the choice of grid.

The coordinate the readings are written on is the axis the bins land on and so which way the bars grow (x up from the x axis, y out from the y axis, theta a wind rose on the polar plane, its bins edges on theta). A sample already tallied is written the other way instead — values the counts and bins the edges they fall between, one more number than there are counts, with orientation for the direction no coordinate is there to say.

#Attributes

On any plane
valuesImplicitAnimatable
The counts, one per bin — a sample the author has already tallied. bins is then the edges they fall between, one more number than there are counts. Never beside readings: a histogram is given the counts or works them out, not both. e.g. 5, 12, 8
number-list
Can be written as shorthand: histogram:value
binsAnimatable
How many bins, or where their edges fall. A single number is a count — bins: 12, or parametised, bins: k, so a slider re-bins the sample — and it needs readings to bin. Two or more numbers are the edges themselves, in order, one more than there are bars, and may be unequal (0, 10, 20, 30). Computed bins span the sample exactly, smallest reading to largest; with no bins at all the count is the square root of the sample size.
histogram-bins
coloursAnimatable
Colour for each bar, cycled in order — one colour colours the lot. If fewer colours than bars are given, the list starts again from the first.
colour-list
Also written: colors, colour, color
Defaultblue
orientation
Bar direction for the counts form. 'vertical' grows upward from the x-axis; 'horizontal' grows rightward from the y-axis. Readings name their own axis — x or y — and that is the direction, so this says nothing beside them.
verticalhorizontal
Defaultvertical
show-labelsAnimatable
When true, renders the numeric value above each bar (or to its right for horizontal orientation).
boolean
Defaultfalse
label
Text drawn beside the element — rich text, so $maths$ and inline formatting render. Fades and draws with the element.
rich-text
hiddenAnimatable
Declared but not drawn. Animatable — hidden: true !cue.to{false}(at: 2) reveals it — and unlike a cue, a hidden element still frames the plot, so the axes do not jump when it appears.
boolean
Defaultfalse
lock
Keeps the reader from editing this element on an editable: graph. Nothing at all on a graph that is not editable.
boolean
Also written: locked
Defaultfalse
text-sizeAnimatable
Text size.
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). Written z: before the argand plane took that letter for its coordinate.
parametised-number
Only withxyplane
xAnimatable
The readings on the x axis — the sample itself, taken as a scatter takes one: numbers, or a dataset column (#sample.height). The mark bins them; bins says how many. Written on x, the grid lies along x and the bars stand up from it.
series
yAnimatable
The same readings measured up the y axis instead: the grid lies up y and the bars run out rightward from it. The readings' own coordinate is the orientation, so orientation is not written beside it.
series
Only withpolarplane
thetaAnimatable
The readings as angles, in radians, on the polar plane: the turn is cut into bins sectors and each count reaches out from the centre — a rose of the sample rather than of counts written by hand.
series

#Allowed in

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

#Examples

A teal histogram of 38 heights in twelve bins.A teal histogram of 38 heights in twelve bins.
canvas.graph{
    histogram(
        x: #sample.height
        bins: 12
        colour: teal
    )
}
A histogram of 38 heights in eight bins, with a bins slider beneath the plot.A histogram of 38 heights in eight bins, with a bins slider beneath the plot.
canvas.graph{
    slider:k(name: bins; range: [2, 20]; step: 1; default: 8)
    histogram(
        x: #sample.height
        bins: k
    )
}
A purple horizontal histogram of three bins from 0 to 15, the middle bar longest.A purple horizontal histogram of three bins from 0 to 15, the middle bar longest.
canvas.graph{
    histogram(
        bins: 0, 5, 10, 15
        values: 3, 7, 2
        orientation: horizontal
        colour: purple
    )
}

Last updated