src/lite/series.ts

Functions

Imports

It imports src/lite/axis.ts, src/lite/scale.ts, src/lite/svg.ts, src/render/datum.ts, src/render/figure.ts, src/render/line-model.ts. Imported by src/lite/area.ts, src/lite/line.ts.

Source

1/** What the light line and area charts share: their scales, axes, annotations and paths. */
2
3import { datumAttributes } from "../render/datum.js";
4import type { ScaleDescription } from "../render/figure.js";
5import type { Point, SeriesChartOptions, SeriesModel } from "../render/line-model.js";
6import { axisLabel, axisTickLabels, axisTicks, type Frame, grid, type Tick } from "./axis.js";
7import {
8  type Continuous,
9  continuous,
10  linearTickFormat,
11  logTickFormat,
12  logTicks,
13  niceLinear,
14  niceLog,
15  type Pair,
16  ticks,
17  timeTickLabels,
18  timeTicks,
19} from "./scale.js";
20import { type Attrs, el, num, text, textElement, translate } from "./svg.js";
21
22/** A group of labels, or nothing when no label has text, as Plot skips an empty mark. */
23function labels(attrs: Attrs, items: string[]): string {
24  return items.length === 0 ? "" : el("g", attrs, items.join(""));
25}
26
27/** The smallest and largest finite numbers in `values`, or undefined when there are none. */
28function extent(values: Iterable<number | null>): Pair | undefined {
29  let lo = Number.POSITIVE_INFINITY;
30  let hi = Number.NEGATIVE_INFINITY;
31  for (const v of values) {
32    if (v === null || !Number.isFinite(v)) continue;
33    if (v < lo) lo = v;
34    if (v > hi) hi = v;
35  }
36  return lo <= hi ? [lo, hi] : undefined;
37}
38
39/** The scales and axes of a line or area chart. */
40export interface SeriesFrame {
41  readonly frame: Frame;
42  readonly x: Continuous;
43  readonly y: Continuous;
44  /** The axes and grid, drawn before the marks. */
45  readonly axes: string;
46  /** The x scale as the enhancement layer reads it. */
47  readonly xScale: ScaleDescription;
48}
49
50/**
51 * Lays out a line or area chart: an x scale over every x the chart draws, without rounding (as
52 * Plot leaves it), and a y scale made round, with zero unless told otherwise.
53 */
54export function seriesFrame(
55  model: SeriesModel,
56  frame: Frame,
57  xs: Iterable<number>,
58  ys: Iterable<number | null>,
59  y: { readonly log: boolean; readonly zero: boolean },
60): SeriesFrame {
61  const { prepared } = model;
62  const { width, height, marginTop, marginRight, marginBottom, marginLeft } = frame;
63  const xDomain = extent(xs) ?? [0, 1];
64  const xRange: Pair = [marginLeft, width - marginRight];
65  const x = continuous(prepared.time ? "utc" : "linear", xDomain, xRange);
66
67  const values = [...ys].filter((v): v is number => v !== null && (!y.log || v > 0));
68  let yDomain: Pair = extent(values) ?? (y.log ? [1, 10] : [0, 1]);
69  if (y.zero && (yDomain[0] > 0 || yDomain[1] < 0)) {
70    yDomain = yDomain[0] > 0 ? [0, yDomain[1]] : [yDomain[0], 0];
71  }
72  yDomain = y.log ? niceLog(yDomain) : niceLinear(yDomain);
73  const yScale = continuous(y.log ? "log" : "linear", yDomain, [height - marginBottom, marginTop]);
74
75  const yCount = (height - marginBottom - marginTop) / 35;
76  const yAt = y.log ? logTicks(yDomain, yCount) : ticks(yDomain[0], yDomain[1], yCount);
77  const yFormat = y.log ? logTickFormat(yDomain, yCount) : linearTickFormat(yDomain, yCount);
78  const yTicks: Tick[] = yAt.map((t) => ({ at: yScale(t), label: yFormat(t) }));
79
80  const xCount = (xRange[1] - xRange[0]) / 80;
81  let xTicks: Tick[];
82  if (model.yearTicks) {
83    xTicks = model.yearTicks.map((t) => ({ at: x(t), label: String(t) }));
84  } else if (prepared.time) {
85    const at = timeTicks(xDomain[0], xDomain[1], xCount);
86    const labels = timeTickLabels(at);
87    xTicks = at.map((t, i) => ({ at: x(t), label: labels[i] ?? "" }));
88  } else {
89    const format = linearTickFormat(xDomain, xCount);
90    xTicks = ticks(xDomain[0], xDomain[1], xCount).map((t) => ({ at: x(t), label: format(t) }));
91  }
92
93  const axes = [
94    grid(
95      "y",
96      yTicks.map((t) => t.at),
97      frame,
98    ),
99    axisTicks(
100      "y",
101      yTicks.map((t) => t.at),
102      frame,
103    ),
104    axisTickLabels("y", yTicks, frame, { tabular: true }),
105    axisLabel("y", prepared.yLabel, frame),
106    axisTicks(
107      "x",
108      xTicks.map((t) => t.at),
109      frame,
110    ),
111    axisTickLabels("x", xTicks, frame, { tabular: true }),
112    axisLabel("x", prepared.xLabel, frame),
113  ].join("");
114
115  return {
116    frame,
117    x,
118    y: yScale,
119    axes,
120    xScale: { type: x.type, domain: [...xDomain], range: [...xRange] },
121  };
122}
123
124/**
125 * A path point. d3-shape writes path coordinates to three decimals, and the Plot renderer then
126 * rounds to two, so a path rounds twice: 123.3846 becomes 123.385, then 123.39.
127 */
128const xy = (x: number, y: number): string =>
129  `${num(Math.round(x * 1000) / 1000)},${num(Math.round(y * 1000) / 1000)}`;
130
131/**
132 * Splits rows into runs of defined values, as Plot does for lines and areas: rows before the
133 * first defined value are dropped, and an undefined value ends a run.
134 */
135function runs<P>(rows: readonly P[], defined: (p: P) => boolean): P[][] {
136  const out: P[][] = [];
137  let current: P[] | undefined;
138  for (const p of rows) {
139    if (defined(p)) {
140      if (!current) {
141        current = [];
142        out.push(current);
143      }
144      current.push(p);
145    } else current = undefined;
146  }
147  return out;
148}
149
150/** Rows grouped by series, in the order each series first appears. */
151export function bySeries<P extends { readonly series: string }>(rows: readonly P[]): P[][] {
152  const groups = new Map<string, P[]>();
153  for (const p of rows) {
154    const group = groups.get(p.series);
155    if (group) group.push(p);
156    else groups.set(p.series, [p]);
157  }
158  return [...groups.values()];
159}
160
161/** A line through each run of defined points; a lone point closes on itself. */
162export function linePath<P>(
163  rows: readonly P[],
164  defined: (p: P) => boolean,
165  at: (p: P) => [number, number],
166): string | undefined {
167  const parts = runs(rows, defined).map(
168    (run) =>
169      run.map((p, i) => `${i === 0 ? "M" : "L"}${xy(...at(p))}`).join("") +
170      (run.length === 1 ? "Z" : ""),
171  );
172  return parts.length === 0 ? undefined : parts.join("");
173}
174
175/** An area over each run of defined points: along the top, back along the base, closed. */
176export function areaPath<P>(
177  rows: readonly P[],
178  defined: (p: P) => boolean,
179  top: (p: P) => [number, number],
180  base: (p: P) => [number, number],
181): string | undefined {
182  const parts = runs(rows, defined).map((run) => {
183    const forward = run.map((p, i) => `${i === 0 ? "M" : "L"}${xy(...top(p))}`).join("");
184    const back = [...run]
185      .reverse()
186      .map((p) => `L${xy(...base(p))}`)
187      .join("");
188    return `${forward}${back}Z`;
189  });
190  return parts.length === 0 ? undefined : parts.join("");
191}
192
193/** A group of one path per series. */
194export function pathGroup(
195  name: string,
196  styles: Attrs,
197  paths: readonly { readonly d: string | undefined; readonly attrs: Attrs }[],
198): string {
199  const drawn = paths.filter((p) => p.d !== undefined);
200  if (drawn.length === 0) return "";
201  return el(
202    "g",
203    { "data-enarratio-mark": name, ...styles },
204    drawn.map((p) => el("path", { d: p.d, ...p.attrs })).join(""),
205  );
206}
207
208/** Keyed points with hover details, drawn as circles. */
209export function dots(
210  model: SeriesModel,
211  points: readonly Point[],
212  styles: Attrs,
213  circle: (p: Point) => Attrs,
214): string {
215  return el(
216    "g",
217    { "data-enarratio-mark": "dot", ...styles },
218    points
219      .map((p) =>
220        el(
221          "circle",
222          { ...circle(p), ...Object.fromEntries(datumAttributes(model.datum(p))) },
223          el("title", {}, text(model.describe(p))),
224        ),
225      )
226      .join(""),
227  );
228}
229
230/** Reference lines across the frame, and markers down it, each labelled, as Plot draws them. */
231export function annotations(
232  options: Pick<SeriesChartOptions<object>, "references">,
233  model: SeriesModel,
234  layout: SeriesFrame,
235): string {
236  const { frame, x, y } = layout;
237  const { width, marginRight, marginLeft } = frame;
238  let out = "";
239  const references = options.references ?? [];
240  if (references.length > 0) {
241    out += el(
242      "g",
243      { "data-enarratio-mark": "rule", stroke: "currentColor", "stroke-dasharray": "4,3" },
244      references
245        .map((r) => el("line", { x1: marginLeft, x2: width - marginRight, y1: y(r.y), y2: y(r.y) }))
246        .join(""),
247    );
248    out += labels(
249      { "data-enarratio-mark": "text", "text-anchor": "end", transform: translate(0, -6) },
250      references
251        .filter((r) => r.label !== "")
252        .map((r) =>
253          textElement({ transform: translate(width - marginRight, y(r.y)) }, r.label, "middle"),
254        ),
255    );
256  }
257  out += verticalRules(
258    model.markers.map((m) => ({ at: x(Number(m.x)), label: m.label })),
259    frame,
260  );
261  return out;
262}
263
264/** Labelled vertical rules (event markers, the forecast boundary), from the top of the frame. */
265export function verticalRules(rules: readonly Tick[], frame: Frame): string {
266  if (rules.length === 0) return "";
267  const { marginTop, height, marginBottom } = frame;
268  return (
269    el(
270      "g",
271      { "data-enarratio-mark": "rule", stroke: "currentColor", "stroke-dasharray": "2,3" },
272      rules
273        .map((r) => el("line", { x1: r.at, x2: r.at, y1: marginTop, y2: height - marginBottom }))
274        .join(""),
275    ) +
276    labels(
277      { "data-enarratio-mark": "text", "text-anchor": "start", transform: translate(4, 0) },
278      rules
279        .filter((r) => r.label !== "")
280        .map((r) => textElement({ transform: translate(r.at, marginTop) }, r.label, "top")),
281    )
282  );
283}