src/render/line-model.ts

Functions

Imports

It imports src/render/data.ts, src/render/datum.ts, src/render/figure.ts, src/render/series.ts. Imported by src/lite/area.ts, src/lite/line.ts, src/lite/series.ts, src/plot/line.ts.

Source

1/**
2 * Everything about a line or area chart except the drawing: reading and checking the rows, the
3 * forecast split, hover text, keys and the data table. Shared by the Observable Plot renderer
4 * (`enarratio/plot`) and the light one (`enarratio/lite`).
5 */
6
7import {
8  calendarDates,
9  DAY,
10  defaultFormat,
11  domainOf,
12  type KeysOfType,
13  markKey,
14  maxOf,
15  minOf,
16  readDate,
17  readLabel,
18  readNumber,
19  readNumberOrNull,
20} from "./data.js";
21import type { MarkDatum } from "./datum.js";
22import {
23  type FigureOptions,
24  figure,
25  type ScaleDescription,
26  type SeriesColor,
27  validateFigure,
28} from "./figure.js";
29import { planSeries, type SeriesPlan } from "./series.js";
30
31/** A horizontal line across the chart at a value: a threshold, a limit, a target. */
32export interface ReferenceLine {
33  readonly y: number;
34  readonly label: string;
35}
36
37/** A vertical line at an x position: a deploy, an intervention, an outbreak declared. */
38export interface EventMarker {
39  readonly x: number | Date | string;
40  readonly label: string;
41}
42
43/** Options shared by `lineChart` and `areaChart`. */
44export interface SeriesChartOptions<T extends object> extends FigureOptions {
45  readonly data: readonly T[];
46  /**
47   * The field along the x axis: dates or numbers. Dates are Date objects or ISO 8601 strings;
48   * epoch milliseconds are numbers, so they need `xType: "time"`. Dates are instants in UTC,
49   * except that when every Date falls at local midnight they are read as calendar dates in the
50   * local time zone, so `new Date(2025, 0, 6)` is 6 January wherever the server runs (A3).
51   */
52  readonly x: KeysOfType<T, number | Date | string>;
53  /** The field for the value. `null` or a missing value is a gap, never zero. */
54  readonly y: KeysOfType<T, number | null | undefined>;
55  /** A field naming the series each row belongs to. */
56  readonly series?: KeysOfType<T, string>;
57  /**
58   * Whether x is time or a number. Inferred from the first row: numbers are linear, Dates and
59   * strings are time.
60   */
61  readonly xType?: "time" | "linear";
62  /** Every series in display and color order. Without it, first-seen order. */
63  readonly seriesDomain?: readonly string[];
64  /**
65   * Color overrides by series name. A chart without `series` has one series, named by `yLabel`
66   * (or "Value" when the y label is hidden).
67   */
68  readonly colors?: Readonly<Record<string, SeriesColor>>;
69  /** The x axis label; defaults to the field name; `null` hides it. */
70  readonly xLabel?: string | null;
71  /** The y axis label; defaults to the field name; `null` hides it. */
72  readonly yLabel?: string | null;
73  /** Formats values in hover details and the data table. */
74  readonly formatValue?: (value: number) => string;
75  /**
76   * Formats x values in hover details and the data table. Dates default to YYYY-MM-DD, with the
77   * UTC time added when any value falls within a day; years print without a thousands separator.
78   */
79  readonly formatX?: (value: number | Date) => string;
80  /** Horizontal reference lines, each labelled on the chart. */
81  readonly references?: readonly ReferenceLine[];
82  /** Vertical event markers, each labelled on the chart. */
83  readonly markers?: readonly EventMarker[];
84}
85
86/**
87 * A shaded band around each series' line, such as a forecast interval or a confidence interval,
88 * from two fields the caller computed. Enarratio draws bounds; it does not estimate them.
89 */
90export interface LineBand<T extends object> {
91  /** The field for the band's lower bound at each x. `null` leaves a gap, with `upper`. */
92  readonly lower: KeysOfType<T, number | null | undefined>;
93  /** The field for the band's upper bound; never below `lower`. */
94  readonly upper: KeysOfType<T, number | null | undefined>;
95  /**
96   * What the band is, e.g. "95% interval". It names the band's data table columns ("95%
97   * interval, lower") and its hover details; without it they say "lower bound" and "upper bound".
98   */
99  readonly label?: string;
100}
101
102/** Options for `lineChart`. */
103export interface LineChartOptions<T extends object> extends SeriesChartOptions<T> {
104  /**
105   * A shaded band around each line, from `lower` and `upper` fields (a forecast interval, a
106   * confidence interval). Drawn in the series' color, behind the line, and carried in the data
107   * table as two columns per series. Every row has both bounds or neither.
108   */
109  readonly band?: LineBand<T>;
110  /**
111   * The x after which the data are forecast: the line is dashed from here on, points are drawn
112   * hollow, a labelled rule marks the boundary, and the data table marks the rows after it
113   * (those with x greater than this). Must lie within the data's x range, before its last value.
114   * The forecast itself is computed by the caller.
115   */
116  readonly forecastFrom?: number | Date | string;
117  /** The label on the forecast boundary (default "Forecast"). */
118  readonly forecastLabel?: string;
119  /** Show a dot at every value (default: only when there are 30 or fewer per series). */
120  readonly points?: boolean;
121  /** Label each series at the end of its line as well as in the legend. */
122  readonly directLabels?: boolean;
123  /**
124   * Use a logarithmic y axis, for values spanning orders of magnitude. Every value must then be
125   * above zero; a zero or negative value throws rather than vanishing from the line (F2).
126   */
127  readonly yType?: "linear" | "log";
128  /** Include zero on the y axis (default true, except on a log axis). */
129  readonly zero?: boolean;
130}
131
132/** One row of a line or area chart. */
133export interface Point {
134  readonly x: number | Date;
135  /** The x value as a number (epoch milliseconds for time), which identifies the row. */
136  readonly at: number;
137  readonly xText: string;
138  readonly series: string;
139  readonly value: number | null;
140  readonly lower: number | null;
141  readonly upper: number | null;
142  /** Whether the row comes after `forecastFrom`. */
143  readonly forecast: boolean;
144  /** The x value's rank among all x values, for keyboard order. */
145  column: number;
146  readonly row: number;
147}
148
149const pad = (n: number): string => String(n).padStart(2, "0");
150const isoDate = (d: Date): string => d.toISOString().slice(0, 10);
151const isoDateTime = (d: Date): string =>
152  `${isoDate(d)} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())}${d.getUTCSeconds() ? `:${pad(d.getUTCSeconds())}` : ""} UTC`;
153
154/** Whether numbers look like years, which print without a thousands separator (F4). */
155const isYears = (values: readonly number[]): boolean =>
156  values.length > 0 && values.every((v) => Number.isInteger(v) && v >= 1000 && v <= 2999);
157
158/** About six whole-year ticks between two years. */
159function yearTicks(from: number, to: number): number[] {
160  const span = Math.max(1, to - from);
161  const step = [1, 2, 5, 10, 20, 50, 100].find((s) => span / s <= 6) ?? 100;
162  const ticks: number[] = [];
163  for (let t = Math.ceil(from / step) * step; t <= to; t += step) ticks.push(t);
164  return ticks;
165}
166
167/** A line or area chart's rows, read and checked, with what its axes and table need. */
168export interface Prepared {
169  readonly points: Point[];
170  readonly seriesNames: string[];
171  readonly time: boolean;
172  readonly years: boolean;
173  readonly format: (value: number) => string;
174  readonly xLabel: string | null;
175  readonly yLabel: string | null;
176  /** `forecastFrom` as a number (epoch milliseconds for time), when given. */
177  readonly forecastAt?: number;
178  readonly band?: { readonly lower: string; readonly upper: string; readonly label?: string };
179}
180
181type Forecastable<T extends object> = SeriesChartOptions<T> &
182  Partial<Pick<LineChartOptions<T>, "band" | "forecastFrom">>;
183
184/** Reads and checks the rows shared by line and area charts. */
185function prepare<T extends object>(kind: string, options: Forecastable<T>): Prepared {
186  const { data, x, y, series } = options;
187  validateFigure(kind, options);
188  if (data.length === 0) throw new Error(`${kind}: data is empty`);
189  const first: unknown = (data[0] as Record<string, unknown>)[x];
190  const time = options.xType ? options.xType === "time" : typeof first !== "number";
191  const format = options.formatValue ?? defaultFormat;
192  const yLabel = options.yLabel === undefined ? y : options.yLabel;
193  const xLabel = options.xLabel === undefined ? x : options.xLabel;
194  const sole = yLabel ?? "Value";
195
196  // forecastFrom is read with the data, so calendar dates treat both the same way.
197  const given = options.forecastFrom;
198  const read: (number | Date)[] = time
199    ? data.map((row, i) => readDate(kind, row, x, i))
200    : data.map((row, i) => readNumber(kind, row, x, i));
201  if (given !== undefined) {
202    read.push(
203      time
204        ? readDate(kind, { forecastFrom: given }, "forecastFrom", 0)
205        : readNumber(kind, { forecastFrom: given }, "forecastFrom", 0),
206    );
207  }
208  const all = time ? calendarDates(read as Date[]) : read;
209  const forecastBoundary = given !== undefined ? Number(all[all.length - 1]) : undefined;
210  const xs = given !== undefined ? all.slice(0, -1) : all;
211  const numbers = xs.map(Number);
212  if (forecastBoundary !== undefined) {
213    if (!(forecastBoundary >= minOf(numbers) && forecastBoundary < maxOf(numbers))) {
214      throw new Error(
215        `${kind}: forecastFrom must lie within the x range and before its last value, so that some rows are forecast`,
216      );
217    }
218  }
219  const years = !time && isYears(numbers);
220  const subDaily = time && numbers.some((n) => n % DAY !== 0);
221  const formatX = (v: number | Date): string => {
222    if (options.formatX) return options.formatX(v);
223    if (v instanceof Date) return subDaily ? isoDateTime(v) : isoDate(v);
224    return years ? String(v) : defaultFormat(v);
225  };
226
227  const seriesOf = (row: T, i: number): string =>
228    series === undefined ? sole : readLabel(kind, row, series, i);
229  const seriesNames =
230    series === undefined
231      ? [sole]
232      : domainOf(
233          kind,
234          series,
235          data.map((row, i) => seriesOf(row, i)),
236          options.seriesDomain,
237        );
238  const rowOf = new Map(seriesNames.map((name, i) => [name, i]));
239  const band = options.band;
240  // Rows are identified by the x value itself, not its text, so hourly data with a daily label
241  // (or any coarse formatX) is still distinct (F3).
242  const seen = new Set<string>();
243  const points = data.map((row, i): Point => {
244    const xv = xs[i] as number | Date;
245    const at = Number(xv);
246    const name = seriesOf(row, i);
247    const lower = band ? readNumberOrNull(kind, row, band.lower, i) : null;
248    const upper = band ? readNumberOrNull(kind, row, band.upper, i) : null;
249    if (band && (lower === null) !== (upper === null)) {
250      throw new Error(
251        `${kind}: row ${i + 1} has only one of the band's "${band.lower}" and "${band.upper}"; give both or neither`,
252      );
253    }
254    if (lower !== null && upper !== null && lower > upper) {
255      throw new Error(
256        `${kind}: row ${i + 1} band lower bound ${lower} is above its upper bound ${upper}`,
257      );
258    }
259    const point: Point = {
260      x: xv,
261      at,
262      xText: formatX(xv),
263      series: name,
264      value: readNumberOrNull(kind, row, y, i),
265      lower,
266      upper,
267      forecast: forecastBoundary !== undefined && at > forecastBoundary,
268      column: 0,
269      row: rowOf.get(name) ?? 0,
270    };
271    const id = markKey(at, name);
272    if (seen.has(id)) {
273      throw new Error(`${kind}: two rows for x ${point.xText} in series "${name}"`);
274    }
275    seen.add(id);
276    return point;
277  });
278  if (points.every((p) => p.value === null)) throw new Error(`${kind}: every value is empty`);
279  points.sort((a, b) => a.at - b.at || a.row - b.row);
280  const ranks = new Map([...new Set(points.map((p) => p.at))].map((at, i) => [at, i]));
281  for (const p of points) p.column = ranks.get(p.at) ?? 0;
282  return {
283    points,
284    seriesNames,
285    time,
286    years,
287    format,
288    xLabel,
289    yLabel,
290    ...(forecastBoundary !== undefined ? { forecastAt: forecastBoundary } : {}),
291    ...(band ? { band } : {}),
292  };
293}
294
295/** A marker's position read like the data's x values, with its label. */
296export interface MarkerPoint {
297  readonly x: number | Date;
298  readonly label: string;
299}
300
301/** Reads the event markers' positions the way the chart reads x. */
302function markerPoints(
303  options: Pick<SeriesChartOptions<object>, "markers">,
304  time: boolean,
305  kind: string,
306): MarkerPoint[] {
307  return (options.markers ?? []).map((m, i) => ({
308    x: time ? readDate(kind, m, "x", i) : readNumber(kind, m, "x", i),
309    label: m.label,
310  }));
311}
312
313/** The data table column for one bound of a band, e.g. "Berlin 95% interval, lower". */
314function boundColumn(prepared: Prepared, series: string, multi: boolean, bound: string): string {
315  const what = prepared.band?.label ? `${prepared.band.label}, ${bound}` : `${bound} bound`;
316  if (multi) return `${series} ${what}`;
317  return `${what.charAt(0).toUpperCase()}${what.slice(1)}`;
318}
319
320function table(prepared: Prepared, xColumn: string, multi: boolean) {
321  const rowsByX = new Map<number, string>();
322  for (const p of prepared.points) if (!rowsByX.has(p.at)) rowsByX.set(p.at, p.xText);
323  const cell = new Map(prepared.points.map((p) => [markKey(p.at, p.series), p]));
324  const bounds = prepared.band
325    ? prepared.seriesNames.flatMap((s) => [
326        { series: s, which: "lower" as const, column: boundColumn(prepared, s, multi, "lower") },
327        { series: s, which: "upper" as const, column: boundColumn(prepared, s, multi, "upper") },
328      ])
329    : [];
330  const forecast = prepared.forecastAt !== undefined;
331  return {
332    columns: [
333      xColumn,
334      ...prepared.seriesNames,
335      ...bounds.map((b) => b.column),
336      ...(forecast ? ["Forecast"] : []),
337    ],
338    rows: [...rowsByX].map(([at, text]) => [
339      text,
340      ...prepared.seriesNames.map((s) => {
341        const v = cell.get(markKey(at, s))?.value;
342        return v === null || v === undefined ? "" : prepared.format(v);
343      }),
344      ...bounds.map((b) => {
345        const v = cell.get(markKey(at, b.series))?.[b.which];
346        return v === null || v === undefined ? "" : prepared.format(v);
347      }),
348      ...(forecast ? [forecastAt(prepared, at) ? "Yes" : ""] : []),
349    ]),
350  };
351}
352
353/** Whether an x value comes after the forecast boundary. */
354function forecastAt(prepared: Prepared, at: number): boolean {
355  return prepared.forecastAt !== undefined && at > prepared.forecastAt;
356}
357
358function describePoint(prepared: Prepared, multi: boolean, xColumn: string) {
359  return (p: Point): string => {
360    const notes: string[] = [];
361    if (p.forecast) notes.push("forecast");
362    if (prepared.band && p.lower !== null && p.upper !== null) {
363      notes.push(
364        `${prepared.band.label ?? "range"} ${prepared.format(p.lower)} to ${prepared.format(p.upper)}`,
365      );
366    }
367    return `${multi ? `${p.series}, ` : ""}${xColumn} ${p.xText}: ${p.value === null ? "no data" : prepared.format(p.value)}${notes.length > 0 ? ` (${notes.join("; ")})` : ""}`;
368  };
369}
370
371function datum(p: Point, x: string, series: string | undefined): MarkDatum {
372  const multi = series !== undefined;
373  return {
374    key: markKey(p.at, p.series),
375    filter: multi ? { field: series, value: p.series } : { field: x, value: p.xText },
376    x: p.xText,
377    ...(multi ? { series: p.series } : {}),
378    column: p.column,
379    row: p.row,
380  };
381}
382
383/** What line and area charts share once read: rows, colors, hover text, keys and the figure. */
384export interface SeriesModel {
385  readonly prepared: Prepared;
386  readonly plan: SeriesPlan;
387  /** Whether the chart has a `series` field (and so a legend). */
388  readonly multi: boolean;
389  /** Whole-year x ticks, when x holds years. */
390  readonly yearTicks: number[] | undefined;
391  readonly markers: readonly MarkerPoint[];
392  describe(p: Point): string;
393  datum(p: Point): MarkDatum;
394  /** Wraps the drawn SVG in the figure, with its legend and data table. */
395  figure(svg: string, x: ScaleDescription | undefined): string;
396}
397
398function seriesModel<T extends object>(
399  kind: string,
400  figureKind: string,
401  options: Forecastable<T>,
402  prepared: Prepared,
403  check?: () => void,
404): SeriesModel {
405  const plan = planSeries(kind, prepared.seriesNames, options.colors);
406  check?.();
407  const multi = options.series !== undefined;
408  const xColumn = prepared.xLabel ?? options.x;
409  const ats = prepared.points.map((p) => p.at);
410  return {
411    prepared,
412    plan,
413    multi,
414    yearTicks: prepared.years ? yearTicks(minOf(ats), maxOf(ats)) : undefined,
415    markers: markerPoints(options, prepared.time, kind),
416    describe: describePoint(prepared, multi, xColumn),
417    datum: (p) => datum(p, options.x, options.series),
418    figure: (svg, x) =>
419      figure(options, {
420        kind: figureKind,
421        svg,
422        ...(x ? { x } : {}),
423        legend: multi ? plan.legend : [],
424        ...(multi && options.series ? { seriesField: options.series } : {}),
425        slotColors: plan.slotColors,
426        table: table(prepared, xColumn, multi),
427      }),
428  };
429}
430
431const LINE = "lineChart";
432
433/** A line chart read from its options. */
434export interface LineModel extends SeriesModel {
435  readonly log: boolean;
436  /** The rows with a value: the drawn points. */
437  readonly present: readonly Point[];
438  /** Whether points are drawn, or only there to hover. */
439  readonly showPoints: boolean;
440  /** The rows drawn solid: all of them, or those up to the forecast boundary. */
441  readonly solid: readonly Point[];
442  /** The rows drawn dashed, after the forecast boundary; empty without a forecast. */
443  readonly dashed: readonly Point[];
444  /** The forecast boundary as the axis reads it, with its label. */
445  readonly forecast: { readonly x: number | Date; readonly label: string } | undefined;
446  readonly directLabels: boolean;
447}
448
449/** Reads and checks a line chart's options. Throws on anything it cannot draw. */
450export function lineModel<T extends object>(options: LineChartOptions<T>): LineModel {
451  const prepared = prepare(LINE, options);
452  const { points, seriesNames, time } = prepared;
453  const log = options.yType === "log";
454  if (log) {
455    const bad = points.find((p) => p.value !== null && p.value <= 0);
456    if (bad) {
457      throw new Error(
458        `${LINE}: ${bad.series} at ${bad.xText} is ${bad.value}, which a log axis cannot show`,
459      );
460    }
461  }
462  if (log) {
463    const low = points.find((p) => p.lower !== null && p.lower <= 0);
464    if (low) {
465      throw new Error(
466        `${LINE}: the band's lower bound for ${low.series} at ${low.xText} is ${low.lower}, which a log axis cannot show`,
467      );
468    }
469  }
470  const base = seriesModel(LINE, "line", options, prepared);
471  const present = points.filter((p) => p.value !== null);
472  const perSeries = present.length / seriesNames.length;
473  const boundary = prepared.forecastAt;
474  // Each series' dashed stretch starts at its last point on or before the boundary, so the line
475  // stays joined where the data change from observed to forecast.
476  const dashed =
477    boundary === undefined
478      ? []
479      : points
480          .filter((p) => p.at > boundary)
481          .concat(
482            seriesNames.flatMap((name) => {
483              const own = points.filter((p) => p.series === name && p.at <= boundary);
484              const last = own[own.length - 1];
485              return last ? [last] : [];
486            }),
487          )
488          .sort((a, b) => a.at - b.at || a.row - b.row);
489  return {
490    ...base,
491    log,
492    present,
493    showPoints: options.points ?? perSeries <= 30,
494    solid: boundary === undefined ? points : points.filter((p) => p.at <= boundary),
495    dashed,
496    forecast:
497      boundary === undefined
498        ? undefined
499        : {
500            x: time ? new Date(boundary) : boundary,
501            label: options.forecastLabel ?? "Forecast",
502          },
503    directLabels: options.directLabels === true && base.multi,
504  };
505}
506
507const AREA = "areaChart";
508
509/**
510 * The fill opacity of an area chart's bands. Light, with a line along each band's top edge,
511 * so the gridlines show through and a stack reads as layers rather than one solid block.
512 */
513export const AREA_OPACITY = 0.3;
514
515/** Reads and checks an area chart's options. Throws on anything it cannot draw. */
516export function areaModel<T extends object>(options: SeriesChartOptions<T>): SeriesModel {
517  const prepared = prepare(AREA, options);
518  return seriesModel(AREA, "area", options, prepared, () => {
519    for (const p of prepared.points) {
520      if (p.value !== null && p.value < 0) {
521        throw new Error(
522          `${AREA}: stacked areas need values of zero or more; ${p.series} at ${p.xText} is ${p.value}`,
523        );
524      }
525    }
526  });
527}