Skip to main content
A boxplot compares how values spread across categories. Each box runs from the first to the third quartile with a line at the median, whiskers reach out to the furthest values close to the box, and any value beyond them is drawn on its own as an outlier.
The boxplot ships as its own package, @graphysdk/geom-boxplot, on a 0.x version line. While it is on 0.x, a minor release may change its aesthetics, params, style parts or look; pin a caret range (^0.1.0) to take only patches. Tell us what works and what doesn’t on Discord.

Install

Its only peer dependencies are @graphysdk/react and React. Register the plugin once with createGraphyKit, which adds kit.geom.boxplot() and binds kit.GraphProvider to the same plugin:

One box per category

Pass the raw values, one row per value, and map the category to x and the value to y. The geom’s boxplot stat computes the summary:
The quartiles interpolate between the middle values, as R, NumPy and d3 compute them. Each whisker reaches the furthest value within 1.5 interquartile ranges of the box (Tukey’s rule), and every value past it is an outlier. The value axis fits every value, outliers included, instead of holding zero. The category axis is always discrete.

Whisker reach

extent sets how far a whisker may reach, in interquartile ranges. 'min-max' runs the whiskers to the smallest and largest values, so no value is drawn as an outlier:
The whiskers and outliers are computed on the raw values, before a log scale transforms them.

Summarized data

If your data already holds the summary, one row per box, set stat to identity and map your own columns: lowerWhisker, q1, median, q3 and upperWhisker are required.
The rest is optional. A row that holds only an outlier value is drawn as an outlier on its category’s box. mean, notchLower and notchUpper are drawn when you map them, and count appears in the tooltip and sets the widths under varwidth. Grouping by color works as it does for raw values. The default is stat: kit.stat.boxplot(); naming it does the same as leaving stat out. Under it, mapping a summary aesthetic is an error, since the stat computes them all from y.

Outliers, notches and means

Each option is a param, and each is off by default except the outliers:
Two boxes whose notches do not overlap have medians that differ, roughly at the 95% level. A notch wider than its box folds over the box’s end, which says the median is uncertain.

Box width

width sets how much of its band a category’s boxes span, as a fraction from just above 0 up to 1. It is 0.6 by default, and grouped boxes share it. A width above 1 is clamped to the full band, and one at or below 0 falls back to the default; the compiler warns in both cases:
varwidth: true scales each box’s width by the square root of how many values it summarizes, relative to the largest box, so a box drawn from few values reads as thinner evidence.

Groups

Map a group to color and each category draws one box per group, side by side across its band, colored from the scale:
position: 'identity' draws a category’s boxes over one another instead. A boxplot does not stack.

Horizontal

Add kit.coord.flip(). The categories move to the vertical axis and the boxes lie across.

Styling

The boxes are the observations, and each other piece has a builder of its own. Every piece takes its group’s color from the scale unless an entry names one: To drop the caps and keep the whiskers, set kit.style.geom.boxplot.cap({ strokeWidth: 0 }).

The summary variables

A box’s summary values are variables you can name in a highlight, an entry’s where or an aesthetic’s mapping, in the units of y. The package exports their names as BOXPLOT_VARIABLES: A box keeps any other variable its rows all agree on, such as the category and the group, and leaves the rest empty. y is one of them, so a box has a y only when all its values are equal. An outlier keeps its own row, y included, so a highlight on y reaches the outliers it matches.

Hover and highlight

Hovering a box emphasizes it and its outliers, and the tooltip lists its upper whisker, third quartile, median, first quartile, lower whisker and count, then its mean when showMean is on. A press anywhere from one whisker’s end to the other takes the box. In a grouped boxplot the box under the cursor answers alone. Hovering an outlier emphasizes it alone, and the tooltip shows its value. A highlight raises each matched box with its outliers. Match on the category, the group or a summary variable:

Not yet supported

  • The editor’s chart-type picker and the chart agent. In annotate mode the boxplot renders, hovers, selects and takes annotations on each box’s median, but it is authored in code.
  • Other stats. A layer stat that computes y (count, mean, sum) is rejected: a box needs a summary, from the boxplot stat or your own columns.
  • A continuous category axis or polar coordinates. x is always read as categories, and the boxplot draws in cartesian coordinates, vertical or under coord.flip().
  • Data labels. dataLabels prints nothing on a box yet.
  • Raw points, jittered or as a violin. Draw them as a separate point layer.