<chart>

<chart> draws data, and type picks which chart is drawn — there is no default, so every chart names one. To chart several groups of data together, give the chart a <series> child per group.

Attributes and Properties

Chart types

Each type reads its data a little differently, and what a <series> holds is what changes. The title, the legend and the sizing are written the same way whichever chart is drawn.

type="bar"

One bar per value, standing on a baseline of zero, under a horizontal axis of category names. A series holds one value per category.

type="line"

A path through each series’ values, in the order given. A series holds one value per category, or a value per x when it has one.

Without an x the points sit under categories, evenly spaced; with an x they sit at the positions it gives and the axis carries numbers. Values are never re-ordered — a path that doubles back is drawn as one.

type="scatter"

One point per value, drawn at the x beside it. A series holds the vertical coordinates and its x the horizontal ones.

type="pie"

One slice per value, each one that value’s share of the total. The slices run clockwise from twelve o’clock in the order the values are given, and categories names them. A pie draws one series.

The slice names go in the legend, and around the rim instead when there is no legend to hold them. displayValues writes each value out at the rim as well, beside its slice’s name when that is there too — as Wind (40) in the second chart. Each slice takes a color of its own, where every other type colors by series.

type="box"

A box plot per series, side by side. A series holds raw observations — a column of measurements — rather than one value per category, and the box drawn from it runs from the first quartile to the third with the median across it.

Each series is one position on the axis, named under its box by its own <label> — or by its position, as the single box above is, where there is no label to name it. The whiskers reach the furthest observation within one and a half interquartile ranges of the box, and an observation past that is drawn as a point of its own — the 96 in the second section. The vertical axis is the data’s, so it need not include zero.

Each <series> also reports its own summary — minimum, quartile1, median, quartile3, maximum and outliers — computed the same way <summaryStatistics> computes them, so a table beside the picture agrees with it.

type="histogram"

One bar per bin, adjacent with no gap, over a numeric axis of cut points. A series holds raw observations, and each bar is as tall as the number of them that fall in its bin. A histogram draws one series.

Write no bins and the cut points are chosen from the data, at a width that keeps them round numbers; write a number and the range is divided into that many equal bins; write two or more numbers and they are the cut points themselves, as in the second chart above. The horizontal axis is labeled at the cut points, and a value falling exactly on one is counted in the bin above it unless closed="right" says otherwise; a value on the outermost cut point is counted either way.

The chart reports the bins it drew: binEdges is the cut points in order and binCounts is how many fell in each, so a sentence, a table or an <answer> can be written beside the picture. <binCounts> counts the same data the same way, for the counts without a picture.

Examples

Example: a bar chart of counts

The values are written as plain numbers, separated by spaces. <number> and <math> children work too, as does a reference to anything that produces numbers, which is how a chart of computed values is written. displayValues prints each bar’s value above it.

Every bar carries its category and value as an annotation, so a screen reader can walk the chart rather than merely announce it, and a <shortDescription> becomes the description of the figure as a whole.

Example: several series in one chart

Each <series> is one group of the data, drawn in its own color. Its children are the values — bare numbers, <number> and <math> children, a <numberList>, or a reference to something that produces numbers — and its <label> names it in the legend, which appears as soon as a series has one. Series take consecutive style numbers unless one is given a styleNumber of its own, so the groups come out in different colors without being asked to. A screen reader walks the chart series by series, then mark by mark within a series.

A series may also carry an x, which gives its values horizontal coordinates and puts the chart on a numeric axis instead of the categories. type="scatter" is normally drawn that way, and type="line" may be; both fall back to the categories when no series carries an x.

A chart written with bare values and no <series> has one unnamed series holding them all, which is why the simpler charts here need no series at all.

A <title> is drawn above the chart and travels with the picture, so it is still there if the chart is printed or exported.

Example: a bar chart of a simulation

<binCounts> turns a sample into counts per interval and <chart> draws them; <tally> does the same for named categories. Building a whole sampling simulation this way is walked through in Charting a Simulation.

Example: a box plot beside the numbers behind it

A box plot and a <summaryStatistics> of the same numbers report the same five, so the table and the picture can stand side by side. Naming the <series> is what makes each of them readable into a sentence.

Example: a histogram and the counts behind it

The counts are numbers the document can read, which is what lets the same bins be drawn, described in a sentence and asked about without being written out three times.

Attribute Examples

Attribute Example: type

type picks the mark the data is drawn with, not the data itself: all three charts above hold the same three values. Two of them are the same numbers under different marks, which is the whole of what this attribute does — everything else about a chart is written the same way whichever type is named.

There is no default, so the third draws nothing and says so.

Every type is listed under Chart types, with what a series holds for each.

Attribute Example: categories

Each bar takes the category in the matching position; without categories, the bars are numbered 1, 2, 3, 4. A category is a label and nothing else — the bars are evenly spaced whatever it says, so categories="1 5 6" writes 1, 5, 6 under three equally spaced bars rather than placing them at those positions.

With several series, the categories run along the axis and the series are what the legend names, so a chart of four categories and two series has four category names and two series labels.

A bar chart and a pie name their positions this way, and so do a line or scatter chart whose series carry no x — with an x those are placed by measurement instead, and have no positions to name. Neither do the two types whose series holds raw observations: a box plot’s positions are its series, named by their own labels, and a histogram’s are its bins, named by the cut points they run between.

