Charts

Bar, line, area, scatter, pie, histogram, heatmap, radar and sparkline charts.

import { ... } from 'cseen/charts';

Functions

areas

An area chart: overlapping filled areas, or stacked with stack: true.

function areas(o?: Omit<ChartOpts, 'type'>): Chart

Parameter	Type
o?	Omit<ChartOpts, 'type'>

Returns Chart

Example

import { Scene } from 'cseen';
import { areas } from 'cseen/charts';

const s = new Scene({ view: 'front' });
s.add(areas({ data: { A: [3, 5, 4, 7, 6, 8], B: [2, 3, 5, 4, 6, 5] }, stack: true }));

Run it in the playground →

bars

A bar chart. data can be numbers, several series, label and value pairs, or a map of series.

function bars(o?: Omit<ChartOpts, 'type'>): Chart

Parameter	Type
o?	Omit<ChartOpts, 'type'>

Returns Chart

Example

import { Scene } from 'cseen';
import { bars } from 'cseen/charts';

const s = new Scene({ view: 'front' });
s.add(bars({ data: [12, 19, 7, 15, 22, 9], labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'], title: 'Signups', labelValues: true }));

Run it in the playground →

chart

A chart. chart({ type: 'bar', data: [3, 5, 2] }), or use the shortcuts bars, lines, pie…

function chart(o?: ChartOpts): Chart

Parameter	Type
o?	ChartOpts

Returns Chart

Options: ChartOpts

donut

A pie with a hole. Takes the same options as pie.

function donut(o?: Omit<ChartOpts, 'type'>): Chart

Parameter	Type
o?	Omit<ChartOpts, 'type'>

Returns Chart

Example

import { Scene } from 'cseen';
import { donut } from 'cseen/charts';

const s = new Scene({ view: 'front' });
s.add(donut({ data: [['Done', 70], ['Open', 20], ['Blocked', 10]], labelValues: true }));

Run it in the playground →

See it in the gallery.

heatmap

A matrix coloured through the theme’s sequential ramp, or a diverging ramp for values around zero.

function heatmap(o?: Omit<ChartOpts, 'type'>): Chart

Parameter	Type
o?	Omit<ChartOpts, 'type'>

Returns Chart

Example

import { Scene } from 'cseen';
import { heatmap } from 'cseen/charts';

const s = new Scene({ view: 'front' });
s.add(heatmap({ matrix: [[1, 3, 5, 2], [4, 6, 9, 3], [7, 2, 4, 8]], rowLabels: ['Mon', 'Tue', 'Wed'], colLabels: ['9', '10', '11', '12'], labelValues: true }));

Run it in the playground →

See it in the gallery.

histogram

A histogram of raw values, binned into bins bars.

function histogram(o?: Omit<ChartOpts, 'type'>): Chart

Parameter	Type
o?	Omit<ChartOpts, 'type'>

Returns Chart

Example

import { Scene } from 'cseen';
import { histogram } from 'cseen/charts';

const s = new Scene({ view: 'front' });
s.add(histogram({ values: [1, 2, 2, 3, 3, 3, 4, 4, 5, 5, 5, 5, 6, 7, 7, 8], bins: 6, title: 'Histogram' }));

Run it in the playground →

See it in the gallery.

lines

A line chart. Several series are drawn together, joined linearly, smoothly or in steps.

function lines(o?: Omit<ChartOpts, 'type'>): Chart

Parameter	Type
o?	Omit<ChartOpts, 'type'>

Returns Chart

Example

import { Scene } from 'cseen';
import { lines } from 'cseen/charts';

const s = new Scene({ view: 'front' });
s.add(lines({ data: { Latency: [220, 180, 240, 190, 150, 170], Errors: [90, 110, 80, 60, 70, 40] }, curve: 'smooth' }));

Run it in the playground →

niceTicks

round tick values that cover [lo, hi]

function niceTicks(lo: number, hi: number, count?: number): number[]

Parameter	Type
lo	number
hi	number
count?	number

Returns number[]

pie

A pie chart of the shares in data.

function pie(o?: Omit<ChartOpts, 'type'>): Chart

Parameter	Type
o?	Omit<ChartOpts, 'type'>

Returns Chart

Example

import { Scene } from 'cseen';
import { pie } from 'cseen/charts';

const s = new Scene({ view: 'front' });
s.add(pie({ data: [['Chrome', 62], ['Safari', 20], ['Firefox', 8], ['Other', 10]], labelValues: true, legend: 'right' }));

Run it in the playground →

See it in the gallery.

radar

A radar chart: one spoke per label, one polygon per series.

function radar(o?: Omit<ChartOpts, 'type'>): Chart

Parameter	Type
o?	Omit<ChartOpts, 'type'>

Returns Chart

Example

import { Scene } from 'cseen';
import { radar } from 'cseen/charts';

const s = new Scene({ view: 'front' });
s.add(radar({ data: { Alpha: [8, 6, 7, 5, 9], Beta: [5, 8, 4, 9, 6] }, labels: ['A', 'B', 'C', 'D', 'E'] }));

Run it in the playground →

See it in the gallery.

scatter

A scatter plot. Points can carry a size r (bubbles), a value v for colour, and a series s.

function scatter(o?: Omit<ChartOpts, 'type'>): Chart

Parameter	Type
o?	Omit<ChartOpts, 'type'>

Returns Chart

Example

import { Scene } from 'cseen';
import { scatter } from 'cseen/charts';

const s = new Scene({ view: 'front' });
s.add(scatter({ points: [{ x: 1, y: 2 }, { x: 2, y: 3.5 }, { x: 3, y: 3 }, { x: 4, y: 5.2 }, { x: 5, y: 4.8 }], title: 'Scatter' }));

Run it in the playground →

See it in the gallery.

sparkline

A small line chart with no axes, the size of a word.

function sparkline(o?: Omit<ChartOpts, 'type'>): Chart

Parameter	Type
o?	Omit<ChartOpts, 'type'>

Returns Chart

Example

import { Scene } from 'cseen';
import { sparkline } from 'cseen/charts';

const s = new Scene({ view: 'front' });
s.add(sparkline({ data: [3, 5, 4, 8, 6, 9, 7, 11], size: [4, 1.4] }));

Run it in the playground →

See it in the gallery.

toTable

The table behind any form of data: the labels along the axis and one series per colour.

function toTable(data: ChartData | undefined, labels?: string[]): Table

Parameter	Type
data	ChartData
labels?	string[]

Returns Table

Classes

Chart

A chart drawn on a plane in the scene: flat on the page, standing up, or on a screen (device.put). It takes the theme’s colours and updates with them. grow (0 to 1) reveals it, and data (the numbers flattened) can be tweened to morph from one dataset to another: tween(c, { data: c.flatten(next) }).

new Chart(o?: ChartOpts): Chart

Options: ChartOpts

Extends SvgPlane.

Member	Description
o: ChartOpts
flatten(t: ChartData | Table): number[]	all the numbers of a table in one list: what the data property holds, and what you tween to
table(): Table	the current table: the original shape with the numbers from the data property, which may be mid-tween. A value that is not a finite number counts as 0, so one bad entry cannot spoil the whole drawing.
draw(W: number, H: number): string	the drawing, in svg units: W wide and H tall, origin at the top left
clipId: string	the id the line charts give their reveal clip path, unique to this chart.

Options and types

ChartData

What data can be. Every form ends up as labels and series.

type ChartData = | number[]
  | number[][]
  | Record<string, number[]>
  | { labels?: string[]; series: Series[] }
  | Array<{ label: string; value: number }>
  | Array<[string, number]>

ChartOpts

Options of chart and of the named chart factories (bars, lines, pie, and so on). Which ones apply depends on the chart type.

Extends SvgPlaneOpts.

Option	Type	Default	Description
type?	ChartType		which chart to draw, for chart; the named factories set it
data?	ChartData		bar, line, area, pie, donut, radar, sparkline
labels?	string[]		labels along the category axis
points?	Point2[]		scatter
values?	number[]		histogram: the raw values, binned for you
bins?	number		histogram: number of bins
matrix?	number[][]		heatmap
rowLabels?	string[]		heatmap: label of each row
colLabels?	string[]		heatmap: label of each column
title?	string		text above the chart
axes?	boolean | { x?: boolean; y?: boolean; grid?: boolean; xLabel?: string; yLabel?: string; }		axes and grid: true, false, or pick parts
yMin?	number		lowest value on the value axis
yMax?	number		highest value on the value axis
stack?	boolean		bars: side by side (default) or stacked. Areas and lines: overlapping (default) or stacked.
normalize?	boolean		stacked values as shares of 100%
horizontal?	boolean		bars: run left to right instead of bottom to top
curve?	'linear' | 'smooth' | 'step'		lines: how the points are joined
dots?	boolean		lines: draw a dot at each point (default true)
fill?	boolean		lines: shade the area under each line
labelValues?	boolean | ((v: number) => string)		show the values on bars, slices, points and cells (true), or format them yourself
legend?	boolean | 'top' | 'bottom' | 'right'		where to put the legend, or false
palette?	Palette		how colours are chosen. See palette below.
highlight?	string | number | (string | number)[]		series (or categories, for a single series) to show in the accent colour while the others fade to grey
hole?	number		donut hole, as a fraction of the radius
maxR?	number		scatter: biggest dot radius in svg units. Heatmap: draw the numbers.
pad?	number		extra margin inside the chart, in world units
format?	((v: number) => string)		how to print a number on the axes and as a value label (labelValues as a function takes precedence)

ChartType

The kinds of chart chart can draw.

type ChartType = 'bar' | 'line' | 'area' | 'scatter' | 'pie' | 'donut' | 'histogram' | 'heatmap' | 'radar' | 'sparkline'

Palette

Where series colours come from. The default, ‘categorical’, walks through the theme’s series colours (—c-s1 to —c-s8), which are derived from your accent. The others are built from the theme too, so no palette is tied to a particular look: ‘categorical’ distinct hues ‘sequential’ light to strong, one hue ‘diverging’ two hues around a quiet middle ‘mono’ the accent in steps or a list of roles and CSS colours, or a function (index, count) => colour.

type Palette = 'categorical' | 'sequential' | 'diverging' | 'mono' | string[] | ((i: number, n: number) => string)

Point2

A point of a scatter plot.

Option	Type	Default	Description
x	number		horizontal value
y	number		vertical value
r?	number		size, for bubbles
v?	number		value that sets the colour
s?	string | number		series index or name

Series

A named list of values, with an optional colour.

Option	Type	Default	Description
name	string		the name shown in the legend
values	number[]		one number per label
color?	string		a role (accent, s3) or any CSS colour

Table

Chart data after normalising: the labels along the axis and one series per colour.

Option	Type	Default	Description
labels	string[]		the labels along the axis
series	Series[]		one entry per colour