src/plot/scatter.ts

Functions

Imports

It imports src/render/data.ts, src/render/figure.ts, src/render/plot.ts, src/render/series.ts, src/render/size.ts. Imported by src/plot/index.ts.

Source

1import * as Plot from "@observablehq/plot";
2import { defaultFormat, domainOf, type KeysOfType, readLabel, readNumber } from "../render/data.js";
3import { type FigureOptions, figure, type SeriesColor, validateFigure } from "../render/figure.js";
4import { keyed, renderPlot } from "../render/plot.js";
5import { planSeries } from "../render/series.js";
6import { DEFAULT_WIDTH } from "../render/size.js";
7
8/** Options for {@link scatterPlot}. */
9export interface ScatterPlotOptions<T extends object> extends FigureOptions {
10  readonly data: readonly T[];
11  readonly x: KeysOfType<T, number>;
12  readonly y: KeysOfType<T, number>;
13  /** A field grouping points into colored series. */
14  readonly series?: KeysOfType<T, string>;
15  /** A field naming each point, shown in hover details and the data table. */
16  readonly label?: KeysOfType<T, string | number>;
17  readonly xType?: "linear" | "log";
18  readonly yType?: "linear" | "log";
19  /** Draw an ordinary least-squares line (per series), with its 95% confidence band. */
20  readonly regression?: boolean;
21  readonly seriesDomain?: readonly string[];
22  readonly colors?: Readonly<Record<string, SeriesColor>>;
23  readonly xLabel?: string | null;
24  readonly yLabel?: string | null;
25  readonly formatValue?: (value: number) => string;
26}
27
28interface ScatterPoint {
29  readonly key: string;
30  readonly name: string;
31  readonly x: number;
32  readonly y: number;
33  readonly series: string;
34}
35
36const KIND = "scatterPlot";
37
38/**
39 * A scatter plot of two measurements, optionally grouped into series, on linear or log axes,
40 * with an optional regression line. Series are told apart by color and by symbol shape, so the
41 * chart never relies on hue alone.
42 *
43 * @example
44 * scatterPlot({ data: isolates, x: "ct", y: "titer", yType: "log", label: "isolate", alt: "..." });
45 */
46export function scatterPlot<T extends object>(options: ScatterPlotOptions<T>): string {
47  const { data, x, y, series, label } = options;
48  validateFigure(KIND, options);
49  if (data.length === 0) throw new Error(`${KIND}: data is empty`);
50  const format = options.formatValue ?? defaultFormat;
51  const xLabel = options.xLabel === undefined ? x : options.xLabel;
52  const yLabel = options.yLabel === undefined ? y : options.yLabel;
53  const sole = "Points";
54  const seriesOf = (row: T, i: number): string =>
55    series === undefined ? sole : readLabel(KIND, row, series, i);
56  const seriesNames =
57    series === undefined
58      ? [sole]
59      : domainOf(
60          KIND,
61          series,
62          data.map((row, i) => seriesOf(row, i)),
63          options.seriesDomain,
64        );
65  const plan = planSeries(KIND, seriesNames, options.colors);
66
67  const points = data.map((row, i): ScatterPoint => {
68    const xv = readNumber(KIND, row, x, i);
69    const yv = readNumber(KIND, row, y, i);
70    for (const [axis, type, v] of [
71      ["x", options.xType, xv],
72      ["y", options.yType, yv],
73    ] as const) {
74      if (type === "log" && v <= 0) {
75        throw new Error(`${KIND}: row ${i + 1} ${axis} is ${v}, which a log axis cannot show`);
76      }
77    }
78    const name = label === undefined ? `Point ${i + 1}` : readLabel(KIND, row, label, i);
79    return { key: String(i), name, x: xv, y: yv, series: seriesOf(row, i) };
80  });
81
82  const multi = series !== undefined;
83  // Keyboard order: left to right, and bottom to top among points at the same x.
84  const order = points
85    .map((p, i) => ({ p, i }))
86    .sort((a, b) => a.p.x - b.p.x || a.p.y - b.p.y || a.i - b.i);
87  const rank = new Map(order.map(({ p }, r) => [p, r]));
88  const describe = (p: ScatterPoint): string =>
89    `${label === undefined ? "" : `${p.name}: `}${multi ? `${p.series}, ` : ""}${xLabel ?? x} ${format(p.x)}, ${yLabel ?? y} ${format(p.y)}`;
90
91  const marks: Plot.Markish[] = [];
92  if (options.regression) {
93    marks.push(
94      Plot.linearRegressionY(points, {
95        x: "x",
96        y: "y",
97        stroke: "series",
98        fill: "series",
99        ...(multi ? { z: "series" } : {}),
100      }),
101    );
102  }
103  marks.push(
104    Plot.dot(points, {
105      x: "x",
106      y: "y",
107      stroke: "series",
108      fill: "series",
109      fillOpacity: 0.35,
110      strokeWidth: 1.5,
111      r: 4,
112      ...(multi ? { symbol: "series" } : {}),
113      title: describe,
114      render: keyed(points, (p) => ({
115        key: p.key,
116        ...(multi && series ? { filter: { field: series, value: p.series } } : {}),
117        column: rank.get(p) ?? 0,
118        row: 0,
119        x: String(p.x),
120        ...(multi ? { series: p.series } : {}),
121      })),
122    }),
123  );
124
125  const rendered = renderPlot(
126    {
127      width: options.width ?? DEFAULT_WIDTH,
128      height: options.height ?? 360,
129      marginTop: 20,
130      marginLeft: yLabel === null ? 48 : 64,
131      marginBottom: 44,
132      x: {
133        type: options.xType ?? "linear",
134        // Log axes label powers of ten only; Plot's default adds every minor tick.
135        ...(options.xType === "log" ? { ticks: 5 } : {}),
136        label: xLabel,
137        labelAnchor: "center",
138        labelArrow: "none",
139        grid: true,
140        nice: true,
141      },
142      y: {
143        type: options.yType ?? "linear",
144        // Log axes label powers of ten only; Plot's default adds every minor tick.
145        ...(options.yType === "log" ? { ticks: 5 } : {}),
146        label: yLabel,
147        labelAnchor: "center",
148        labelArrow: "none",
149        grid: true,
150        nice: true,
151      },
152      color: { domain: seriesNames, range: [...plan.range] },
153      ...(multi ? { symbol: { domain: seriesNames } } : {}),
154      marks,
155    },
156    options.alt,
157  );
158
159  return figure(options, {
160    kind: "scatter",
161    svg: rendered.svg,
162    ...(rendered.x ? { x: rendered.x } : {}),
163    legend: multi ? plan.legend : [],
164    ...(multi && series ? { seriesField: series } : {}),
165    slotColors: plan.slotColors,
166    table: {
167      columns: ["Point", ...(multi ? ["Series"] : []), xLabel ?? x, yLabel ?? y],
168      rows: points.map((p) => [p.name, ...(multi ? [p.series] : []), format(p.x), format(p.y)]),
169    },
170  });
171}