react-cheminfo 0.15.0 → 0.16.0

package/src/parallel/core/parallelAxes.ts

@@ -0,0 +1,207 @@
+/**
+ * Where each axis stands, how far it reaches, and how a value on it becomes a
+ * pixel.
+ *
+ * The first axis sits flush with the left of the drawing area and the last one
+ * flush with the right, rather than inset the way a two-axis chart insets its
+ * plot: the axes *are* the figure here, and a reader comparing the leftmost
+ * column against the rightmost must see both of them, not a margin.
+ */
+
+import { chartScale } from '../../chart/core/chartScale.ts';
+
+import { parallelExtent } from './parallelExtent.ts';
+import { parallelTicks } from './parallelTicks.ts';
+import type {
+  ParallelAxis,
+  ParallelAxisScale,
+  ParallelTick,
+} from './parallelTypes.ts';
+
+/** Room kept around the drawing area for the axis names and the tick labels. */
+export const PARALLEL_MARGIN = {
+  /** Above the drawing area, where the axis names are written. */
+  top: 26,
+  /** To the right of it, so the last axis's labels are not clipped. */
+  right: 54,
+  /** Below it. */
+  bottom: 22,
+  /** To its left, where the first axis's tick labels are written. */
+  left: 54,
+} as const;
+
+/** How a value on one axis becomes a pixel, as the two numbers a multiply-add needs. */
+export interface ParallelAxisPixels {
+  /** The pixel the value zero lands on — or the value one, on a log axis. */
+  readonly offset: number;
+  /** Pixels per unit, negative because an axis grows upward. Zero when the axis is flat. */
+  readonly factor: number;
+  /** Whether a value is read through its base-10 logarithm first. */
+  readonly logarithmic: boolean;
+  /** The smallest value a log axis can place; anything at or below it is pinned there. */
+  readonly floor: number;
+}
+
+/** One axis, placed and measured, ready to draw. */
+export interface ParallelAxisLayout {
+  /** The axis this lays out. */
+  id: string;
+  /** Its name. */
+  label: string;
+  /** The unit written after the name, or an empty string. */
+  unit: string;
+  /** Horizontal centre, in pixels from the left of the drawing area. */
+  x: number;
+  /** The value at the bottom of the axis. */
+  min: number;
+  /** The value at its top. */
+  max: number;
+  /** How values are placed between them. */
+  scale: ParallelAxisScale;
+  /** Its graduations, already written out, from the bottom up. */
+  ticks: readonly ParallelTick[];
+  /** How a value on it becomes a pixel, worked out once here. */
+  pixels: ParallelAxisPixels;
+}
+
+/** A flat axis: every value lands on the top of the drawing area. */
+const FLAT: ParallelAxisPixels = {
+  offset: 0,
+  factor: 0,
+  logarithmic: false,
+  floor: 1,
+};
+
+/** How far below the largest value a log axis may reach when its low end is not positive. */
+const LOG_FLOOR_SHARE = 1e-12;
+
+/**
+ * Place every axis across the drawing area and work out what it reaches.
+ * @param axes - The axes, from left to right.
+ * @param count - How many rows the columns are read over.
+ * @param innerWidth - Width between the first and the last axis, in pixels.
+ * @param innerHeight - Height of the drawing area, in pixels.
+ * @returns One layout per axis, in the order they were given. A single axis is
+ * centred; two or more are spread evenly with the outer ones flush with the
+ * edges.
+ */
+export function parallelAxisLayouts(
+  axes: readonly ParallelAxis[],
+  count: number,
+  innerWidth: number,
+  innerHeight: number,
+): ParallelAxisLayout[] {
+  const layouts: ParallelAxisLayout[] = [];
+  const total = axes.length;
+  for (let index = 0; index < total; index++) {
+    const axis = axes[index];
+    if (axis === undefined) continue;
+    const extent = axisExtent(axis, count);
+    const graduation = parallelTicks(axis, extent.min, extent.max);
+    const [min, max] = graduation.domain;
+    const scale = axis.scale ?? 'linear';
+    layouts.push({
+      id: axis.id,
+      label: axis.label,
+      unit: axis.unit ?? '',
+      x: total === 1 ? innerWidth / 2 : (innerWidth * index) / (total - 1),
+      min,
+      max,
+      scale,
+      ticks: graduation.ticks,
+      pixels: parallelAxisPixels(min, max, scale, innerHeight),
+    });
+  }
+  return layouts;
+}
+
+/**
+ * The mapping that puts `max` at the top of the drawing area and `min` at its
+ * bottom.
+ * @param min - The value at the bottom.
+ * @param max - The value at the top.
+ * @param scale - How values are placed between them.
+ * @param innerHeight - Height of the drawing area, in pixels.
+ * @returns The mapping. An axis with no span, or one drawn in no height at
+ * all, comes back flat, which pins every value to the top rather than dividing
+ * by zero.
+ */
+export function parallelAxisPixels(
+  min: number,
+  max: number,
+  scale: ParallelAxisScale,
+  innerHeight: number,
+): ParallelAxisPixels {
+  if (max - min <= 0 || innerHeight <= 0) return FLAT;
+  if (scale !== 'log') {
+    const linear = chartScale(min, max, innerHeight, 0);
+    return { ...linear, logarithmic: false, floor: 1 };
+  }
+  const floor = min > 0 ? min : max > 0 ? max * LOG_FLOOR_SHARE : 1;
+  const low = Math.log10(floor);
+  const high = Math.log10(Math.max(max, floor));
+  if (high - low <= 0) return FLAT;
+  const mapping = chartScale(low, high, innerHeight, 0);
+  return { ...mapping, logarithmic: true, floor };
+}
+
+/**
+ * Where one value falls on an axis, in pixels.
+ *
+ * For a single conversion — a tick, a brushed edge, a highlighted crossing.
+ * Inside a loop over rows, read `axis.pixels` and write the multiply-add out.
+ * @param pixels - The axis's mapping.
+ * @param value - The value to place.
+ * @returns The pixel, measured from the top of the drawing area. A value
+ * outside the axis lands outside the drawing area and is not clipped.
+ */
+export function parallelPixelAt(
+  pixels: ParallelAxisPixels,
+  value: number,
+): number {
+  if (pixels.factor === 0) return pixels.offset;
+  const placed = pixels.logarithmic
+    ? Math.log10(Math.max(value, pixels.floor))
+    : value;
+  return pixels.offset + placed * pixels.factor;
+}
+
+/**
+ * Where one value falls on an axis, in pixels.
+ * @param value - The value to place.
+ * @param axis - The axis it belongs to.
+ * @returns The pixel, measured from the top of the drawing area.
+ */
+export function parallelValueToY(
+  value: number,
+  axis: ParallelAxisLayout,
+): number {
+  return parallelPixelAt(axis.pixels, value);
+}
+
+/**
+ * What value a pixel on an axis stands for — the brush's direction.
+ * @param y - The pixel, measured from the top of the drawing area.
+ * @param axis - The axis it belongs to.
+ * @returns The value there, or the top of a flat axis. Zero comes back
+ * unsigned, so an interval that reaches the end of an axis never reads `-0`.
+ */
+export function parallelYToValue(y: number, axis: ParallelAxisLayout): number {
+  const { pixels, max } = axis;
+  if (pixels.factor === 0) return max;
+  const placed = (y - pixels.offset) / pixels.factor;
+  if (pixels.logarithmic) return 10 ** placed;
+  return placed === 0 ? 0 : placed;
+}
+
+function axisExtent(
+  axis: ParallelAxis,
+  count: number,
+): { min: number; max: number } {
+  const domain = axis.domain;
+  if (domain === undefined) return parallelExtent(axis.values, count);
+  return {
+    min: Math.min(domain[0], domain[1]),
+    max: Math.max(domain[0], domain[1]),
+  };
+}

