Charts, statistics and units

API reference › Charts, statistics and units

The charts module

modules/charts draws thirty-five chart types from the grid's own data. It is optional and imports nothing from the grid (the grid is handed in) so the bundle carries the drawing and none of the grid, and a page that never charts never loads it.

import { createChart } from '@toclocoinc/lattice-grid/modules/charts';

const chart = createChart({
  grid,                       // the grid to read
  container: '#revenue',      // an element or a selector
  type: 'bar',
  x: 'region',                // the category column
  y: 'revenue',               // the measure column
});

A chart reads the grid's filtered rows. Filter, sort or edit the grid and every chart bound to it redraws on the next frame: there is nothing to subscribe to and nothing to keep in step. A chart of rows the user cannot see would be describing a different data set.

The types

A chart given data it cannot draw (a candlestick with three measures rather than four) says so on the chart rather than drawing nothing, because a chart that silently draws nothing is indistinguishable from one that is broken.

The spec

The chart

Clicking a chart

A chart emits point:click, point:hover and series:toggle. The common use is filtering the grid from a mark, which makes the pair two views of one selection rather than a chart beside a table.

chart.on('point:click', ({ point }) => {
  grid.filters.set({ col: 'region', op: 'eq', value: point.x });
});

Maps

A geomap takes an ISO code from one column and a value from another. Alpha-2, alpha-3 and numeric codes are all accepted, and continent codes draw a continent map without any outline data. Country outlines are yours to supply through shapes, because a world atlas is larger than the whole library and this package fetches nothing at runtime.

Codes that match nothing are counted and reported on the chart rather than dropped, a map missing half its data looks exactly like a map of a world where half the data is zero. The full code tables are in CHART-CODES.md.

grid.statistics

What the grid knows about its own numbers, and about how they have changed since the page loaded. Every figure is computed over the filtered rows, through the same column handles the totals row uses, so a median here and a median in the footer are the same number, by the same definition (R type 7).

grid.statistics.profile('margin');
// { column, rows, present, missing, distinct, min, max, mean, median,
//   q1, q3, iqr, stddev, outliers, histogram: [{ from, to, count }, …] }

grid.statistics.reduce('margin', 'p95');          // any registered kernel
grid.statistics.correlation('spend', 'revenue');  // Pearson's r, clamped to [-1, 1]
grid.statistics.weightedAverage('price', 'qty');

grid.statistics.covariance('spend', 'revenue');
grid.statistics.regression('spend', 'revenue');   // { slope, intercept, r2, stdError, n }
grid.statistics.spearman('spend', 'revenue');     // rank; one outlier cannot drag it
grid.statistics.kendall('spend', 'revenue');      // tau-b, null past 5,000 rows
grid.statistics.weightedQuantile('price', 'qty'); // the median by default

grid.statistics.series('price', { by: 'date', periodsPerYear: 252 });
// { volatility, annualisedVolatility, growth, maxDrawdown, maxDrawdownFrom,
//   maxDrawdownTo, autocorrelation, upDays, downDays, … }

grid.statistics.capability('mm', { baseline: 20 });
// { cp, cpk, pp, ppk, sigmaWithin, sigmaOverall, outOfSpec, defectRate,
//   limits: { centre, upper, lower, sigma }, violations: [{ index, rule }] }

grid.statistics.shadow('price', 'delta', 'R42');  // one row's shadow value
grid.statistics.rebase('price');                  // "mark all": today's values become the baseline
grid.statistics.tracking();                       // { columns, rows, forgotten }

The statistics tool panel is the end-user half of profile(): a column picker, the twelve figures and a histogram of the column's shape, all following the filters. Add it with toolPanel: { panels: ['columns', 'statistics'] }.

It shows the twelve one-pass figures, then Shape (skewness, kurtosis, Jarque-Bera), Robust (trimmed and winsorized means, MAD, robust outliers), Concentration (Gini, HHI, entropy, evenness, top-3 share) and Capability where the column declares a spec. A section whose reductions all return null is left out rather than shown as a column of dashes.

Or put it in your own page. mountPanel takes no dock and does not create one: toolPanel may be off entirely, so a statistics readout can sit beside a chart, in your own sidebar, or in a settings dialog, at whatever size you give it. It repaints on the same events the rail does, so it stays in step with filters, edits and saved views without you subscribing to anything.

import { mountPanel } from '@toclocoinc/lattice-grid';

const stats = mountPanel({ grid, panel: 'statistics', container: sidebar });
stats.refresh();   // for a change the grid does not announce
stats.destroy();   // yours to call: the element belongs to your page

Any built-in panel works: columns, filters, views, quick, formatting, statistics, as does a constructor of your own.

The reductions

Forty-one, all available to a totals row, to reduce() and to the profiling panel. Names are the same everywhere and the labels come from the message catalogue, so a grid in Polish reads in Polish.

Process capability

Declare the customer's tolerance on the column, and the capability figures, a control chart and any rule marking an out-of-tolerance cell all read the same limits.

columns: [{ field: 'mm', type: 'number', spec: { lower: 9.5, upper: 10.8, target: 10 } }]

Cp and Cpk use short-term variation, estimated from the moving range; Pp and Ppk use the overall standard deviation. The gap between them is the point: Cpk well above Ppk means the process drifted. Cp above Cpk means it is precise and aimed wrong, which needs a different fix from being too variable.

Seeing it

The statistics have chart types to match, in modules/charts. Each takes its numbers from this namespace rather than recomputing, so a coefficient in a matrix and the same one from the API cannot drift apart.

Values the grid maintains for you

Three of the ideas in this section are not standard grid vocabulary, so it is worth saying what they have in common before the detail. Each of them is a value the grid keeps up to date from data you already have, declared once rather than maintained by hand.

