Guide / Controls / Charts

Spread

How a set of numbers spreads out

When to use it. Distribution at a glance: one box-and-whisker (quartiles, median, Tukey outliers) or violin (kernel density body) per category. Push raw samples and the phone does the statistics — quartiles, 1.5 × IQR fences, gaussian KDE — or push precomputed stats when the server already reduced them. Tapping a distribution reads its median into the header and fires boxAction with the full five-number summary, so a latency plot doubles as a drill-down picker.

Type
boxPlot
Also titled
Box Plot
Default size
3 rows × 4 columns
Symbol
align.vertical.center
Docs
Docs complete
Search for it as
  • boxplot
  • distribution
  • quartile
  • whisker
  • spread
  • statistics
Spread: Latency by region (tap to inspect)
Rendered by the app

Fields

19 fields you can set on a boxPlot control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
haptichapticchoiceone of 10—

The buzz you feel on a tap

Plays this haptic on the phone when you tap or scrub the plot, on supported hardware.

  • noneno vibration
  • lighta small soft tap
  • mediuma medium tap
  • heavya strong thud
  • softa cushioned, muffled tap
  • rigida firm sharp click
  • selectionthe faint tick of picking an item
  • successthe double tap of a success
  • warninga two-pulse warning
  • errora sharp triple buzz of an error
Titlelabeltext—

The plot's title

Shows this text above the plot, with the selected box's median beside it.

ShapeboxStylechoiceone of 2box

Boxes or violins

Draws each category as a box-and-whisker or as a smooth violin-shaped density body.

  • box defaulta box with whiskers marking the quartiles and median
  • violina smooth shape showing where the samples cluster (needs raw samples)
boxPlotConfigboxPlotConfigobject—

Extra plot settings

Groups the options for axes, whiskers, colors, scrubbing and the tap action.

Colortintcolor#667eea

Main color

Colors the first box and seeds the color of the others.

formatValueformatValuetext—

How numbers are written

Formats the axis labels and the median readout, e.g. as a unit or with fixed decimals.

boxActionboxPlotConfig.boxActionobject—

What a tap does

Fires this action when you tap a box, passing its five-number summary as {{value}}.

Bar roundnessboxPlotConfig.barCornerRadiusnumber0–30 ptstep 13

Box roundness

Rounds the box corners from square (0) to 30 points.

Box widthboxPlotConfig.boxWidthnumber0–1step 0.050.55

How wide the boxes are

Sets each box's width as a fraction (0 to 1) of its category slot.

Box colorsboxPlotConfig.colorsstring[]—

Colors for each box

Cycles through this list of colors, one per category, instead of the built-in palette.

scrubboxPlotConfig.scrubon / offfalse (off)

Drag across the boxes

Lets a drag sweep the selection across categories with a tick for each change; the action still fires only on tap.

Grid linesboxPlotConfig.showGridon / offtrue (on)

Grid lines on or off

Shows or hides the horizontal grid lines behind the boxes.

Mean dotboxPlotConfig.showMeanon / offfalse (off)

Mean dot on or off

Shows or hides a hollow dot at each category's average.

OutliersboxPlotConfig.showOutlierson / offtrue (on)

Outlier dots on or off

Shows or hides the dots for values beyond the whiskers.

Bottom axisboxPlotConfig.showXAxison / offtrue (on)

Category names on or off

Shows or hides the category labels along the bottom.

Side axisboxPlotConfig.showYAxison / offtrue (on)

Value scale on or off

Shows or hides the value labels down the left side.

WhiskersboxPlotConfig.whiskerschoiceone of 2tukey

How far the whiskers reach

Sets whether the whiskers stop at the Tukey fences with outliers as dots, or stretch to the full range.

  • tukey defaultwhiskers stop at 1.5 times the spread and farther values show as dots
  • minmaxwhiskers reach the smallest and largest values with no outlier dots
yMaxboxPlotConfig.yMaxnumber—

Top of the scale

Pins the top of the value axis instead of fitting it to the data.

yMinboxPlotConfig.yMinnumber—

Bottom of the scale

Pins the bottom of the value axis instead of fitting it to the data.

Theme fields

Restyle one control by setting these in its theme object; a layout's theme sets them for every control.

Theme fields
FieldTypeDefaultWhat it does
secondaryColortheme.secondaryColorcolor#FFFFFF99

Dimmed text color

Colors the faintest text and ink on the chart.

Emits and receives

What this control sends when you use it, and what it can show or follow when data arrives.

Emits

Emits
SendsWhenTypeWhat it sends
When you tap a boxboxtapjson

the tapped category's five-number summary (index, min, q1, median, q3, max) as JSON

Dragging with scrub on only moves the highlight; nothing sends until you tap

Example: {"index": 0, "min": 1, "q1": 2, "median": 3, "q3": 4, "max": 5}

Receives

Receives
TakesFromTypeWhat it does
seriesshowhub, mqtt, http, store, defaultjson

a column of raw numbers per category (or ready-made quartile stats, which win when both are sent)

