Statistics

A stat summarizes a layer’s data before it is drawn. Instead of plotting raw rows, the layer plots a computed result: a count, a mean, or a fitted regression line. A stat is set per layer through the geom’s stat option. A layer that names none runs its geom’s default stat, which is identity (draw the data as-is) for every built-in geom.

import { stat } from '@graphysdk/react';

geom.line({ stat: stat.smooth({ method: 'linear' }) });

Available stats

Stat	Result
`stat.identity()` (default)	The data unchanged
`stat.count()`	The number of observations per x-value, per group
`stat.sum()`	The total of `y` per x-value, per group
`stat.mean()`	The mean of `y` across the whole layer, as a single observation
`stat.summary({ interval? })`	The mean or median of `y` per x-value, per group, with an optional interval around it
`stat.smooth({ method })`	A fitted regression curve through the points

count, sum and summary group by x plus the layer’s grouping variables, so the groups a reader compares stay separate. mean reduces the layer to one observation, which is why it pairs with geom.rule() rather than a bar or a line. count computes y for you; mapping y alongside it is a CONFLICTING_STAT_MAPPING error. sum, mean, summary and smooth need a numeric y; a non-numeric one is an INCOMPATIBLE_TYPE error. Every stat also has a string shorthand, so geom.bar({ stat: 'count' }) is the same as geom.bar({ stat: stat.count() }). The names are 'identity', 'count', 'smooth', 'mean', 'sum' and 'summary'.

Trendlines with `smooth`

The smooth stat fits a regression through a layer’s points. Add it to a second geom.line() layer over the raw data:

pipe(
  createSpec({ x: 'date', y: 'sales' }),
  geom.point(), // the raw points
  geom.line({ stat: stat.smooth({ method: 'linear' }) }), // the trend
  scale.x(),
  scale.y()
);

method selects the regression family:

default:"linear"

The regression method to fit. The object builder asks for it; the 'smooth' string shorthand takes the default.

number

default:"3"

Polynomial order. Only used when method: 'polynomial'.

number

default:"0.3"

Smoothing bandwidth. Only used when method: 'loess'.

stat.smooth({ method: 'polynomial', order: 4 });
stat.smooth({ method: 'loess', bandwidth: 0.5 });

A mean reference line

stat.mean() reduces the layer to one observation, which is what a rule needs. Pair the two to draw a horizontal line at the layer’s average:

pipe(
  createSpec({ x: 'month', y: 'revenue' }),
  geom.bar(),
  geom.rule({ stat: stat.mean() }), // a line at the mean revenue
  scale.x(),
  scale.y()
);

Estimates and intervals with `summary`

The summary stat reduces y to one observation per x-value and group: an estimate, and an interval around it if you ask for one. The estimate is mapped to y and the interval’s ends to lower and upper, which is what a geom drawing an interval reads.

pipe(
  createSpec({ x: 'treatment', y: 'recoveryDays', color: 'ageBand' }),
  geom.bar({ stat: stat.summary() }), // the mean per treatment and age band
  scale.x(),
  scale.y()
);

'mean' | 'median'

default:"mean"

The value each x-value and group reduces to.

'stderr' | 'stdev' | 'ci' | 'iqr' | 'range'

The interval around the estimate. It has no default: leave it out and the stat computes the estimate alone, so a chart that draws an interval always says which one it is.

'stderr': the mean ± mult standard errors
'stdev': the mean ± mult standard deviations
'ci': a level confidence interval for the mean, from Student’s t distribution
'iqr': the first to the third quartile
'range': the smallest value to the largest

'stderr', 'stdev' and 'ci' describe a mean, so they need estimate: 'mean'. 'iqr' describes a median, so it needs estimate: 'median'.

number

default:"0.95"

The confidence level, between 0 and 1. Only used with interval: 'ci'.

number

default:"1"

How many standard errors or deviations each end sits from the mean. Only used with interval: 'stderr' or 'stdev'.

stat.summary({ interval: 'ci', level: 0.9 });
stat.summary({ interval: 'stderr', mult: 2 });
stat.summary({ estimate: 'median', interval: 'iqr' });

An x-value and group with a single value, or with values that are all equal, gets no interval: there is no spread to measure. A param outside its allowed values fails with INVALID_STAT_PARAM.

Setting a stat at runtime

Two commands reach the stat:

Command	Params	What it does
`SetLayerStatCommand`	`layerId?`, `stat` (a name such as `'count'`, an object such as `stat.count()`, or a plugin stat)	Sets one layer’s stat
`SetStatLineCommand`	`line: 'none' \| 'trend' \| 'average'`, `layerId?`, `method?`, `group?`, `label?`, `removedLayer?`	The switch behind “show a trendline” and “show an average”; swapping one for the other is one undo entry

Custom stats

A plugin can contribute its own stat: a Stat subclass registered through plugins, which gets a typed builder beside the built-ins. Its spec is only { type }, so it reads any settings from the layer’s params. A custom geom can also declare one as its defaultStat; its layers then summarize without naming it, and registering the geom registers the stat. See a summary is a stat for writing one, and Extending for registration.

Transforms — reshape data before it reaches a stat
Reference lines — the rules stat.mean() draws
Geoms & layers — where the stat option lives

Get Started

Core concepts

Chart types

Themes

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Available stats

Trendlines with `smooth`

A mean reference line

Estimates and intervals with `summary`

Setting a stat at runtime

Custom stats

Next

​Available stats

​Trendlines with smooth

​A mean reference line

​Estimates and intervals with summary

​Setting a stat at runtime

​Custom stats

​Next

Available stats

Trendlines with `smooth`

A mean reference line

Estimates and intervals with `summary`

Setting a stat at runtime

Custom stats

Next