The alternative, in every application that needs one of these, is a parallel structure in the host: a copy of what each row looked like a moment ago, a rank recomputed on every tick, a cumulative total that has to be redone whenever the sort changes, and a dashboard panel running its own query beside the table. That code works for a while and then produces a number nobody can account for, usually because one part of it noticed a filter and another did not.

The line between a shadow and a running column is the sort order. A shadow is a function of the column: a row’s own history, or where its value sits among the others. Sort the grid differently and a rank is still the same rank. A running total is the opposite : it answers “how much by the time we reach this row”, and by the time is the order the rows are in, so re-sorting changes every value in the column. That is why they are declared separately rather than as two kinds of one thing.

A derived grid is a different scale of the same idea. A shadow adds a column to the rows you have; a derivation produces different rows altogether: one per sales person rather than one per sale. Because it is a source rather than a special kind of grid, the result sorts, filters, totals, themes and exports like any other, and can itself be the source of another.

All three read the rows the grid is currently showing, so a filter applied to the table moves the ranks, the running totals and every derived panel together. That is the property worth having: not that any one of them is clever, but that they cannot disagree.

Shadow columns

A shadow column is declared against another column and maintained by the grid. It has no field in the data and it is not a pure computed column either, because its value depends on what happened before. It is a real column throughout: sortable, filterable, totalled, grouped, exported, saved into a view, which is what makes "show me every circuit repriced more than twice this session, most-changed first" one gesture rather than a report.

columns: [
  { field: 'price', type: 'number' },
  { id: 'moved',  title: 'Change',  shadow: { of: 'price', kind: 'delta' } },
  { id: 'churn',  title: 'Updates', shadow: { of: 'price', kind: 'updates' } },
  { id: 'run',    title: 'Streak',  shadow: 'streak' },   // shorthand: shadows the column beside it
]

A second family answers where the row sits among the others rather than what it did before. They share the same declaration and the same state, the tracker already holds every row's current value and its baseline, which is exactly what a rank and a rank change need.

Running totals

A running column answers “how much by the time we reach this row”: a balance that accumulates down the page, or the share of the total accounted for so far. It is the column a Pareto chart is made of, and the one a finance report opens with.

It is declared separately from a shadow column, and the sort order is the reason. Every shadow is a function of the column (of a row's own history, or of where its value sits among the others) so it reads the same however the rows are arranged. A running total does not: sort the grid differently and every value changes, because the question is "how much by the time we reach this row", and by the time is the sort order.

columns: [
  { field: 'amount', type: 'number' },
  { id: 'cum',   title: 'Running',      running: { of: 'amount', kind: 'total' } },
  { id: 'share', title: 'Cumulative %', running: { of: 'amount', kind: 'percent' } },
]

Computed in one pass over the display rows and cached against that ordering, so a hundred thousand rows are walked once per sort rather than once per cell. A running column is not sortable. Sorting on one asks the sort to depend on its own output (the value is defined by the display order) so the column does not offer a sort unless its definition asks for one, and the query layer refuses such a sort with a warning rather than computing it. Sort by the column it runs over instead. Group headings and totals rows are skipped, a running total that counted a subtotal would double everything below it, and a row with no value carries the figure forward unchanged rather than resetting it.

The statistic block

createStat draws the tile a dashboard opens with: a label, a value, its change against a baseline, and a line saying what the comparison was. Two things make it worth using rather than writing. It reads the grid, so it cannot disagree with the table beneath it, a tile saying £4.2M above a table filtered to £1.8M is worse than no tile, and that is what a hand-built tile does the first time somebody adds a filter. And it formats through the column's own type: a stat over a seconds column reads 42.1 ms, over a money column with an auto ladder £1.2M, with nothing declared.

import { createStat } from '@toclocoinc/lattice-grid';

createStat({
  grid, container: '#mrr',
  title: 'Monthly recurring revenue',
  of: 'mrr', fn: 'sum',
  baseline: lastMonth,
  footer: 'vs. last month',
});

The column's formatter is borrowed only where the reduction leaves the unit alone. A Gini coefficient over a money column is a ratio between 0 and 1, and rendering it as $0.34 says it is thirty-four cents; counts, ratios and variances, which are in units squared: fall back to a plain number.

Returns { element, value, refresh, destroy }. A misconfigured tile returns an inert handle rather than throwing, so a dashboard with one bad tile still renders the other eleven.

Units of your own

Twenty-six unit systems ship: length, mass, pressure, data, bitrate, angle, temperature, flow and the rest. A family of your own takes three things, and all three are yours to set: the symbols, where the symbol sits relative to the number, and how the rungs relate to each other.

import { registerUnitSystem, defineUnit, createUnitType } from '@toclocoinc/lattice-grid';

// `factor` is how many base units one of these is. Exactly one must be 1.
registerUnitSystem('distance', [
  defineUnit('mm', 0.001, ['millimetre', 'millimetres']),
  defineUnit('cm', 0.01,  ['centimetre', 'centimetres']),
  defineUnit('m',  1,     ['metre', 'metres']),
  defineUnit('km', 1000,  ['kilometre', 'kilometres']),
]);

createGrid(el, {
  dataTypes: {
    distance: createUnitType({ system: 'distance', unit: 'm', display: 'auto' }),
  },
  columns: [{ field: 'span', type: 'distance' }],
});

The factor values are the relationship between the rungs: there is no separate ladder to declare, and no ordering to get right, because the ladder is sorted by factor at load. A hand-ordered list of thirty units is one transposition away from an auto display that walks backwards, and that mistake is invisible in review.

A unit given { auto: false } stays off the display: 'auto' ladder while remaining accepted on input and available as an explicit display. That is how imperial units sit beside metric ones without an auto readout jumping between the two.