histogram
A sample counted into bins and drawn as bars, each as tall as its count.
On this page


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


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
countsbins: is then the edges they fall between, one more number than there are counts. Refused beside readings (canvas/histogram-form).histogram:valuebinsbins: 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#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-stylecolorbluestylesolid, hatched, dotted or outlined. One style, a list cycled bar by bar, or an expression on #self.value, as colour: takes.fill-style-stylesolidorientationvertical 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.verticalhorizontalverticalmirrorfalseshow-labelsfalselabel$maths$ and inline formatting render. Fades and draws with the element.hiddenhidden: 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.falselockeditable: graph. Nothing at all on a graph that is not editable.lockedfalsetext-size20layerz: before the argand plane took that letter for its coordinate.groupgroup: 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.xyplanexscatter 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.yorientation is not written beside it.polarplanethetabins sectors and each count reaches out from the centre — a rose of the sample rather than of counts written by hand.xyzplanexscatter 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.yorientation 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.
valuecolour: follows as #self.value: colour: #self.value -> (..<5: grey; 5..: blue).countxyplanemeanbins: changes; a dash for counts written out, a rose (theta:), or no readings.mediantheta:), or no readings.modesdtheta:), or fewer than two readings.minmaxrangeq1q2q3iqr#Allowed in
#Examples


graph{
histogram(
x: #sample.height
bins: 12
colour: teal
)
}

graph{
slider:k(name: bins; range: [2, 20]; step: 1; default: 8)
histogram(
x: #sample.height
bins: k
)
}

graph{
histogram(
bins: 0, 5, 10, 15
counts: 3, 7, 2
orientation: horizontal
colour: purple
)
}

graph{
histogram(
bins: 0, 5, 10, 15, 20, 25, 30
counts: 2, 6, 11, 8, 4, 1
colour: grey, grey, orange, grey, grey, grey
)
}

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)
)