package/src/parallel/core/parallelBrush.ts

@@ -0,0 +1,145 @@
+/**
+ * The brush, as arithmetic rather than as a library.
+ *
+ * Everything a vertical brush does — create by dragging on a bare axis, move
+ * the band, drag either edge, clear by pressing outside it — is four answers
+ * to one question: which part of the axis the press landed on. Written this
+ * way it is a pure function of a press and a pointer, so the whole gesture is
+ * covered by tests in a runtime with no DOM at all, which is the one thing a
+ * DOM-mutating brush could never be.
+ */
+
+import type { ParallelAxisLayout } from './parallelAxes.ts';
+import { parallelValueToY, parallelYToValue } from './parallelAxes.ts';
+import type { ParallelRange } from './parallelTypes.ts';
+
+/** A band kept on one axis, in pixels from the top of the drawing area. */
+export interface ParallelBand {
+  /** The upper edge, which is the higher value. */
+  top: number;
+  /** The lower edge, which is the lower value. */
+  bottom: number;
+}
+
+/** Which part of an axis a press landed on. */
+export type ParallelBrushGrip = 'create' | 'move' | 'top' | 'bottom';
+
+/** A drag in progress on one axis. */
+export interface ParallelBrushDrag {
+  /** The axis being brushed, by its id. */
+  axis: string;
+  /** What the press took hold of. */
+  grip: ParallelBrushGrip;
+  /** Where the press landed, in pixels from the top of the drawing area. */
+  originY: number;
+  /** The band as it stood when the press landed. */
+  origin: ParallelBand;
+}
+
+/** How close to an edge a press has to land to take hold of it, in pixels. */
+export const PARALLEL_BRUSH_HANDLE_REACH = 4;
+
+/** How tall a released band has to be to count as a band rather than a click. */
+export const PARALLEL_BRUSH_SMALLEST = 1;
+
+/** How far either side of an axis a press still reaches it, in pixels. */
+export const PARALLEL_BRUSH_HALF_WIDTH = 9;
+
+/**
+ * What a press at that height takes hold of.
+ * @param y - Where the press landed, in pixels from the top of the drawing area.
+ * @param band - The band already on that axis, or `null` when it carries none.
+ * @returns The grip. A press within {@link PARALLEL_BRUSH_HANDLE_REACH} of an
+ * edge takes that edge, a press inside the band moves it, and anything else —
+ * including a press on a bare axis — starts a new one.
+ */
+export function parallelBrushGrip(
+  y: number,
+  band: ParallelBand | null,
+): ParallelBrushGrip {
+  if (band === null) return 'create';
+  if (Math.abs(y - band.top) <= PARALLEL_BRUSH_HANDLE_REACH) return 'top';
+  if (Math.abs(y - band.bottom) <= PARALLEL_BRUSH_HANDLE_REACH) return 'bottom';
+  if (y > band.top && y < band.bottom) return 'move';
+  return 'create';
+}
+
+/**
+ * The band a drag stands at, now that the pointer is there.
+ * @param drag - The drag, as it began.
+ * @param y - Where the pointer is, in pixels from the top of the drawing area.
+ * @param height - Height of the drawing area, in pixels.
+ * @returns The band, held inside the drawing area at both ends. Dragging one
+ * edge past the other swaps them rather than inverting the band, and a band
+ * being moved keeps its height rather than being squashed against an end.
+ */
+export function parallelBandAt(
+  drag: ParallelBrushDrag,
+  y: number,
+  height: number,
+): ParallelBand {
+  const to = clamp(y, 0, height);
+  if (drag.grip === 'create') return order(drag.originY, to);
+  if (drag.grip === 'top') return order(to, drag.origin.bottom);
+  if (drag.grip === 'bottom') return order(drag.origin.top, to);
+  const shift = clamp(
+    to - drag.originY,
+    -drag.origin.top,
+    height - drag.origin.bottom,
+  );
+  return {
+    top: drag.origin.top + shift,
+    bottom: drag.origin.bottom + shift,
+  };
+}
+
+/**
+ * Whether a released band keeps anything, or was a click that clears the axis.
+ * @param band - The band, as the pointer left it.
+ * @returns Whether it is tall enough to be an interval.
+ */
+export function parallelIsBand(band: ParallelBand): boolean {
+  return band.bottom - band.top >= PARALLEL_BRUSH_SMALLEST;
+}
+
+/**
+ * Where an interval sits on its axis, in pixels.
+ * @param range - The interval, low value first.
+ * @param axis - The axis it belongs to.
+ * @returns The band.
+ */
+export function parallelBandOf(
+  range: ParallelRange,
+  axis: ParallelAxisLayout,
+): ParallelBand {
+  return order(
+    parallelValueToY(range[1], axis),
+    parallelValueToY(range[0], axis),
+  );
+}
+
+/**
+ * What interval a band keeps, in the axis's own units.
+ * @param band - The band, in pixels from the top of the drawing area.
+ * @param axis - The axis it belongs to.
+ * @returns The interval, low value first — which is the order every filter in
+ * the family reads, and getting it backwards keeps nothing at all.
+ */
+export function parallelRangeOf(
+  band: ParallelBand,
+  axis: ParallelAxisLayout,
+): ParallelRange {
+  const low = parallelYToValue(band.bottom, axis);
+  const high = parallelYToValue(band.top, axis);
+  return low <= high ? [low, high] : [high, low];
+}
+
+function order(a: number, b: number): ParallelBand {
+  return a <= b ? { top: a, bottom: b } : { top: b, bottom: a };
+}
+
+function clamp(value: number, low: number, high: number): number {
+  if (value < low) return low;
+  if (value > high) return high;
+  return value;
+}

