histogram

histogramNode

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.

Only withxypolarplane

#Attributes

On any plane

valuesImplicitAnimatable
number-list
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, 8Can be written as shorthand: histogram:value
binsAnimatable
histogram-bins
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.
coloursAnimatable
colour-list
Also written: colors, colour, colorColour 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.
Defaultblue
orientation
verticalhorizontal
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.
Defaultvertical
show-labelsAnimatable
boolean
When true, renders the numeric value above each bar (or to its right for horizontal orientation).
Defaultfalse
label
rich-text
Text drawn beside the element — rich text, so $maths$ and inline formatting render. Fades and draws with the element.
hiddenAnimatable
boolean
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.
Defaultfalse
lock
boolean
Also written: lockedKeeps the reader from editing this element on an editable: graph. Nothing at all on a graph that is not editable.
Defaultfalse
text-sizeAnimatable
number
Text size.
Default20
layerAnimatable
parametised-number
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.
Only withxyplane
xAnimatable
series
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.
yAnimatable
series
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.
Only withpolarplane
thetaAnimatable
series
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.

#Allowed in

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

#Examples

histogram(
    x: #sample.height
    bins: 12
    colour: teal
)
histogram(
    x: #sample.height
    bins: k
)
histogram(
    y: 2.1, 2.4, 3.8, 4.0, 4.1, 5.6
    bins: 4
)
histogram(
    bins: 0, 10, 20, 30, 40
    values: 5, 12, 8, 3
    colour: teal
)
histogram(
    bins: 0, 5, 10, 15
    values: 3, 7, 2
    orientation: horizontal
    colour: purple
)