react-cheminfo 0.15.0 → 0.16.0

package/src/parallel/core/parallelPaint.ts

@@ -0,0 +1,231 @@
+/**
+ * The lines, painted into a canvas.
+ *
+ * The first canvas figure in the family, and for one reason: ten thousand
+ * polylines of a dozen points each is a hundred and twenty thousand SVG
+ * coordinates the browser would keep as elements. Everything a reader points
+ * at, brushes or reads is still SVG or HTML over the top, so only the mass of
+ * lines is pixels — which is also why saving the figure keeps the axes and
+ * loses the lines, and why a site that needs a downloadable figure should say
+ * so before choosing this one.
+ */
+
+import type { ParallelAxisLayout } from './parallelAxes.ts';
+import { PARALLEL_MARGIN, parallelPixelAt } from './parallelAxes.ts';
+
+/** How strongly one kept line is drawn, so that the mass reads as a density. */
+export const PARALLEL_INCLUDED_ALPHA = 0.35;
+
+/** How wide a singled-out line's halo is, in pixels. */
+const HALO_WIDTH = 5;
+
+/** How wide a singled-out line itself is. */
+const HIGHLIGHT_WIDTH = 2;
+
+/** How large the dot at each of its axis crossings is. */
+const HIGHLIGHT_DOT_RADIUS = 3;
+
+const FULL_TURN = 2 * Math.PI;
+
+/** What one pass of the line painter needs. */
+export interface ParallelPaint {
+  /** The axes, from left to right, already placed and measured. */
+  layouts: readonly ParallelAxisLayout[];
+  /** Each axis's column, in the same order. */
+  values: ReadonlyArray<ArrayLike<number>>;
+  /** How many rows to draw. */
+  count: number;
+  /**
+   * Which rows the brushes keep, a zero meaning the row is drawn underneath in
+   * the excluded ink.
+   * @default null — every row is kept and nothing is drawn underneath
+   */
+  included?: Uint8Array | null;
+  /**
+   * Which colour each row takes, as a step into `palette`.
+   * @default null — every line takes `line`
+   */
+  steps?: Uint8Array | null;
+  /**
+   * The colours a step indexes, from `parallelPalette`.
+   * @default [] — nothing to index
+   */
+  palette?: readonly string[];
+  /** The ink a line takes when no quantity is colouring the lines. */
+  line: string;
+  /** The ink the rows a brush left out are drawn in. */
+  excluded: string;
+  /**
+   * How strongly a kept line is drawn. Turn it down for a dense library.
+   * @default PARALLEL_INCLUDED_ALPHA
+   */
+  includedAlpha?: number;
+}
+
+/** One row drawn over the mass, and the ink it is drawn in. */
+export interface ParallelHighlight {
+  /** The row. */
+  row: number;
+  /** Its ink. */
+  color: string;
+}
+
+/** What the highlight pass needs. */
+export interface ParallelHighlightPaint {
+  /** The rows to draw, the last one on top. */
+  highlights: readonly ParallelHighlight[];
+  /** The axes, from left to right. */
+  layouts: readonly ParallelAxisLayout[];
+  /** Each axis's column, in the same order. */
+  values: ReadonlyArray<ArrayLike<number>>;
+  /** The ink the halo under each line is drawn in. */
+  halo: string;
+}
+
+/**
+ * Resize a canvas to the device pixel grid and move its origin to the drawing
+ * area, which also clears whatever it held.
+ * @param canvas - The canvas, or `null` before it is mounted.
+ * @param width - Width of the figure, in CSS pixels.
+ * @param height - Its height, in CSS pixels.
+ * @returns The context, or `null` when there is nothing to draw on.
+ */
+export function preparePlotCanvas(
+  canvas: HTMLCanvasElement | null,
+  width: number,
+  height: number,
+): CanvasRenderingContext2D | null {
+  if (canvas === null) return null;
+  const context = canvas.getContext('2d');
+  if (context === null) return null;
+  const pixelRatio = Math.max(globalThis.devicePixelRatio || 1, 1);
+  // Assigning the backing store is what clears it; there is no second clear.
+  canvas.width = Math.round(width * pixelRatio);
+  canvas.height = Math.round(height * pixelRatio);
+  context.resetTransform();
+  context.scale(pixelRatio, pixelRatio);
+  context.translate(PARALLEL_MARGIN.left, PARALLEL_MARGIN.top);
+  return context;
+}
+
+/**
+ * Draw one line per row: the ones a brush left out first, underneath, then the
+ * kept ones over them.
+ *
+ * The excluded rows are one single path stroked once, in a light grey rather
+ * than a translucent black: overlapping segments of one stroked path
+ * accumulate alpha, so a translucent black saturates to black wherever the
+ * library is dense, while a light grey is a colour the pile can only converge
+ * on.
+ * @param context - A context already scaled and moved to the drawing area by {@link preparePlotCanvas}.
+ * @param paint - See {@link ParallelPaint}.
+ */
+export function paintParallelLines(
+  context: CanvasRenderingContext2D,
+  paint: ParallelPaint,
+): void {
+  const { layouts, values, count, line, excluded, includedAlpha } = paint;
+  if (layouts.length < 2) return;
+  const included = paint.included ?? null;
+  const steps = paint.steps ?? null;
+  const palette = paint.palette ?? [];
+  context.lineWidth = 1;
+
+  if (included !== null) {
+    context.strokeStyle = excluded;
+    context.beginPath();
+    for (let row = 0; row < count; row++) {
+      if (included[row] !== 0) continue;
+      traceParallelRow(context, row, layouts, values);
+    }
+    context.stroke();
+  }
+
+  context.globalAlpha = includedAlpha ?? PARALLEL_INCLUDED_ALPHA;
+  context.strokeStyle = line;
+  let previousStep = -1;
+  for (let row = 0; row < count; row++) {
+    if (included !== null && included[row] === 0) continue;
+    if (steps !== null) {
+      const step = steps[row] as number;
+      if (step !== previousStep) {
+        const color = palette[step];
+        if (color !== undefined) context.strokeStyle = color;
+        previousStep = step;
+      }
+    }
+    context.beginPath();
+    traceParallelRow(context, row, layouts, values);
+    context.stroke();
+  }
+  context.globalAlpha = 1;
+}
+
+/**
+ * Draw a few singled-out rows over the mass, each over a halo and dotted at
+ * every axis crossing.
+ * @param context - A context already scaled and moved to the drawing area.
+ * @param paint - See {@link ParallelHighlightPaint}.
+ */
+export function paintParallelHighlights(
+  context: CanvasRenderingContext2D,
+  paint: ParallelHighlightPaint,
+): void {
+  const { highlights, layouts, values, halo } = paint;
+  if (layouts.length < 2) return;
+  context.lineJoin = 'round';
+  context.lineCap = 'round';
+  for (const { row, color } of highlights) {
+    context.beginPath();
+    traceParallelRow(context, row, layouts, values);
+    context.strokeStyle = halo;
+    context.lineWidth = HALO_WIDTH;
+    context.stroke();
+    context.strokeStyle = color;
+    context.lineWidth = HIGHLIGHT_WIDTH;
+    context.stroke();
+
+    context.fillStyle = color;
+    for (let index = 0; index < layouts.length; index++) {
+      const layout = layouts[index];
+      const column = values[index];
+      if (layout === undefined || column === undefined) continue;
+      const y = parallelPixelAt(layout.pixels, column[row] as number);
+      if (!Number.isFinite(y)) continue;
+      context.beginPath();
+      context.arc(layout.x, y, HIGHLIGHT_DOT_RADIUS, 0, FULL_TURN);
+      context.fill();
+    }
+  }
+}
+
+/**
+ * Add one row's line to the path being built.
+ * @param context - A context already scaled and moved to the drawing area.
+ * @param row - The row to trace.
+ * @param layouts - The axes, from left to right.
+ * @param values - Each axis's column, in the same order.
+ */
+export function traceParallelRow(
+  context: CanvasRenderingContext2D,
+  row: number,
+  layouts: readonly ParallelAxisLayout[],
+  values: ReadonlyArray<ArrayLike<number>>,
+): void {
+  let started = false;
+  for (let index = 0; index < layouts.length; index++) {
+    const layout = layouts[index];
+    const column = values[index];
+    if (layout === undefined || column === undefined) continue;
+    const y = parallelPixelAt(layout.pixels, column[row] as number);
+    // A row whose value on this axis is not known yet has no point to draw:
+    // the line skips that axis rather than collapsing onto one of its ends.
+    if (!Number.isFinite(y)) continue;
+    if (started) {
+      context.lineTo(layout.x, y);
+    } else {
+      context.moveTo(layout.x, y);
+      started = true;
+    }
+  }
+}

