boxplot

A sample drawn as its five-number summary: a box across the quartiles, the median ruled across it, and whiskers.

boxplotNode
Only withxxyargandplane
A teal box plot above a number line with its readings as grey markers swarmed through it, one reading far out to the right.A teal box plot above a number line with its readings as grey markers swarmed through it, one reading far out to the right.

#What the box computes

A box takes the readings and works the summary out. The quartiles are Tukey's hinges: the median splits the ordered readings in two, itself in neither half when the count is odd, and each quartile is the median of its half. The box spans the quartiles with the median ruled across it. A row that is not a number drops.

whiskers: fences, the default, stops each whisker at the furthest reading within one and a half interquartile ranges of its quartile and draws every reading beyond as its own dot. whiskers: extremes runs them to the smallest and largest readings and draws no dots; so does a sample whose quartiles coincide. !outliers keeps the fences and leaves the dots off. It is animatable and the frame holds the dots either way, so they can fade in on a step without the axis moving.

A box holding one sample publishes median, q1, q3, iqr, min and max. min and max are the sample's extremes whether or not a whisker reaches them.

#One sample

One coordinate is one sample, and the box lies along the axis it is written on. On the number line it takes a lane above the line. On a plane, on: says where it stands on the other axis — a number, a date, or a name, which joins that axis's names:

