<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.

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.

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.

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.

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.

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.

A bar chart’s vertical axis always includes zero, because its bars are measured from it. A line or scatter chart’s does not: its points are measured from nothing, so the axis scales to the data alone.

Attribute Example: xMin, xMax

The horizontal counterpart of yMin and yMax, and only for a chart whose horizontal axis carries numbers. On a categorical axis the positions are 1, 2, 3 whatever the categories say, so there is nothing to bound: a bar chart, and a line or scatter chart no series of which carries an x, ignore these and 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 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.