package/src/parallel/core/parallelPalette.ts

@@ -0,0 +1,80 @@
+/**
+ * The colour each line is drawn in, as a step into a sampled ramp.
+ *
+ * A canvas reassigns `strokeStyle` once per line, and a thousand different
+ * colours is a thousand style writes. Quantising the ramp to 121 steps and
+ * keeping the rows in the order they came means the style is written about
+ * 121 times for the whole figure — while no reader can tell a hundred-and-
+ * twenty-first of a ramp apart from its neighbour.
+ */
+
+import type { ColorScale } from '../../color/core/interpolate.ts';
+import { evenScale, sampleScale } from '../../color/core/interpolate.ts';
+import { positionInRange } from '../../color/core/scale.ts';
+import { resolveColorScale } from '../../color/core/scaleText.ts';
+import { DEFAULT_COLOR_SCALE_ID } from '../../color/core/scales.ts';
+
+import { parallelExtent } from './parallelExtent.ts';
+import type { ParallelColorBy } from './parallelTypes.ts';
+
+/** How many steps the ramp is quantised into; there is one more colour than steps. */
+export const PARALLEL_PALETTE_STEPS = 120;
+
+/**
+ * The ramp, sampled into the steps a line's colour is looked up by.
+ * @param scale - The ramp, as the registry hands it over or as a plain list of colours. Defaults to viridis.
+ * @returns `PARALLEL_PALETTE_STEPS + 1` colours, from the low end to the high end.
+ */
+export function parallelPalette(
+  scale?: ColorScale | readonly string[],
+): readonly string[] {
+  return sampleScale(resolveRamp(scale), PARALLEL_PALETTE_STEPS + 1);
+}
+
+/**
+ * Which step of the ramp each row takes.
+ *
+ * Worked out once per data change rather than per repaint, and held as bytes:
+ * a library of ten thousand rows costs ten kilobytes and the painter's inner
+ * loop reads an integer instead of placing a value on a ramp.
+ * @param color - The quantity the lines are coloured by.
+ * @param count - How many rows there are.
+ * @returns One step per row, from `0` to {@link PARALLEL_PALETTE_STEPS}.
+ */
+export function parallelColorSteps(
+  color: ParallelColorBy,
+  count: number,
+): Uint8Array {
+  const steps = new Uint8Array(count);
+  const extent = parallelExtent(color.values, count);
+  const min = color.min ?? extent.min;
+  const max = color.max ?? extent.max;
+  const logarithmic = color.logarithmic ?? false;
+  const span = max - min;
+  const rows = Math.min(count, color.values.length);
+  for (let row = 0; row < rows; row++) {
+    const value = color.values[row] as number;
+    steps[row] = logarithmic
+      ? Math.round(
+          positionInRange(value, min, max, { logarithmic: true }) *
+            PARALLEL_PALETTE_STEPS,
+        )
+      : colorStep(value, min, span);
+  }
+  return steps;
+}
+
+function resolveRamp(scale?: ColorScale | readonly string[]): ColorScale {
+  if (scale === undefined) {
+    return resolveColorScale(DEFAULT_COLOR_SCALE_ID).scale;
+  }
+  return 'stops' in scale ? scale : evenScale(scale);
+}
+
+function colorStep(value: number, min: number, span: number): number {
+  if (span <= 0) return 0;
+  const ratio = (value - min) / span;
+  if (Number.isNaN(ratio) || ratio < 0) return 0;
+  if (ratio > 1) return PARALLEL_PALETTE_STEPS;
+  return Math.round(ratio * PARALLEL_PALETTE_STEPS);
+}

