react-cheminfo 0.15.0 → 0.17.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,211 @@
+/**
+ * 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;
+  /** Which of that axis's intervals is being written, or `-1` for a new one. */
+  index: number;
+  /** 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;
+
+/**
+ * How close to an axis's own end a band edge counts as standing on it.
+ *
+ * Half a pixel is below anything a pointer can aim at, and the two ends are
+ * where the rows a reader most wants sit: the axes end exactly on the data,
+ * so the extreme row is drawn on the end itself.
+ */
+const END_REACH = 0.5;
+
+/**
+ * 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';
+}
+
+/** Which of an axis's bands a press took hold of, and by what. */
+export interface ParallelBrushTarget {
+  /** The band, as an index into the list, or `-1` when none was under it. */
+  index: number;
+  /** What the press took hold of. */
+  grip: ParallelBrushGrip;
+}
+
+/** Nothing under the press, so it starts a band of its own. */
+const NEW_BAND: ParallelBrushTarget = { index: -1, grip: 'create' };
+
+/**
+ * Which band a press at that height took hold of, on an axis carrying several.
+ * @param y - Where the press landed, in pixels from the top of the drawing area.
+ * @param bands - The bands on that axis, in any order.
+ * @returns The band and the grip. An edge wins over the band it belongs to and
+ * over any band it lies inside, so two bands dragged flush against each other
+ * can still be pulled apart; a press on bare axis starts a new band.
+ */
+export function parallelBrushTarget(
+  y: number,
+  bands: readonly ParallelBand[],
+): ParallelBrushTarget {
+  let nearest = NEW_BAND;
+  let nearestDistance = PARALLEL_BRUSH_HANDLE_REACH;
+  for (let index = 0; index < bands.length; index++) {
+    const band = bands[index] as ParallelBand;
+    const toTop = Math.abs(y - band.top);
+    if (toTop <= nearestDistance) {
+      nearestDistance = toTop;
+      nearest = { index, grip: 'top' };
+    }
+    const toBottom = Math.abs(y - band.bottom);
+    if (toBottom <= nearestDistance) {
+      nearestDistance = toBottom;
+      nearest = { index, grip: 'bottom' };
+    }
+  }
+  if (nearest !== NEW_BAND) return nearest;
+  for (let index = 0; index < bands.length; index++) {
+    const band = bands[index] as ParallelBand;
+    if (y > band.top && y < band.bottom) return { index, grip: 'move' };
+  }
+  return NEW_BAND;
+}
+
+/**
+ * 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. An edge
+ * standing on an end of the axis reports that end verbatim: inverting the
+ * placement is not exact, and one ulp is enough to drop the row the axis ends
+ * on from its own full-range brush.
+ */
+export function parallelRangeOf(
+  band: ParallelBand,
+  axis: ParallelAxisLayout,
+): ParallelRange {
+  const low =
+    band.bottom >= parallelValueToY(axis.min, axis) - END_REACH
+      ? axis.min
+      : parallelYToValue(band.bottom, axis);
+  const high =
+    band.top <= parallelValueToY(axis.max, axis) + END_REACH
+      ? axis.max
+      : 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,131 @@
+/**
+ * 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.
+ *
+ * An axis carrying several intervals keeps a row that falls in any of them,
+ * while a row has to be kept by every brushed axis — union down an axis,
+ * intersection across them, which is the only reading under which brushing a
+ * second axis can never widen what the first one left.
+ */
+
+import { parallelRangeList } from './parallelSelection.ts';
+import type {
+  ParallelAxis,
+  ParallelRange,
+  ParallelRanges,
+} from './parallelTypes.ts';
+
+/** One axis's intervals, ready to be tested row by row. */
+interface ActiveRange {
+  /** The column being tested. */
+  values: ArrayLike<number>;
+  /** The lowest value each interval keeps. */
+  minimum: Float64Array;
+  /** The highest value each interval keeps. */
+  maximum: Float64Array;
+}
+
+/**
+ * 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];
+}
+
+/**
+ * Whether one value falls inside any of an axis's intervals.
+ * @param ranges - The intervals that axis keeps.
+ * @param value - The value to test.
+ * @returns Whether any of them keeps it. An axis keeping nothing keeps every
+ * value, which is what an unbrushed axis means.
+ */
+export function parallelSelectionKeeps(
+  ranges: readonly ParallelRange[],
+  value: number,
+): boolean {
+  if (ranges.length === 0) return true;
+  for (const range of ranges) {
+    if (value >= range[0] && value <= range[1]) return true;
+  }
+  return false;
+}
+
+/**
+ * Which rows every brush keeps at once.
+ * @param axes - The axes, whose ids the intervals are keyed by.
+ * @param ranges - What each axis keeps: one interval, several, or 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 list = parallelRangeList(ranges[axis.id]);
+    if (list.length === 0) continue;
+    const minimum = new Float64Array(list.length);
+    const maximum = new Float64Array(list.length);
+    for (let index = 0; index < list.length; index++) {
+      const range = list[index] as ParallelRange;
+      minimum[index] = Math.min(range[0], range[1]);
+      maximum[index] = Math.max(range[0], range[1]);
+    }
+    active.push({ values: axis.values, minimum, maximum });
+  }
+  if (active.length === 0) return included;
+
+  for (const range of active) {
+    const rows = Math.min(count, range.values.length);
+    const intervals = range.minimum.length;
+    for (let row = 0; row < rows; row++) {
+      if (included[row] === 0) continue;
+      const value = range.values[row] as number;
+      let kept = false;
+      for (let index = 0; index < intervals; index++) {
+        if (
+          value >= (range.minimum[index] as number) &&
+          value <= (range.maximum[index] as number)
+        ) {
+          kept = true;
+          break;
+        }
+      }
+      if (!kept) 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;
+}