ComponentAdded in v15.1

Box Plot

How the values of several groups are spread: the median, the middle half, the range and the outliers of each, side by side.

Installation

Import the class, and @use the entry point in your global styles: without it the component renders unstyled.

import { Component } from '@angular/core';
import { WrBoxplotChart } from 'ngwr/charts/boxplot-chart';

@Component({ imports: [WrBoxplotChart] })
export class MyComponent {}

Basic

Pass each group's raw values. The chart works out the quartiles, the whiskers and the outliers. The value axis fits the data and is not forced to zero.

<wr-boxplot-chart
  ariaLabel="Response time by region"
  xLabel="Region"
  yLabel="Response time, ms"
  [groups]="[
    { label: 'Europe', values: [96, 102, 108, 111, 115, 290] },
    { label: 'Asia', values: [120, 131, 140, 148, 155, 161] }
  ]"
/>
Response time, ms
EuropeNorth AmericaAsiaSouth America
Region

Reading a box

Quartiles use linear interpolation: type 7, the default in R and NumPy, and Excel's QUARTILE.INC. Whiskers follow Tukey's rule.

<wr-boxplot-chart
  ariaLabel="Eleven values, one outlier"
  [groups]="[{ label: 'Sample', values: [12, 14, 15, 17, 18, 19, 21, 22, 24, 27, 48] }]"
/>
Sample
MarkMeansHere
BoxThe first quartile to the third: the middle half of the values.16 to 23
Line in the boxThe median.19
WhiskersThe farthest values within 1.5 × the box's height (the IQR) of the box.12 and 27
DotsOutliers: values past the whiskers' reach.48, past 23 + 1.5 × 7

Precomputed stats

Already have the summary? Pass stats instead of values. It is drawn as given. A group's color overrides the chart's.

<wr-boxplot-chart ariaLabel="Build time by release" yLabel="Build time, s" [groups]="releases" />
releases: WrBoxplotGroup[] = [
  { label: 'v14', stats: { min: 80, q1: 101, median: 118, q3: 134, max: 170, outliers: [240, 262] } },
  { label: 'v15', stats: { min: 70, q1: 92, median: 104, q3: 121, max: 150, outliers: [31] } },
  { label: 'v15.1', stats: { min: 61, q1: 80, median: 90, q3: 101, max: 128 }, color: 'var(--wr-color-success)' },
];
Build time, s
v14v15v15.1

Number format

Numbers follow LOCALE_ID. valueFormat replaces it for the ticks, the tooltip and the data table.

<wr-boxplot-chart ariaLabel="Build time by release" yLabel="Build time" [groups]="releases" [valueFormat]="seconds" />
const unit = new Intl.NumberFormat('en-US', { style: 'unit', unit: 'second' });

seconds = (value: number): string => unit.format(value);
Build time
v14v15v15.1

Data table

dataTable adds a table only screen readers reach: a row per group, its five numbers and its outliers. Nothing changes on screen.

<wr-boxplot-chart ariaLabel="Response time by region" dataTable [groups]="regions" />
Response time, ms
EuropeNorth AmericaAsiaSouth America
Region
Response time by region
RegionLower whiskerQ1MedianQ3Upper whiskerOutliers
Europe96113124137.5156290
North America10411913415017531
Asia120149.75171196.75238
South America150188204221230340, 365

Accessibility

PartBehaviour
PlotOne role="img", named by ariaLabel. No tab stop.
ValuesOnly in the tooltip, unless dataTable is on.
GroupsNamed under their boxes. Colour carries nothing the name does not.
TooltipPointer only. Escape closes it.
Forced coloursEvery mark is drawn as an outline in the system text colour.

API

NameDescriptionTypeDefault
groupsOne entry per box, in reading order: each with its raw values or a stats summary worked out elsewhere. A group with neither, or with nothing finite to summarise, keeps its slot and its name and draws no box.readonly WrBoxplotGroup[][]
ariaLabelAccessible name of the chart. The numbers are nowhere in text unless dataTable puts them there, so say what the chart shows. Falls back to boxplotChart.label ("Box plot").string | nullnull
xLabelWhat the groups are — a region, a release. Drawn under the group names only when given; either way it heads the group column of the data table, which falls back to boxplotChart.group ("Group").string | nullnull
yLabelWhat the values measure, with their unit. Drawn above the value axis only when given.string | nullnull
valueFormatWrites every number the chart shows: the axis ticks, the tooltip and the data table. null uses Intl.NumberFormat in LOCALE_ID, with compact ticks (1.2K, 3.4M) unless the full numbers are shorter.((value: number) => string) | nullnull
colorThe colour of every group with no color of its own. Any CSS colour.string'var(--wr-color-primary)'
heightThe plot's height in px, at least 80. Under 160 the value axis aims for fewer ticks, so their labels keep clear of one another.number240
showGridShow the gridlines and the value axis' tick labels.booleantrue
tooltipShow a tooltip with the hovered group's five numbers — the whiskers' ends, the quartiles and the median — and its outliers' values, the lowest three, then how many more there are. Pointer only.booleantrue
dataTableRender every group's numbers as a table only assistive technology reaches, beside the drawing: a row per group, a column for each of the five numbers from the lower whisker up and, when a group has any, one listing its outliers. The drawing is one named image, so without it the numbers are nowhere a screen reader can walk.booleanfalse