package/src/parallel/core/parallelTicks.ts

@@ -0,0 +1,164 @@
+/**
+ * How one axis is graduated.
+ *
+ * Five evenly spaced marks across the raw extent, not `chartAxisScale`'s nice
+ * ones: nicing moves the ends of the axis, and a figure whose whole job is to
+ * compare rows against each other must end exactly where the data does. A
+ * caller who wants round numbers asks for them with `nice`, per axis.
+ */
+
+import {
+  chartAxisScale,
+  chartTickDecimals,
+} from '../../chart/core/chartAxisScale.ts';
+import { formatDecimal } from '../../format/core/numbers.ts';
+import { roundTo } from '../../format/core/roundTo.ts';
+
+import type { ParallelAxis, ParallelTick } from './parallelTypes.ts';
+
+/** How many graduations an axis carries when the caller asks for no number. */
+export const PARALLEL_TICK_COUNT = 5;
+
+/** The most decimals a graduation is ever written with. */
+const MOST_TICK_DECIMALS = 6;
+
+/** How far a label may sit from its own value: a tenth of the spacing. */
+const LABEL_TOLERANCE = 10;
+
+/** An axis's ends and the graduations written along it. */
+export interface ParallelGraduation {
+  /** The two ends of the axis, low first, after any nicing. */
+  domain: readonly [number, number];
+  /** The graduations, from the bottom of the axis to the top. */
+  ticks: readonly ParallelTick[];
+}
+
+/**
+ * The graduations of one axis, and the ends they are spread between.
+ *
+ * Three ways, in order: the caller's own list wins outright — a coded quantity
+ * reading `none`, `low`, `high` is nobody else's to invent; `nice` hands the
+ * axis to `chartAxisScale`, which rounds both ends outward to whole steps; and
+ * otherwise the extent is divided evenly and a mark whose label repeats the
+ * one below it is dropped, so an axis of whole numbers from 0 to 2 reads
+ * `0 1 2` rather than writing `1` twice.
+ * @param axis - The axis, for its formatting and how many marks it wants.
+ * @param min - The value at the bottom of the axis.
+ * @param max - The value at its top.
+ * @returns The ends and the graduations. See {@link ParallelGraduation}.
+ */
+export function parallelTicks(
+  axis: ParallelAxis,
+  min: number,
+  max: number,
+): ParallelGraduation {
+  const domain = [min, max] as const;
+  if (axis.ticks !== undefined) return { domain, ticks: axis.ticks };
+
+  const wanted = Math.max(2, Math.trunc(axis.tickCount ?? PARALLEL_TICK_COUNT));
+  if (axis.nice === true && axis.scale !== 'log') {
+    return nicedGraduation(axis, min, max, wanted);
+  }
+
+  const values = evenValues(min, max, wanted, axis.scale === 'log');
+  return { domain, ticks: labelled(values, axis.format) };
+}
+
+function nicedGraduation(
+  axis: ParallelAxis,
+  min: number,
+  max: number,
+  wanted: number,
+): ParallelGraduation {
+  const scale = chartAxisScale(min, max, { count: wanted, nice: true });
+  const ticks: ParallelTick[] = [];
+  for (let index = 0; index < scale.values.length; index++) {
+    const value = scale.values[index] as number;
+    const label =
+      axis.format === undefined
+        ? (scale.labels[index] ?? formatDecimal(value, scale.decimals))
+        : axis.format(value);
+    if (ticks.at(-1)?.label === label) continue;
+    ticks.push({ value, label });
+  }
+  return { domain: scale.domain, ticks };
+}
+
+function evenValues(
+  min: number,
+  max: number,
+  wanted: number,
+  logarithmic: boolean,
+): number[] {
+  const values: number[] = [];
+  const low = logarithmic ? Math.log10(Math.max(min, smallestStep(max))) : min;
+  const high = logarithmic ? Math.log10(Math.max(max, smallestStep(max))) : max;
+  const span = high - low;
+  for (let index = 0; index < wanted; index++) {
+    const placed = low + (span * index) / (wanted - 1);
+    values.push(logarithmic ? 10 ** placed : placed);
+  }
+  return values;
+}
+
+function labelled(
+  values: readonly number[],
+  format: ((value: number) => string) | undefined,
+): ParallelTick[] {
+  const decimals = format === undefined ? tickDecimals(values) : 0;
+  const ticks: ParallelTick[] = [];
+  for (const value of values) {
+    const label =
+      format === undefined ? formatDecimal(value, decimals) : format(value);
+    if (ticks.at(-1)?.label === label) continue;
+    ticks.push({ value, label });
+  }
+  return ticks;
+}
+
+/**
+ * As many decimals as the spacing needs, and one more whenever rounding would
+ * move a mark by more than a tenth of that spacing — which is what keeps an
+ * axis from 12.3 to 157 reading `12 48 85 121 157` while one from −1.5 to 2.5
+ * still reads `−1.5 −0.5 0.5 1.5 2.5` rather than rounding both away.
+ * @param values - The graduations, in the axis's own units.
+ * @returns How many decimals each of their labels carries.
+ */
+function tickDecimals(values: readonly number[]): number {
+  const step = smallestGap(values);
+  const tolerance = step / LABEL_TOLERANCE;
+  let decimals = chartTickDecimals(step);
+  while (
+    decimals < MOST_TICK_DECIMALS &&
+    !faithful(values, decimals, tolerance)
+  ) {
+    decimals++;
+  }
+  return decimals;
+}
+
+function faithful(
+  values: readonly number[],
+  decimals: number,
+  tolerance: number,
+): boolean {
+  for (const value of values) {
+    if (Math.abs(value - roundTo(value, decimals)) > tolerance) return false;
+  }
+  return true;
+}
+
+function smallestGap(values: readonly number[]): number {
+  let smallest = Number.POSITIVE_INFINITY;
+  for (let index = 1; index < values.length; index++) {
+    const gap = Math.abs(
+      (values[index] as number) - (values[index - 1] as number),
+    );
+    if (gap > 0 && gap < smallest) smallest = gap;
+  }
+  return Number.isFinite(smallest) ? smallest : 1;
+}
+
+function smallestStep(max: number): number {
+  return max > 0 ? max * 1e-12 : 1;
+}