package/src/parallel/core/parallelExtent.ts

@@ -0,0 +1,56 @@
+/**
+ * The two ends of one axis, read off its own column.
+ *
+ * Deliberately not `chartPadExtent`: a parallel-coordinates axis ends exactly
+ * on the data, because the reader compares rows against each other rather than
+ * against a round number, and the best row has to touch the top of its axis.
+ * The only opening is for a column with no spread at all, which would
+ * otherwise draw no axis and place every row on one pixel.
+ */
+
+/** How far a column with no spread at all is opened, on each side. */
+export const PARALLEL_DEGENERATE_PADDING = 0.5;
+
+/** The two ends of an axis, low first. */
+export interface ParallelExtent {
+  /** The value at the bottom of the axis. */
+  min: number;
+  /** The value at its top. */
+  max: number;
+}
+
+/**
+ * The smallest and the largest finite value of one column.
+ * @param values - The column, read in place.
+ * @param count - How many rows to read, from the start.
+ * @returns The extent. A column holding no finite value at all comes back as
+ * half a unit either side of zero, and a constant one as half a unit either
+ * side of its value, so that both still draw an axis.
+ */
+export function parallelExtent(
+  values: ArrayLike<number>,
+  count: number,
+): ParallelExtent {
+  const rows = Math.min(count, values.length);
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  for (let row = 0; row < rows; row++) {
+    const value = values[row] as number;
+    if (!Number.isFinite(value)) continue;
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  if (min > max) {
+    return {
+      min: -PARALLEL_DEGENERATE_PADDING,
+      max: PARALLEL_DEGENERATE_PADDING,
+    };
+  }
+  if (min === max) {
+    return {
+      min: min - PARALLEL_DEGENERATE_PADDING,
+      max: max + PARALLEL_DEGENERATE_PADDING,
+    };
+  }
+  return { min, max };
+}

package/src/parallel/core/parallelFilter.ts

@@ -0,0 +1,94 @@
+/**
+ * Which rows the brushes keep.
+ *
+ * Exported rather than kept inside the figure, because a table beside the
+ * figure has to filter on the same answer. Two definitions of "kept" is the
+ * fault this file exists to prevent: a table showing fourteen rows under a
+ * plot drawing one is not a rounding error, it is two different programs.
+ */
+
+import type {
+  ParallelAxis,
+  ParallelRange,
+  ParallelRanges,
+} from './parallelTypes.ts';
+
+/** One axis's interval, ready to be tested row by row. */
+interface ActiveRange {
+  /** The column being tested. */
+  values: ArrayLike<number>;
+  /** The lowest value kept. */
+  minimum: number;
+  /** The highest value kept. */
+  maximum: number;
+}
+
+/**
+ * Whether one value falls inside an interval.
+ * @param range - The interval, low value first.
+ * @param value - The value to test.
+ * @returns Whether it is kept. Both ends are inclusive, and a value that is
+ * not a number is kept by no interval at all — a row whose property has not
+ * been worked out yet cannot be said to be in range.
+ */
+export function parallelRangeKeeps(
+  range: ParallelRange,
+  value: number,
+): boolean {
+  return value >= range[0] && value <= range[1];
+}
+
+/**
+ * Which rows every brush keeps at once.
+ * @param axes - The axes, whose ids the intervals are keyed by.
+ * @param ranges - The interval each axis keeps, or `null` for none.
+ * @param count - How many rows there are.
+ * @returns One byte per row, `1` for kept. An interval keyed on an axis that
+ * is not drawn is ignored rather than emptying the figure, so a range left
+ * over from a column the reader has since hidden does not silently filter
+ * everything away.
+ */
+export function parallelIncludedMask(
+  axes: readonly ParallelAxis[],
+  ranges: ParallelRanges,
+  count: number,
+): Uint8Array {
+  const included = new Uint8Array(count).fill(1);
+  const active: ActiveRange[] = [];
+  for (const axis of axes) {
+    const range = ranges[axis.id];
+    if (range === null || range === undefined) continue;
+    active.push({
+      values: axis.values,
+      minimum: Math.min(range[0], range[1]),
+      maximum: Math.max(range[0], range[1]),
+    });
+  }
+  if (active.length === 0) return included;
+
+  for (const range of active) {
+    const rows = Math.min(count, range.values.length);
+    for (let row = 0; row < rows; row++) {
+      if (included[row] === 0) continue;
+      const value = range.values[row] as number;
+      if (value >= range.minimum && value <= range.maximum) continue;
+      included[row] = 0;
+    }
+    // A row the figure has no value for on a brushed axis is not in range.
+    for (let row = rows; row < count; row++) included[row] = 0;
+  }
+  return included;
+}
+
+/**
+ * How many rows a mask keeps.
+ * @param included - One byte per row, `1` for kept.
+ * @returns The count.
+ */
+export function parallelKeptCount(included: Uint8Array): number {
+  let kept = 0;
+  for (const row of included) {
+    if (row !== 0) kept++;
+  }
+  return kept;
+}

package/src/parallel/core/parallelHit.ts

@@ -0,0 +1,106 @@
+/**
+ * Which row the pointer is over.
+ *
+ * Only the segment between the two axes the pointer sits between is tested, so
+ * the cost is one distance per row whatever the number of axes. The vertical
+ * gap to the segment is projected onto its normal, so a steep line is no
+ * harder to pick than a flat one — without which the only rows a reader can
+ * ever point at are the uninteresting ones.
+ */
+
+import type { ParallelAxisLayout } from './parallelAxes.ts';
+import { parallelPixelAt } from './parallelAxes.ts';
+
+/** How far the pointer may sit from a line and still pick it, in pixels. */
+export const PARALLEL_HOVER_TOLERANCE = 6;
+
+/** A pointer position, relative to the top left of the drawing area. */
+export interface ParallelPoint {
+  /** Pixels from the left of the drawing area. */
+  x: number;
+  /** Pixels from its top. */
+  y: number;
+}
+
+/** The pair of axes a pointer sits between, as indices into the layouts. */
+export interface ParallelSegment {
+  /** The axis to the left of the pointer. */
+  left: number;
+  /** The axis to its right. */
+  right: number;
+}
+
+/**
+ * The pair of axes a horizontal position sits between.
+ * @param x - Pixels from the left of the drawing area.
+ * @param axes - The axes, from left to right.
+ * @param tolerance - How far past the first and the last axis still counts. Defaults to {@link PARALLEL_HOVER_TOLERANCE}.
+ * @returns The pair, or `null` when there are fewer than two axes or the
+ * position is past either end of the figure.
+ */
+export function parallelSegmentAt(
+  x: number,
+  axes: readonly ParallelAxisLayout[],
+  tolerance: number = PARALLEL_HOVER_TOLERANCE,
+): ParallelSegment | null {
+  const first = axes[0];
+  const last = axes.at(-1);
+  if (first === undefined || last === undefined || axes.length < 2) return null;
+  if (x < first.x - tolerance || x > last.x + tolerance) return null;
+  for (let index = 1; index < axes.length; index++) {
+    const right = axes[index];
+    if (right === undefined) continue;
+    if (x <= right.x || index === axes.length - 1) {
+      return { left: index - 1, right: index };
+    }
+  }
+  return null;
+}
+
+/**
+ * The row whose line runs closest to the pointer.
+ * @param point - Where the pointer is, relative to the drawing area.
+ * @param axes - The axes, from left to right.
+ * @param values - Each axis's column, in the same order.
+ * @param count - How many rows are drawn.
+ * @param included - Which rows a brush keeps, a zero meaning the row is not pickable. Defaults to every row.
+ * @param tolerance - How far the pointer may sit from a line. Defaults to {@link PARALLEL_HOVER_TOLERANCE}.
+ * @returns The row, or `-1` when the pointer is over no line.
+ */
+export function parallelNearestRow(
+  point: ParallelPoint,
+  axes: readonly ParallelAxisLayout[],
+  values: ReadonlyArray<ArrayLike<number>>,
+  count: number,
+  included?: Uint8Array,
+  tolerance: number = PARALLEL_HOVER_TOLERANCE,
+): number {
+  const segment = parallelSegmentAt(point.x, axes, tolerance);
+  if (segment === null) return -1;
+  const left = axes[segment.left];
+  const right = axes[segment.right];
+  const leftColumn = values[segment.left];
+  const rightColumn = values[segment.right];
+  if (left === undefined || right === undefined) return -1;
+  if (leftColumn === undefined || rightColumn === undefined) return -1;
+
+  const width = right.x - left.x;
+  if (width <= 0) return -1;
+  const ratio = (point.x - left.x) / width;
+  const rows = Math.min(count, leftColumn.length, rightColumn.length);
+
+  let nearest = -1;
+  let nearestDistance = tolerance;
+  for (let row = 0; row < rows; row++) {
+    if (included?.[row] === 0) continue;
+    const leftY = parallelPixelAt(left.pixels, leftColumn[row] as number);
+    const rightY = parallelPixelAt(right.pixels, rightColumn[row] as number);
+    const gap = Math.abs(leftY + (rightY - leftY) * ratio - point.y);
+    const distance = (gap * width) / Math.hypot(width, rightY - leftY);
+    if (distance < nearestDistance) {
+      nearestDistance = distance;
+      nearest = row;
+    }
+  }
+  return nearest;
+}