histogram

A sample counted into bins and drawn as bars, each as tall as its count.

Only withxypolarxyzplane
On this page
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.

#Binning readings

histogram(x: #sample.height; bins: 12) takes the sample and counts it into bins; each bar is as tall as its count. The coordinate the readings are written on is the axis the bins lie along: x stands the bars up from the x axis, y runs them out from the y axis, and theta, on the polar plane, cuts the whole turn into sectors from where the theta domain starts — empty sectors included. One coordinate only.

bins as one number is how many equal bins, spanning the sample exactly, smallest reading to largest. Left out, it is the square root of the sample size, rounded; either way at most 60. Two or more numbers are the edges themselves, in order and possibly unequal. A bin holds its lower edge and not its upper, except the last, which holds both, so the largest reading is counted. A count given as a parameter re-bins the sample as the reader moves it:

graph{
    slider:k(name: bins; range: [2, 20]; step: 1; default: 8)
    histogram(x: #sample.height; bins: k)
}
Warning
Given as edges, bins leaves out the readings outside the outer edges: they are not counted.

#Counts already tallied

A sample tallied already is written as its counts in counts, written out or a column bound whole, with bins the edges they fall between — one more number than there are counts. With no readings to name an axis, orientation gives the direction: vertical up from the x axis, or horizontal out from the y axis. A list in colour is cycled bin by bin in either form; in a map, value is a bin's count and x (or y) the middle of the bin.

graph{
    histogram(bins: 0, 18, 30, 50, 65, 90; counts: 12, 25, 31, 18, 9; colour: grey, grey, orange, grey, grey)
}

A histogram is given its readings or its counts, never both; counts without edges, or with a single number for bins, are refused with the same code:

histogram(x: #sample.height; counts: 3, 7, 2)

[canvas/histogram-form]'histogram' gives its bars two ways — the readings in 'x:' and the counts in 'values:'; give one. Readings are binned for you ('bins: 12' says how many); 'values:' is for a sample already tallied

#Back to back

mirror draws the bins on the far side of the baseline, as a bar's does, and an auto axis the counts reach along writes its numbers without their signs. Two histograms over the same bins, one mirrored, stand back to back: a population pyramid is the ages of one population counted in bands, men on one side and women on the other, each written as the positive counts a census table gives. An open top band, 85 and over, is drawn closed at an age the author chooses.

A population pyramid on an age axis from 0 to 90 in five-year bins: a blue histogram of men stepping out to the left and a red histogram of women to the right, widest in the thirties and early fifties and narrowing towards the top, where the women outnumber the men.A population pyramid on an age axis from 0 to 90 in five-year bins: a blue histogram of men stepping out to the left and a red histogram of women to the right, widest in the thirties and early fifties and narrowing towards the top, where the women outnumber the men.
graph{
    @data#pop{
        men  | women
        1.75 | 1.67
        1.85 | 1.76
        1.90 | 1.80
        1.88 | 1.79
        2.08 | 1.99
        2.20 | 2.12
        2.27 | 2.22
        2.23 | 2.18
        2.10 | 2.09
        2.12 | 2.14
        2.24 | 2.28
        2.16 | 2.22
        1.92 | 2.01
        1.68 | 1.79
        1.46 | 1.62
        1.10 | 1.30
        0.68 | 0.92
        0.48 | 0.86
    }

    histogram(
        counts: #pop.men
        bins: 0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90
        orientation: horizontal
        mirror: true
        colour: blue
        label: Men
    )
    histogram(
        counts: #pop.women
        bins: 0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90
        orientation: horizontal
        colour: red
        label: Women
    )
}(
    x axis label: population (millions)
    y axis label: age
)

#Pairs in space

On graph:xyz a histogram counts pairs: x and y are both required, paired by position, and the floor is cut into a grid of cells, bins along each axis or the edges on both. Each cell holding any readings carries a column as tall as its count. counts, orientation: horizontal and mirror are refused there.


#Attributes

On any plane
countsImplicitAnimatable
The counts, one per bin, of a sample already tallied; bins: is then the edges they fall between, one more number than there are counts. Refused beside readings (canvas/histogram-form).
Can be written as shorthand: histogram:value
binsAnimatable
How many bins, or where their edges fall. One number is a count of equal bins spanning the sample exactly, smallest reading to largest — bins: 12, or a parameter, bins: k, so a slider re-bins the sample — and needs readings to bin. Left out, the count is the square root of the sample size, rounded; either way at most 60. Two or more numbers are the edges, in order, one more than there are bars, and may be unequal (0, 10, 20, 30); readings outside them are not counted. Each bin holds its lower edge and not its upper, except the last, which holds both.
colour
The bars' colour: one colour, a list cycled bar by bar, or an expression on #self.value, each bin's count. Intervals as keys band the bars, #self.value -> (..<5: grey; otherwise: teal); an interval then a ramp's name is a ramp, #self.value -> 0..20 -> blue.
colour-style
Also written: color
Defaultblue
style
How each bar is filled: solid, hatched, dotted or outlined. One style, a list cycled bar by bar, or an expression on #self.value, as colour: takes.
fill-style-style
Defaultsolid
orientation
Which way the bars of the counts form grow: vertical up from the x axis, horizontal out from the y axis. Readings name their own axis, so this is not read beside them; in space only vertical is accepted.
verticalhorizontal
Defaultvertical
mirror
Defaultfalse
show-labelsAnimatable
Write each bar's count at its end.
Defaultfalse
label
Text drawn beside the element — rich text, so $maths$ and inline formatting render. Fades and draws with the element.
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.
Defaultfalse
lock
Keeps the reader from editing this element on an editable: graph. Nothing at all on a graph that is not editable.
Also written: locked
Defaultfalse
text-sizeAnimatable
Text size.
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.
group
The groups this histogram 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.
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.
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.
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.
Only withxyzplane
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.
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.

#Derived attributes

Computed while the element renders — read one with #id.name in attribute position or {{#id.name}} in prose, never set.

On any plane
valueDerived
Each bar's count, one per bar, which colour: follows as #self.value: colour: #self.value -> (..<5: grey; 5..: blue).
countDerived
The number of readings binned — in space, of pairs over the floor's grid — every one counted whether or not it falls inside written edges — or the sum of the counts where they are written out.
Only withxyplane
meanDerived
The mean of the readings themselves, not of the bins, in the axis's units, holding still while bins: changes; a dash for counts written out, a rose (theta:), or no readings.
medianDerived
The middle of the ordered readings themselves, not of the bins, in the axis's units; a dash for counts written out, a rose (theta:), or no readings.
modeDerived
The reading seen most often; none when no reading repeats, or two are seen equally often.
sdDerived
The sample standard deviation (divided by n − 1) of the readings themselves, not of the bins, in the axis's units; a dash for counts written out, a rose (theta:), or fewer than two readings.
minDerived
The smallest reading.
maxDerived
The largest reading.
rangeDerived
The largest reading less the smallest.
q1Derived
The lower quartile: the median of the lower half of the ordered readings.
q2Derived
The median under its quartile name: the middle reading once the readings are ordered.
q3Derived
The upper quartile: the median of the upper half of the ordered readings.
iqrDerived
The interquartile range, q3 − q1.

#Allowed in

#Examples

A teal histogram of 38 heights in twelve bins.A teal histogram of 38 heights in twelve bins.
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.
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.
graph{
    histogram(
        bins: 0, 5, 10, 15
        counts: 3, 7, 2
        orientation: horizontal
        colour: purple
    )
}
A grey histogram of six bins from 0 to 30 with the bin from 10 to 15 picked out in orange.A grey histogram of six bins from 0 to 30 with the bin from 10 to 15 picked out in orange.
graph{
    histogram(
        bins: 0, 5, 10, 15, 20, 25, 30
        counts: 2, 6, 11, 8, 4, 1
        colour: grey, grey, orange, grey, grey, grey
    )
}
A histogram in space: sixty adults binned by height and by mass over a grid on the floor, the tallest columns near 170 cm and 70 kg.A histogram in space: sixty adults binned by height and by mass over a grid on the floor, the tallest columns near 170 cm and 70 kg.
graph:xyz{
    histogram(
        x: #bodies.height
        y: #bodies.mass
        bins: 6
    )
}(
    x axis label: height (cm)
    y axis label: mass (kg)
    z axis label: count
    view: (-50, 25)
)

Last updated