demo D239
Reference lines, targets and bands
Target and limit lines and a shaded range over a chart, with a mean line read from the data
annotations: [{ kind: 'line', compute: 'mean' }]
The configuration
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.24.0/lattice-grid.min.css">
<script src="https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.24.0/lattice-grid.min.js"></script>
<div id="chart" style="height: 360px"></div>
<div id="grid" style="height: 340px; margin-top: 14px"></div>
<script type="module">
import { createChart } from 'https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.24.0/modules/charts';
const grid = LatticeGrid.createGrid(document.getElementById('grid'), {
rowKey: 'id',
columns: [
{ field: 'circuit', title: 'Circuit', layout: { width: 180 } },
{ field: 'region', title: 'Region', filter: { type: 'set' } },
{ field: 'status', title: 'Status', filter: { type: 'set' } },
{ field: 'bandwidth', title: 'Bandwidth', type: 'number' },
{ field: 'charge', title: 'Monthly charge', type: 'number',
format: { style: 'currency', currency: 'GBP' }, total: 'sum' },
],
rows,
});
// Reference marks over the chart: a shaded band, a target, and a
// mean line read from the data so it follows the filtered rows.
createChart({
grid,
container: '#chart',
type: 'bar',
x: 'region',
y: { col: 'charge', fn: 'mean' },
annotations: [
{ kind: 'band', from: 900, to: 1300, label: 'Target range' },
{ kind: 'target', value: 1100, label: 'Goal' },
{ kind: 'line', compute: 'mean', label: 'Mean charge' },
],
});
</script>Marking a chart with the numbers a reader is meant to judge it against
A chart of results is easier to read when the goals are drawn on it: the target to clear, the limit not to cross, the band to stay inside. Without them a reader has to hold those numbers in their head and eye them off the axis. Annotations in any JavaScript charting layer draw those reference marks directly over the plot. In Lattice Grid a chart’s annotations accept reference and target lines, both distinct so a limit does not read as a mere guide, and a shaded band that marks the range between two values, each with its own label. This is the shape a pass-or-fail chart wants: a spec band, a nominal target in the middle, and an upper limit line, all on the same picture as the data.
An annotation can be a number you type or a figure read from the data. A line given compute: 'mean' or a percentile is resolved from the chart’s current rows rather than fixed, so it always marks the mean, or the p95, of what is on screen. Because the chart reads the grid’s filtered rows, filtering the grid moves a computed line to the new mean on the next frame, so the reference stays honest as the data narrows. Every annotation is described in the chart’s text alternative alongside its label, so a reader using assistive technology hears the target and the limit, not just the bars.
How do you draw a target or reference line on a chart?
Pass an annotations array to the chart. Each entry has a kind: a line for a reference, a target for a goal drawn distinctly from a plain reference, or a band with from and to to shade a range. Give a fixed line a value, or give it compute: 'mean' or a percentile to read the figure from the data so it follows the filtered rows.
Can an annotation follow the data instead of being a fixed number?
Yes. An annotation with compute set to a statistic such as the mean or a percentile resolves against the chart’s current rows rather than a value you type. Because the chart draws from the grid’s filtered rows, the line moves to the new figure whenever the grid is filtered, so it always marks the mean, or the percentile, of what the reader is actually looking at.