Attribute Example: bins, closed

One number is a number of equal-width bins and is used exactly; two or more are the cut points themselves, so n + 1 of them make n bins. Written neither way, the bins are chosen from the data: as many as the sample size suggests, at a width that keeps the cut points round numbers.

closed says which end of a bin includes its cut point — left by default, so a bin runs [a, b) and a value on a cut point is counted in the bin above it, and closed="right" makes it (a, b]. Each outermost cut point belongs to its own bin either way, so an observation sitting exactly on the first or the last of them is counted. This is how <binCounts> reads the same attribute, and both count the same data the same way.

Only a histogram divides its data, so these are the histogram’s alone.

Attribute Example: layout

Side by side by default, so the bars can be compared both across categories and across series. layout="stacked" puts them one above another instead, so each category’s total is what you read; negative values stack downward from the baseline rather than through the positive ones. A chart of one series looks the same either way.

displayValues labels each series separately in both, so a stacked bar reads as its parts: the second chart’s middle bar is 9 and 5 rather than 14. Give a stacked chart segments too thin to label and the numbers will run together, since each is drawn at the top of its own segment.

layout is a bar chart’s alone: it says how several series share one category’s slot, and no other type puts two series in the same place.

Attribute Example: legend, legendPosition

A legend appears as soon as a series has a <label>, so a chart whose series are unnamed never grows one — a legend names the series, and there is nothing to put in one until they are named. legend="false" suppresses it even when they are.

legendPosition says where it goes. By default it sits outside the plot, to the right, in a margin widened to hold it — so it never covers the data, at the cost of some of the chart’s width. outsideBottom puts it below the horizontal axis instead, spending height rather than width, which suits long series labels or a wide chart.

The four inside corners — upperRight, upperLeft, lowerRight, lowerLeft — spend neither, and are worth reaching for when the chart has a corner to spare. They can cover a mark, as the third chart above does: room has to be made for one, either by a bound that pushes the data clear of that corner or by choosing a corner the data does not reach.

On a pie the legend names the slices rather than the series, since a pie’s colors tell its slices apart. legend="false" there moves the names out to the rim, so they are always somewhere:

$chart.showLegend reports whether a legend is drawn, so it is false for a suppressed legend and for one with nothing to name — series that carry no label, or named series with no value that could be drawn. On a pie there is something to name as soon as a slice is drawn.

A bar, line, scatter or histogram chart’s legend names its series, and a pie’s names its slices. A box plot draws none: its series are already named on the axis, under the box drawn from each.

Attribute Example: yMin, yMax

The axis scales itself to the data, and either bound may be replaced on its own. Bars are measured from zero whatever the axis shows, so the third chart cuts them off at the bottom of the frame, and the two bars that end below 5 disappear entirely, leaving only the one of height 9.

Left to choose for itself, a bar chart’s vertical axis includes zero, because its bars are measured from it, and so does a histogram’s, whose bars are counts — a yMin above zero crops them, as the third chart above shows. A line, scatter or box chart’s is not anchored to zero at all: its marks are measured from nothing, so the axis scales to the data alone. A pie has no axes and reads neither bound.

Attribute Example: xMin, xMax

The horizontal counterpart of yMin and yMax, and only for a chart whose horizontal axis carries numbers — a histogram, and a line or scatter chart whose series carry an x. On a categorical axis the positions are 1, 2, 3 whatever the categories say, so there is nothing to bound: a bar chart, a box plot, and a line or scatter chart no series of which carries an x, report nothing for them.

Attribute Example: markers

A marker is drawn at each of a line chart’s points unless markers="false" says otherwise, which suits a series long enough for the markers to merge into the line. A scatter plot is its markers, so it always draws them and ignores this.

The markers are also what a screen reader walks: each one carries its own annotation, and with them off the line carries a single annotation for the whole series instead.

Attribute Example: size, aspectRatio, barWidth

size sets the width and aspectRatio the width over the height, whichever chart is drawn. barWidth is bar-only: it says how much of its slot each category fills, and the series of a category divide that between them. A histogram’s bars are adjacent, with no gap to widen into, and a box’s width is fixed. A width may be given instead of a size, and picks the nearest preset rather than being used exactly, so width="400px" draws the same chart as size="medium".

Property Examples

Property Example: values, categories, numSeries, yMin, yMax

values is every value in the chart, series by series, so a chart of one series reports exactly what it was given; naming a <series> is how one group is read on its own.

yMin, yMax, xMin, xMax, barWidth and aspectRatio report what the chart was drawn with rather than what was asked for, so $counts.yMax is the top of the axis you can see even though nothing above set one. xMin and xMax report nothing for a chart whose horizontal axis carries category names rather than numbers, and a pie reports nothing for any of the four: it has no axes to read a value off.

Property Example: a series’ own summary

Every <series> reports minimum, quartile1, median, quartile3, maximum and outliers about the values it holds, whichever chart was drawn from them, so a sentence beside the picture can say what the picture shows. outliers is the observations a box plot draws as points beyond its whiskers.

Property Example: binEdges, binCounts

A histogram reports the bins it drew, whether the cut points were written out or chosen from the data, so a document can state them without repeating them. binEdges has one more entry than binCounts: n + 1 cut points make n bins.