the boxes redraw from the new numbers; violins need the raw numbers

Example: {"categories": ["Sample A", "Sample B"], "samples": [[1, 2, 3, 4, 5], [2, 3, 4, 5, 6]]}

Sample

The placeholder value the editor shows before real data arrives.

  • {"categories": ["Sample A", "Sample B", "Sample C"], "samples": [[1, 2, 3, 4, 5, 9], [2, 3, 4, 5, 6], [3, 4, 5, 6, 7, 8]]} then {"categories": ["Sample A", "Sample B", "Sample C"], "samples": [[2, 3, 4, 5, 6], [3, 4, 5, 6, 7], [1, 3, 5, 7, 9]]}

Examples

3 examples, each one a control you can paste into a layout.

Latency by region (tap to inspect)

JSON 11 lines
{
  "type": "boxPlot",
  "id": "latency",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Latency (ms)",
  "boxPlotConfig": {
    "boxAction": { "method": "meshsocket", "mode": "broadcast", "event": "broadcast_request", "payload": { "msg_type": "inspect_region", "stats": "{{value}}" } }
  },
  "sync": [{ "method": "meshsocket", "type": "listen", "event": "broadcast", "filter": { "msg_type": "latency_samples" }, "valuePath": "regions" }]
}

Open in CAR-TER

Spread: Latency by region (tap to inspect)
Rendered by the app

Violin comparison

JSON 10 lines
{
  "type": "boxPlot",
  "id": "spread",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Sensor spread",
  "boxStyle": "violin",
  "boxPlotConfig": { "showMean": true },
  "defaultValue": "{\"categories\":[\"A\",\"B\"],\"samples\":[[5,6,6,7,7,7,8,9],[4,5,7,9,10,11,11,12]]}"
}

Open in CAR-TER

Spread: Violin comparison
Rendered by the app

Whiskers to the full range

Shows every value inside the whiskers, so no outlier dots appear, with a mean dot added.

JSON 9 lines
{
  "type": "boxPlot",
  "id": "full-range",
  "position": [0, 0],
  "span": [3, 4],
  "label": "Response time",
  "boxPlotConfig": { "whiskers": "minmax", "showMean": true },
  "defaultValue": "{\"categories\":[\"A\",\"B\"],\"samples\":[[10,12,13,15,18,40],[20,22,25,26,30,31]]}"
}

Open in CAR-TER

Try it on your phone

carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Latency by region (tap to inspect)” on your phone.

    carterkit demo boxPlot --example 'Latency by region (tap to inspect)'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Wide like Axis bottom: [3, 4]. In a flow grid it auto-sizes to a 16:10 cell.

BoxPlotConfig

Field Type Default Description
showXAxis bool true Category labels along the bottom
showYAxis bool true Value labels down the left gutter
showGrid bool true Horizontal grid lines
yMin / yMax number data range Pin the value axis
whiskers string "tukey" "tukey" (1.5 × IQR fences + outlier dots) or "minmax" (full range)
showOutliers bool true Outlier dots beyond the whiskers
showMean bool false Hollow dot at the mean
boxWidth number 0.55 Box width as a fraction of the category slot
barCornerRadius number 3 Box corner rounding in points, 0–30
colors string[] built-in palette Per-category color cycle
boxAction ActionDefinition — Fired on tap; {{value}} = the stats as JSON
scrub bool false Drag sweeps the selection across categories with haptic ticks (readout only — the action still fires on tap)

Sync Payload Structure

Raw samples (the app computes the statistics) — natural JSON or an encoded string:

{
  "categories": ["us-east", "eu-west", "ap-south"],
  "samples": [
    [42, 51, 38, 66, 47, 130, 44],
    [61, 72, 58, 66, 70, 64, 69],
    [88, 95, 91, 180, 86, 90, 84]
  ]
}

Shorthand: a bare 2-D array [[…], […]] is samples with numbered categories.

Or precomputed stats (wins over samples if both are present):

{
  "categories": ["us-east"],
  "stats": [
    { "min": 38, "q1": 43, "median": 47, "q3": 58, "max": 66, "outliers": [130] }
  ]
}

Note: boxStyle: "violin" needs raw samples for the density body; with only stats it falls back to the skeleton bar.

Behavior

  • Dataset pushes animate via the control's animation profile
  • Tap a category to select it (header shows name ~median); tap again or tap empty space to clear
  • scrub: true lets a drag sweep the selection fluidly across categories with a tick per change
  • Quartiles use type-7 linear interpolation (same as Numbers/NumPy); violin bandwidth is Silverman's rule
  • The value axis pads 6% beyond the extremes so caps and outlier dots never clip

Notes

  • 2–6 categories read best; past ~8 the boxes get skinny on a phone
  • The control's value is the dataset JSON — selection never overwrites it
  • For a single streaming series use Title; for binned frequency shape use a Axis bottom histogram series

Generated from ControlDocs/box-plot.md. Something unclear or missing? Tell me.