Types

interface WrBoxplotGroup {
  label: string;
  values?: readonly number[];
  stats?: WrBoxplotStats;
  color?: string;
}

interface WrBoxplotStats {
  min: number;
  q1: number;
  median: number;
  q3: number;
  max: number;
  outliers?: readonly number[];
}
NameDescriptionTypeDefault
WrBoxplotGroupOne box.interface—
labelrequiredThe group name: under its box, in the tooltip and the data table.string—
valuesRaw values to summarise. A non-finite value is left out. Ignored when stats is given.readonly number[]undefined
statsA summary worked out elsewhere, drawn as given.WrBoxplotStatsundefined
colorAny CSS colour.stringthe chart's `color`
WrBoxplotStatsThe five numbers and the outliers.interface—
minrequiredThe lower whisker’s end: the smallest value that is not an outlier.number—
q1requiredThe first quartile: the box’s lower edge.number—
medianrequiredThe line across the box.number—
q3requiredThe third quartile: the box’s upper edge.number—
maxrequiredThe upper whisker’s end: the largest value that is not an outlier.number—
outliersValues drawn as dots past the whiskers.readonly number[]undefined

CSS variables

Set these on the component's selector or a wrapper, not on :root: the defaults are declared on ngwr/charts/boxplot-chart's own element.

VariableDefaultDeclared on
--wr-boxplot-chart-active-bgcolor-mix(in srgb, var(--wr-color-on-surface) 6%, transparent).wr-boxplot-chart
--wr-boxplot-chart-box-radiusvar(--wr-border-radius-sm).wr-boxplot-chart
--wr-boxplot-chart-box-tint20%.wr-boxplot-chart
--wr-boxplot-chart-box-tint-active40%.wr-boxplot-chart
--wr-boxplot-chart-box-widthmin(3rem, 60%).wr-boxplot-chart
--wr-boxplot-chart-cap-widthcalc(var(--wr-boxplot-chart-box-width) / 2).wr-boxplot-chart
--wr-boxplot-chart-colorvar(--wr-color-on-surface).wr-boxplot-chart
--wr-boxplot-chart-font-familyvar(--wr-font-family-base).wr-boxplot-chart
--wr-boxplot-chart-grid-colorcolor-mix(in srgb, var(--wr-border-base) 70%, transparent).wr-boxplot-chart
--wr-boxplot-chart-label-colorvar(--wr-color-on-surface).wr-boxplot-chart
--wr-boxplot-chart-label-font-sizevar(--wr-text-xs).wr-boxplot-chart
--wr-boxplot-chart-label-gapvar(--wr-space-xs).wr-boxplot-chart
--wr-boxplot-chart-label-line-heightvar(--wr-text-xs-leading).wr-boxplot-chart
--wr-boxplot-chart-line-width2px.wr-boxplot-chart
--wr-boxplot-chart-median-colorvar(--wr-color-on-surface).wr-boxplot-chart
--wr-boxplot-chart-median-width3px.wr-boxplot-chart
--wr-boxplot-chart-outlier-fillvar(--wr-color-surface).wr-boxplot-chart
--wr-boxplot-chart-outlier-size0.5rem.wr-boxplot-chart
--wr-boxplot-chart-plot-inset-xvar(--wr-space-sm).wr-boxplot-chart
--wr-boxplot-chart-plot-inset-yvar(--wr-space-sm).wr-boxplot-chart
--wr-boxplot-chart-tick-colorvar(--wr-color-on-surface-muted).wr-boxplot-chart
--wr-boxplot-chart-tick-font-sizevar(--wr-text-xs).wr-boxplot-chart
--wr-boxplot-chart-tick-gapvar(--wr-space-xs).wr-boxplot-chart
--wr-boxplot-chart-tick-line-heightvar(--wr-text-xs-leading).wr-boxplot-chart
--wr-boxplot-chart-title-colorvar(--wr-color-on-surface-muted).wr-boxplot-chart
--wr-boxplot-chart-title-font-sizevar(--wr-text-xs).wr-boxplot-chart
--wr-boxplot-chart-title-font-weightvar(--wr-font-weight-medium).wr-boxplot-chart
--wr-boxplot-chart-title-gapvar(--wr-space-xs).wr-boxplot-chart

Dependencies

Built onPopover

See also