boxplot(y: #births.mass)

[canvas/stand-on]'boxplot' summarises y and needs 'on:' to say where it stands on x — a number there ('on: 2'), or a name ('on: Control'), which rules the axis in the names its boxes stand at

on: is refused on the number line, and the axis the readings are written on must be numeric (canvas/boxplot-axes). A box and a scatter of the same readings at one place share one slot: the summary lands over the readings, the markers swarm, and the box leaves its outlier dots to the scatter, whose markers they already are.

Tip
Marks paint in source order, so the box is written first, or its wash tints every marker inside it.
scene{
    The middle half of the sample spans {{#control.iqr}} g.
}[
    graph:x{
        boxplot#control(x: #births.mass; colour: teal; label: control)
        scatter(x: #births.mass; colour: grey)
    }(
        x axis label: mass (g)
    )
]

#A box per group

Both coordinates, one of them a column of names, draw a box at every name, each over the readings in that name's rows — boxplot(x: #trial.arm; y: #trial.mass), the two columns grouped data arrives in. on: is refused, since the names say where each box stands.

Warning
A grouped box publishes its numbers only while it holds one group; with several it publishes none, because each name has its own median and a derived attribute has one value. A number to cite is drawn as its own box, on: its name.

#A box of paired readings

Both coordinates numeric are one bivariate sample, paired row by row. The box is the rectangle of the x quartiles by the y quartiles with both medians crossed inside it, a whisker from each edge to that axis's fence, and every reading outside either fence as its own dot — drawn over a scatter of the same columns, it lands on the markers it summarises. It publishes each axis's numbers under the axis's name — x-median, y-q3 — and no plain median. on: and band are refused. On the argand plane the pair is re and im, or one complex z, publishing re-median and the rest.

scene{
    Half the trees are taller than {{#cloud.x-median}} m.
}[
    graph{
        boxplot#cloud(x: #trees.height; y: #trees.mass; colour: teal)
        scatter(x: #trees.height; y: #trees.mass; colour: grey)
    }
]

#Attributes

On any plane
whiskersAnimatable
How far the whiskers reach. fences stops each at the furthest reading within one and a half interquartile ranges of its quartile and draws every reading beyond as its own dot; extremes runs them to the smallest and largest readings and draws no dots. A sample whose quartiles coincide is drawn to its extremes either way.
fencesextremes
Defaultfences
outliersAnimatable
Draw the readings past the fences. The whiskers stop where they stop either way, so a box with its outliers left off claims a reach the sample does not have and says nothing about the readings it dropped. !outliers takes them off anyway — for a scene about the middle of a distribution rather than its tails, and for one that puts them back on a step, since it is animatable (outliers: false !cue.to{true}(at: 2)). The frame still holds them, so fading them in does not move the axis. Nothing under whiskers: extremes, which has no reading outside its whiskers. Not drawn where the box shares its slot with a scatter of the same readings: every reading past the fences is one of those markers already.
boolean
Defaulttrue
colour
The boxes' colour: one colour, or a list box by box in the order the boxes stand — colour: grey, teal. Grouped by a column of names, it can also be applied to that column, so each box takes its own name's colour whatever order the boxes stand in: colour: #polls.party -> (DEM: blue; REP: red; otherwise: grey).
colour-style
Also written: color
Defaultblue
style
How each box is filled: solid, hatched, dotted or outlined. One style, or a list box by box.
fill-style-style
Defaultsolid
bandAnimatable
The share of its room that the box is thick — its lane on the number line, its slot of the band on a plane, where the band is one unit on an axis of names and the closest two places stand on a continuous one. The same room a scatter's band: is a share of, so a box and its markers are measured against one thing. The whisker caps are half of it, so one number sets the weight of the whole mark. Nothing to a box of a pair of samples, whose thickness is the spread of the second sample.
parametised-number
Default0.5
opacityAnimatable
Opacity.
number
Default1
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. It holds its slot the same way, drawn yet or not, so a box arriving on a step lands beside the marks already there rather than moving them.
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
group
The groups this box 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.
string
Only withxplane
xImplicitAnimatable
The readings — numbers written out, or a dataset column bound whole (#trial.mass). The sample itself, not a summary of it: a summary written by hand cannot be checked against the sample it claims to summarise. A row that is not a number drops.
series
Can be written as shorthand: boxplot:value
Only withxyplane
xImplicitAnimatable
The readings — numbers written out, or a dataset column bound whole (#trial.mass). The sample itself, not a summary of it: a summary written by hand cannot be checked against the sample it claims to summarise. A row that is not a number drops.
series
Can be written as shorthand: boxplot:value
yAnimatable
The readings when the sample is read up the y axis, written out or bound whole (#trial.mass). One coordinate is one sample. x: and y: together, with one of the two axes ruled in names, are a sample grouped by those names — a box at every name over that name's rows; both numeric, they are the paired readings of one bivariate sample, row by row, and a row missing either half drops whole.
series
onAnimatable
Where a one-sample box stands on the axis it does not summarise — a number, a name, or a date, as axis.label takes. Required on a plane for a box written with one coordinate, since the second axis is an axis and a box laid across it by lane would be asserting a coordinate its sample does not have. A name joins the axis's names, so boxes written on: control and on: treated rule the axis in those names with no x format: line, and a scatter with the same on: stands in the same place. Refused on the number line, whose boxes take a lane each; on a grouped box, whose names column already says where each box stands; and on a box of a pair of samples, which stands where its readings put it.
axis-value
Only withargandplane
reAnimatable
The readings on the real axis. One of re: and im: alone is one sample; the pair is one bivariate sample, which z: writes as a single list.
series
imAnimatable
The readings on the imaginary axis. One of re: and im: alone is one sample; the pair is one bivariate sample, which z: writes as a single list.
series
zAnimatable
A bivariate sample as one list of complex readings, summarised on each axis in turn — re: and im: written apart are the same box. A complex column binds here, there being no way to split one into two real ones.
complex-series
onAnimatable
Where a one-sample box stands on the axis it does not summarise — a number, a name, or a date, as axis.label takes. Required on a plane for a box written with one coordinate, since the second axis is an axis and a box laid across it by lane would be asserting a coordinate its sample does not have. A name joins the axis's names, so boxes written on: control and on: treated rule the axis in those names with no x format: line, and a scatter with the same on: stands in the same place. Refused on the number line, whose boxes take a lane each; on a grouped box, whose names column already says where each box stands; and on a box of a pair of samples, which stands where its readings put it.
axis-value

#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
medianDerived
The middle reading — the rule across the box. Published by a box holding one sample; a box grouped over several names publishes none.
q1Derived
The lower quartile: the median of the lower half of the ordered readings. Published by a box holding one sample; a box grouped over several names publishes none.
q3Derived
The upper quartile: the median of the upper half. Published by a box holding one sample; a box grouped over several names publishes none.
iqrDerived
The interquartile range, q3 − q1 — the width of the box. Published by a box holding one sample; a box grouped over several names publishes none.
minDerived
The smallest reading in the sample, whether or not a whisker reaches it. Published by a box holding one sample; a box grouped over several names publishes none.
maxDerived
The largest reading in the sample, whether or not a whisker reaches it. Published by a box holding one sample; a box grouped over several names publishes none.
meanDerived
The mean of the readings, which the box does not draw, in the axis's units; published by a box holding one sample, and a box grouped over several names publishes none.
countDerived
The number of readings the box summarises; published by a box holding one sample, and a box grouped over several names publishes none.
Only withxyplane
x-medianDerived
The middle reading — the rule across the box. Of the readings on the x axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain median, which a sample of pairs does not have.
x-q1Derived
The lower quartile: the median of the lower half of the ordered readings. Of the readings on the x axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain q1, which a sample of pairs does not have.
x-q3Derived
The upper quartile: the median of the upper half. Of the readings on the x axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain q3, which a sample of pairs does not have.
x-iqrDerived
The interquartile range, q3 − q1 — the width of the box. Of the readings on the x axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain iqr, which a sample of pairs does not have.
x-minDerived
The smallest reading in the sample, whether or not a whisker reaches it. Of the readings on the x axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain min, which a sample of pairs does not have.
x-maxDerived
The largest reading in the sample, whether or not a whisker reaches it. Of the readings on the x axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain max, which a sample of pairs does not have.
y-medianDerived
The middle reading — the rule across the box. Of the readings on the y axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain median, which a sample of pairs does not have.
y-q1Derived
The lower quartile: the median of the lower half of the ordered readings. Of the readings on the y axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain q1, which a sample of pairs does not have.
y-q3Derived
The upper quartile: the median of the upper half. Of the readings on the y axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain q3, which a sample of pairs does not have.
y-iqrDerived
The interquartile range, q3 − q1 — the width of the box. Of the readings on the y axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain iqr, which a sample of pairs does not have.
y-minDerived
The smallest reading in the sample, whether or not a whisker reaches it. Of the readings on the y axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain min, which a sample of pairs does not have.
y-maxDerived
The largest reading in the sample, whether or not a whisker reaches it. Of the readings on the y axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain max, which a sample of pairs does not have.
x-meanDerived
The mean of the readings on the x axis, in its units, published by a box of a pair of samples under that axis's name in place of a plain mean.
x-countDerived
The number of pairs a box of a pair of samples summarises, under the x axis's name in place of a plain count.
y-meanDerived
The mean of the readings on the y axis, in its units, published by a box of a pair of samples under that axis's name in place of a plain mean.
y-countDerived
The number of pairs a box of a pair of samples summarises, under the y axis's name in place of a plain count.
Only withargandplane
re-medianDerived
The middle reading — the rule across the box. Of the readings on the real axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain median, which a sample of pairs does not have.
re-q1Derived
The lower quartile: the median of the lower half of the ordered readings. Of the readings on the real axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain q1, which a sample of pairs does not have.
re-q3Derived
The upper quartile: the median of the upper half. Of the readings on the real axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain q3, which a sample of pairs does not have.
re-iqrDerived
The interquartile range, q3 − q1 — the width of the box. Of the readings on the real axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain iqr, which a sample of pairs does not have.
re-minDerived
The smallest reading in the sample, whether or not a whisker reaches it. Of the readings on the real axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain min, which a sample of pairs does not have.
re-maxDerived
The largest reading in the sample, whether or not a whisker reaches it. Of the readings on the real axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain max, which a sample of pairs does not have.
im-medianDerived
The middle reading — the rule across the box. Of the readings on the imaginary axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain median, which a sample of pairs does not have.
im-q1Derived
The lower quartile: the median of the lower half of the ordered readings. Of the readings on the imaginary axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain q1, which a sample of pairs does not have.
im-q3Derived
The upper quartile: the median of the upper half. Of the readings on the imaginary axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain q3, which a sample of pairs does not have.
im-iqrDerived
The interquartile range, q3 − q1 — the width of the box. Of the readings on the imaginary axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain iqr, which a sample of pairs does not have.
im-minDerived
The smallest reading in the sample, whether or not a whisker reaches it. Of the readings on the imaginary axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain min, which a sample of pairs does not have.
im-maxDerived
The largest reading in the sample, whether or not a whisker reaches it. Of the readings on the imaginary axis: a box of a pair of samples publishes each axis's numbers under that axis's name, and no plain max, which a sample of pairs does not have.
re-meanDerived
The mean of the readings on the real axis, in its units, published by a box of a pair of samples under that axis's name in place of a plain mean.
re-countDerived
The number of pairs a box of a pair of samples summarises, under the real axis's name in place of a plain count.
im-meanDerived
The mean of the readings on the imaginary axis, in its units, published by a box of a pair of samples under that axis's name in place of a plain mean.
im-countDerived
The number of pairs a box of a pair of samples summarises, under the imaginary axis's name in place of a plain count.

#Allowed in

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

#Examples

A teal box plot of a trial’s control arm, labelled control, one reading far out to the right.A teal box plot of a trial’s control arm, labelled control, one reading far out to the right.
graph:x{
    boxplot(x: #trial.mass; colour: teal; label: control)
}
The same readings with the whiskers running to the extremes, so the far reading is inside them.The same readings with the whiskers running to the extremes, so the far reading is inside them.
graph:x{
    boxplot(x: #trial.mass; whiskers: extremes)
}
Three box plots side by side, one for each group of studies: fewer, same and more.Three box plots side by side, one for each group of studies: fewer, same and more.
graph{
    boxplot(x: #studies.change; y: #studies.impact)
}

Last updated