package/src/parallel/core/parallelTypes.ts

@@ -0,0 +1,147 @@
+/**
+ * What a parallel-coordinates figure is asked to draw: one axis per column,
+ * the intervals the reader brushed on them, and the quantity the lines are
+ * coloured by.
+ *
+ * The figure itself is index-based — every axis hands over its column as an
+ * `ArrayLike<number>` read in place — so a repaint costs an indexed read per
+ * value rather than a call. {@link parallelAxisOf} is the one place a row type
+ * is named, and it is run once per data change rather than once per repaint.
+ */
+
+import type { ColorScale } from '../../color/core/interpolate.ts';
+
+/** How a value is placed along an axis. */
+export type ParallelAxisScale = 'linear' | 'log';
+
+/** One labelled graduation a caller writes itself. */
+export interface ParallelTick {
+  /** Where it sits, in the axis's own units. */
+  value: number;
+  /** What is written beside it. */
+  label: string;
+}
+
+/** One vertical axis of a parallel-coordinates figure, and the column it draws. */
+export interface ParallelAxis {
+  /**
+   * A stable key, which is how a brushed range is reported and how a caller
+   * names the axis the colour is read from. Never an index: axes are added and
+   * reordered, and a range keyed on a position outlives the axis it belonged
+   * to.
+   */
+  id: string;
+  /** What it is called, written over the axis. */
+  label: string;
+  /**
+   * Every row's value, in the figure's row order. Read in place — nothing is
+   * copied — so a `Float64Array` is the cheapest thing to pass.
+   */
+  values: ArrayLike<number>;
+  /**
+   * The two ends of the axis, low first. Left out, they are the column's own
+   * smallest and largest finite value, and a column with no spread at all is
+   * opened by half a unit on each side so that it still draws.
+   * @default undefined — the column's own range
+   */
+  domain?: readonly [number, number];
+  /**
+   * How values are placed between the ends. `log` needs a domain whose low end
+   * is above zero; a value at or below zero is pinned to the low end.
+   * @default 'linear'
+   */
+  scale?: ParallelAxisScale;
+  /**
+   * How a tick is written. Left out, the ticks carry as many decimals as the
+   * spacing needs.
+   * @default undefined
+   */
+  format?: (value: number) => string;
+  /**
+   * The graduations, written out by the caller — what a coded quantity needs,
+   * where `0`, `1`, `2` should read `none`, `low`, `high`.
+   * @default undefined — the figure graduates the axis itself
+   */
+  ticks?: readonly ParallelTick[];
+  /**
+   * Roughly how many graduations to aim for, when the figure picks them.
+   * @default 5
+   */
+  tickCount?: number;
+  /**
+   * Whether the ends are rounded outward to whole tick steps. Off, so the axis
+   * ends exactly on the data — a reader comparing two molecules on a drug
+   * score must see the best one touch the top of its axis, not float below a
+   * round number nothing reached.
+   * @default false
+   */
+  nice?: boolean;
+  /**
+   * The unit written after the axis name, e.g. `g/mol`.
+   * @default '' — nothing is written
+   */
+  unit?: string;
+}
+
+/** An interval kept on one axis, in that axis's own units, low first. */
+export type ParallelRange = readonly [number, number];
+
+/** Which rows a set of brushes keeps, keyed by axis id. */
+export type ParallelRanges = Readonly<Record<string, ParallelRange | null>>;
+
+/** How the lines are coloured. */
+export interface ParallelColorBy {
+  /** The quantity read for each row, in the figure's row order. */
+  values: ArrayLike<number>;
+  /**
+   * The value at the low end of the ramp.
+   * @default the smallest finite value
+   */
+  min?: number;
+  /**
+   * The value at its high end.
+   * @default the largest finite value
+   */
+  max?: number;
+  /**
+   * The ramp, as the registry hands it over or as a plain list of colours.
+   * @default viridis — `resolveColorScale(DEFAULT_COLOR_SCALE_ID).scale`
+   */
+  scale?: ColorScale | readonly string[];
+  /**
+   * Whether the quantity is read on a base-10 logarithmic ramp.
+   * @default false
+   */
+  logarithmic?: boolean;
+}
+
+/** An axis described by the field to read off each row, rather than by its column. */
+export type ParallelAxisSource<Row> = Omit<ParallelAxis, 'values'> & {
+  /**
+   * The value this axis reads off one row. Called once per row per data
+   * change, never per repaint.
+   */
+  readonly value: (row: Row) => number;
+};
+
+/**
+ * One axis built by reading a field off each row.
+ *
+ * The one place a row type is named: the figure itself reads numbers out of a
+ * typed array, so a repaint costs an indexed read rather than a call per
+ * value. Call it inside a `useMemo` keyed on the rows.
+ * @param rows - The rows, in the order the figure will index them.
+ * @param axis - The axis, with the field to read instead of its values.
+ * @returns The axis, with its values filled in.
+ */
+export function parallelAxisOf<Row>(
+  rows: readonly Row[],
+  axis: ParallelAxisSource<Row>,
+): ParallelAxis {
+  const { value, ...rest } = axis;
+  const values = new Float64Array(rows.length);
+  for (let row = 0; row < rows.length; row++) {
+    values[row] = value(rows[row] as Row);
+  }
+  return { ...rest, values };
+}