react-cheminfo 0.9.0 → 0.11.0

package/src/scatter/ui/index.ts

@@ -0,0 +1,123 @@
+/**
+ * A scatter plot the reader can interrogate: a lasso to select a crowd, a card
+ * on the point under the pointer, an outline per group, and the grid of every
+ * pair of axes.
+ *
+ * Nothing here knows what produced the coordinates. The same plot draws a
+ * principal component map, a UMAP embedding and a k-means run with its
+ * centroids, which is why it is its own domain rather than part of the viewer
+ * that happens to use it first.
+ */
+
+export type { ScatterEllipseLayerProps } from './ScatterEllipseLayer.tsx';
+export { ScatterEllipseLayer } from './ScatterEllipseLayer.tsx';
+export type { ScatterLabelLayerProps } from './ScatterLabelLayer.tsx';
+export { ScatterLabelLayer } from './ScatterLabelLayer.tsx';
+export type {
+  ScatterMarkLayerProps,
+  ScatterPixelMark,
+} from './ScatterMarkLayer.tsx';
+export { ScatterMarkLayer } from './ScatterMarkLayer.tsx';
+export { ScatterMatrix } from './ScatterMatrix.tsx';
+export type { ScatterMatrixCellProps } from './ScatterMatrixCell.tsx';
+export { ScatterMatrixCell } from './ScatterMatrixCell.tsx';
+export type {
+  ScatterMatrixDiagonalProps,
+  ScatterMatrixGrid,
+} from './ScatterMatrixDiagonal.tsx';
+export { ScatterMatrixDiagonal } from './ScatterMatrixDiagonal.tsx';
+export type {
+  ScatterGroup,
+  ScatterMarker,
+  ScatterPlotProps,
+} from './ScatterPlot.tsx';
+export { ScatterPlot } from './ScatterPlot.tsx';
+export type { ScatterPointLayerProps } from './ScatterPointLayer.tsx';
+export { ScatterPointLayer } from './ScatterPointLayer.tsx';
+export type {
+  FrameSlot,
+  GestureModifiers,
+  LassoGesture,
+  LassoGestureOptions,
+  ScatterSurfaceProps,
+} from './lassoGesture.ts';
+export {
+  DEFAULT_LASSO_MIN_DISTANCE,
+  MINIMUM_RING_VERTICES,
+  capturePointer,
+  dropFrame,
+  modifierMode,
+  scheduleFrame,
+  surfacePosition,
+} from './lassoGesture.ts';
+export type {
+  ScatterGroupSpread,
+  ScatterGroupSpreadOptions,
+} from './scatterGroupSpread.ts';
+export type { LabelBox } from './scatterLabelBoxes.ts';
+export {
+  LabelBoxField,
+  SCATTER_GROUP_LABEL_SIZE,
+  SCATTER_LABEL_SIZE,
+  labelBoxHeight,
+  labelBoxWidth,
+  labelBoxesOverlap,
+} from './scatterLabelBoxes.ts';
+export type { ScatterLabelInk, ScatterPixelLabel } from './scatterLabels.ts';
+export { scatterGroupLabels, scatterPointLabels } from './scatterLabels.ts';
+export type {
+  PlacedScatterLabel,
+  ScatterLabelPlacementOptions,
+} from './scatterLabelPlacement.ts';
+export { placeScatterLabels } from './scatterLabelPlacement.ts';
+export {
+  scatterGroupSpread,
+  scatterPairEllipse,
+} from './scatterGroupSpread.ts';
+export { scatterMatrixDots } from './scatterMatrixDots.tsx';
+export {
+  SCATTER_MATRIX_GAP,
+  SCATTER_MATRIX_MARGINS,
+  SCATTER_MATRIX_MOST_AXES,
+  SCATTER_MATRIX_ROOM,
+  SCATTER_MATRIX_SMALLEST_OUTLINE,
+  SCATTER_MATRIX_SMALLEST_PLOT,
+  scatterMatrixAxesThatFit,
+  scatterMatrixPlotSide,
+  scatterMatrixTickCount,
+} from './scatterMatrixLayout.ts';
+export { scatterMatrixOutlines } from './scatterMatrixOutlines.tsx';
+export type {
+  ScatterMatrixAxis,
+  ScatterMatrixProps,
+} from './scatterMatrixProps.ts';
+export type { ScatterOutlineInk } from './scatterOutlineShape.tsx';
+export {
+  SCATTER_OUTLINE_FILL_OPACITY,
+  scatterOutlineShape,
+} from './scatterOutlineShape.tsx';
+export { useLassoGesture } from './useLassoGesture.ts';
+export type {
+  HoverAnchor,
+  PointHoverApi,
+  PointHoverOptions,
+} from './usePointHover.ts';
+export { DEFAULT_HOVER_RADIUS, usePointHover } from './usePointHover.ts';
+export type { ScatterFrame, ScatterFrameOptions } from './useScatterFrame.ts';
+export { useScatterFrame } from './useScatterFrame.ts';
+export type {
+  ScatterInteractionApi,
+  ScatterInteractionOptions,
+} from './useScatterInteraction.ts';
+export { useScatterInteraction } from './useScatterInteraction.ts';
+export type {
+  ScatterKeyboardApi,
+  ScatterKeyboardOptions,
+} from './useScatterKeyboard.ts';
+export { useScatterKeyboard } from './useScatterKeyboard.ts';
+export type {
+  ScatterSelectionApi,
+  ScatterSelectionOptions,
+  SelectionChange,
+} from './useScatterSelection.ts';
+export { useScatterSelection } from './useScatterSelection.ts';

package/src/scatter/ui/lassoGesture.ts

@@ -0,0 +1,250 @@
+/**
+ * What a lasso is asked for, what it hands back, and the arithmetic behind the
+ * rectangle it is drawn on.
+ *
+ * Kept out of the hook the way `listNavigation` is kept out of its own: where
+ * the pointer is, which modifier wins and how a frame is booked are questions
+ * with one answer each, and none of them needs React to be read or checked.
+ */
+
+import type { CSSProperties, PointerEvent as ReactPointerEvent } from 'react';
+
+import type { LassoPath } from '../core/lassoPath.ts';
+import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
+
+/**
+ * What the transparent rectangle laid over a plot has to carry.
+ *
+ * One rectangle takes every gesture, rather than each dot carrying handlers of
+ * its own: two thousand `<circle>` elements with six listeners each is two
+ * thousand times the work on mount, and a hit test against a coordinate array
+ * is cheaper than one against the DOM. Spread the whole object, and give the
+ * rectangle a fill — a rectangle with none is never hit.
+ */
+export interface ScatterSurfaceProps {
+  /** Starts the drag and claims the pointer for the rest of it. */
+  onPointerDown: (event: ReactPointerEvent<Element>) => void;
+  /** Follows the pointer, at most once a frame. */
+  onPointerMove: (event: ReactPointerEvent<Element>) => void;
+  /** Ends the drag and commits what was drawn. */
+  onPointerUp: (event: ReactPointerEvent<Element>) => void;
+  /** Abandons the drag when the browser takes the pointer away. */
+  onPointerCancel: (event: ReactPointerEvent<Element>) => void;
+  /** Abandons it when the capture is lost for any other reason. */
+  onLostPointerCapture: (event: ReactPointerEvent<Element>) => void;
+  /** Tells a hover card the pointer has left, when no drag is running. */
+  onPointerLeave: (event: ReactPointerEvent<Element>) => void;
+  /** Keeps a finger from scrolling the page, and names the pointer. */
+  style: CSSProperties;
+}
+
+/** What `useLassoGesture` needs. */
+export interface LassoGestureOptions {
+  /**
+   * Whether a drag draws an outline. The pointer is still followed when it is
+   * off, so a plot with no lasso still has a hover card.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Whether a finger draws rather than scrolling the page. Off, because a
+   * figure that traps the page scroll on a phone is the worse fault.
+   * @default false
+   */
+  touch?: boolean;
+  /**
+   * How far the pointer moves before a vertex is kept, in pixels.
+   * @default 3
+   */
+  minDistance?: number;
+  /**
+   * Where the rectangle's left edge sits in the space the points were measured
+   * in — the plot's `left`, since a plot is inset by its axes.
+   * @default 0
+   */
+  originX?: number;
+  /**
+   * Where its top edge sits, the plot's `top`.
+   * @default 0
+   */
+  originY?: number;
+  /**
+   * What a drag with no modifier held does to the selection.
+   * @default 'replace'
+   */
+  mode?: ScatterSelectionMode;
+  /**
+   * Called on every frame the outline grew, and once with `null` when the drag
+   * ends — so whatever was drawn from the growing path is cleared by the same
+   * hand that set it.
+   * @default undefined
+   */
+  onDraw?: (path: LassoPath | null, mode: ScatterSelectionMode) => void;
+  /**
+   * Called when a ring was released. The path is reused by the next drag, so
+   * read it before returning.
+   * @default undefined
+   */
+  onComplete?: (path: LassoPath, mode: ScatterSelectionMode) => void;
+  /**
+   * Called instead when the pointer went up having drawn nothing worth
+   * closing — a click, which a scatter reads as picking one point.
+   * @default undefined
+   */
+  onClick?: (x: number, y: number, mode: ScatterSelectionMode) => void;
+  /**
+   * Called with every position the rectangle saw, coalesced to one a frame,
+   * and whether a drag was running. A hover test belongs here, where it pays
+   * the throttle the outline is already paying.
+   * @default undefined
+   */
+  onMove?: (x: number, y: number, drawing: boolean) => void;
+  /**
+   * Called when the pointer leaves with no drag running.
+   * @default undefined
+   */
+  onLeave?: () => void;
+}
+
+/** A lasso being drawn, or waiting to be. */
+export interface LassoGesture {
+  /** Spread onto the rectangle laid over the plot. */
+  surface: ScatterSurfaceProps;
+  /** Whether a drag is under way. */
+  drawing: boolean;
+  /** The outline so far as an SVG `d`, left open; `''` between drags. */
+  pathData: string;
+  /**
+   * What releasing now would do to the selection. It is reported while the
+   * drag runs, so a caption can say `Adding to the selection` from the moment
+   * Shift goes down rather than after the fact.
+   */
+  mode: ScatterSelectionMode;
+  /** Abandon the drag from outside — what Escape is wired to. */
+  cancel: () => void;
+}
+
+/** The modifier keys the hand making a gesture is holding. */
+export interface GestureModifiers {
+  /** Whether Alt is down, which always removes. */
+  altKey: boolean;
+  /** Whether Shift is down, which always adds. */
+  shiftKey: boolean;
+}
+
+/** Where a booked animation frame is remembered between calls. */
+export interface FrameSlot {
+  /** The frame's handle, or `null` when none is booked. */
+  current: number | null;
+}
+
+/** How far the pointer travels before a vertex is worth keeping, in pixels. */
+export const DEFAULT_LASSO_MIN_DISTANCE = 3;
+
+/** Vertices a stroke needs before it is a ring rather than a click. */
+export const MINIMUM_RING_VERTICES = 3;
+
+/**
+ * The mode a drag is running in, from the keys the hand is holding.
+ *
+ * Alt removes and Shift adds whatever the plot's resting mode is, so both
+ * gestures mean the same thing on every figure. Alt wins a hand holding both,
+ * because taking points out is the more deliberate of the two asks.
+ * @param event - The pointer event, for its modifier keys.
+ * @param resting - What a drag with neither key held does.
+ * @returns The mode a release would use.
+ */
+export function modifierMode(
+  event: GestureModifiers,
+  resting: ScatterSelectionMode,
+): ScatterSelectionMode {
+  if (event.altKey) return 'remove';
+  if (event.shiftKey) return 'add';
+  return resting;
+}
+
+/** The little of an event that says where on the surface it happened. */
+export interface SurfaceEvent {
+  /** The element the handler is on, which is the rectangle being measured. */
+  currentTarget: Element;
+  /** Where the event happened, in the window. */
+  clientX: number;
+  /** Where the event happened, in the window. */
+  clientY: number;
+}
+
+/**
+ * Where the pointer is, in the space the points were measured in.
+ *
+ * Measured from the rectangle rather than from the page and then shifted by
+ * the plot's own corner, so the answer can be compared with a point coordinate
+ * without the caller mapping anything. An element that cannot be measured —
+ * a server render — reports the corner itself rather than throwing.
+ *
+ * It takes the three fields it actually reads rather than a pointer event,
+ * because a double click arrives as a mouse event and asks the same question.
+ * @param event - The event, or anything carrying those three fields.
+ * @param originX - The rectangle's left edge in the points' space.
+ * @param originY - Its top edge.
+ * @returns The position, in pixels.
+ */
+export function surfacePosition(
+  event: SurfaceEvent,
+  originX: number,
+  originY: number,
+): { x: number; y: number } {
+  const target = event.currentTarget;
+  if (typeof target?.getBoundingClientRect !== 'function') {
+    return { x: originX, y: originY };
+  }
+  const box = target.getBoundingClientRect();
+  return {
+    x: event.clientX - box.left + originX,
+    y: event.clientY - box.top + originY,
+  };
+}
+
+/**
+ * Claim the pointer, so a drag that wanders off the figure keeps drawing.
+ * @param event - The pointer event that started the drag.
+ */
+export function capturePointer(event: ReactPointerEvent<Element>): void {
+  const target = event.currentTarget;
+  if (typeof target?.setPointerCapture !== 'function') return;
+  try {
+    target.setPointerCapture(event.pointerId);
+  } catch {
+    // The pointer was already gone; the drag ends through the same one path.
+  }
+}
+
+/**
+ * Book a frame to do the work on, unless one is already booked.
+ *
+ * Where there is no `requestAnimationFrame` — a server render, a test — the
+ * work is done at once. Coalescing is a saving, never a requirement, and a
+ * gesture that only worked in a browser with a frame clock would be untestable
+ * as well as fragile.
+ * @param frameRef - Where the booking is held.
+ * @param run - What the frame should do.
+ */
+export function scheduleFrame(frameRef: FrameSlot, run: () => void): void {
+  if (frameRef.current !== null) return;
+  if (typeof requestAnimationFrame === 'function') {
+    frameRef.current = requestAnimationFrame(run);
+  } else {
+    run();
+  }
+}
+
+/**
+ * Drop a frame that was booked and is no longer wanted.
+ * @param frameRef - Where the booking is held; emptied either way.
+ */
+export function dropFrame(frameRef: FrameSlot): void {
+  if (frameRef.current === null) return;
+  if (typeof cancelAnimationFrame === 'function') {
+    cancelAnimationFrame(frameRef.current);
+  }
+  frameRef.current = null;
+}

package/src/scatter/ui/scatterGroupSpread.ts

@@ -0,0 +1,206 @@
+/**
+ * Every group's outline over every pair of axes, measured once.
+ *
+ * A pair grid asks the same question of a group thirty-six times, and calling
+ * `confidenceEllipse` per cell would gather that group's points into a fresh
+ * array of objects each time — n² allocations to draw n axes, over the same
+ * samples. The averages and the pairwise covariances say everything an outline
+ * needs, they come out of two passes over the scores read where they stand,
+ * and a cell then reads four numbers out of the block.
+ */
+
+import type { MatrixLike } from '../../chart/core/matrix.ts';
+import type {
+  ConfidenceEllipse,
+  EllipseCovariance,
+  EllipseSize,
+} from '../core/confidenceEllipse.ts';
+import {
+  ellipseAxes,
+  ellipseStandardDeviations,
+} from '../core/confidenceEllipse.ts';
+
+/** How every group is spread over the axes a grid lays out. */
+export interface ScatterGroupSpread {
+  /** How many leading axes each block covers. */
+  axes: number;
+  /** How many groups it holds. */
+  groups: number;
+  /** How many rows went into each group, in group order. */
+  counts: Int32Array;
+  /** Each group's average along each axis, at `group * axes + axis`. */
+  means: Float64Array;
+  /**
+   * How each group varies between two axes, at `(group * axes + a) * axes + b`
+   * and again at the transposed position, so a cell reads either way round.
+   */
+  covariances: Float64Array;
+  /** How far out an outline is drawn, in standard deviations. */
+  standardDeviations: number;
+  /** How many rows a group needs before it is outlined at all. */
+  minimumPoints: number;
+}
+
+/** How {@link scatterGroupSpread} measures the groups. */
+export interface ScatterGroupSpreadOptions {
+  /** The coordinates: one row per sample, one column per axis, read in place. */
+  scores: MatrixLike;
+  /** Which group each row belongs to; a row outside the range is left out. */
+  groupOf: ArrayLike<number>;
+  /** How many groups there are. */
+  groups: number;
+  /** How many leading axes to measure over. */
+  axes: number;
+  /**
+   * How large the outlines are drawn.
+   * @default { kind: 'coverage', probability: 0.95 }
+   */
+  size?: EllipseSize;
+  /**
+   * How many rows a group needs before it is outlined at all.
+   * @default 3
+   */
+  minimumPoints?: number;
+}
+
+/**
+ * Measure every group over every laid-out axis, in two passes.
+ *
+ * A row missing a value in any one of the axes is left out of the group
+ * altogether rather than only out of the cells that use that axis: an outline
+ * that quietly covered a different set of samples in each cell would make the
+ * grid disagree with itself, and a reader comparing two cells has no way to
+ * see it. The spread uses the `n - 1` divisor, as `confidenceEllipse` does, so
+ * a group outlined here and the same group outlined on the map come out the
+ * same size.
+ * @param options - See {@link ScatterGroupSpreadOptions}.
+ * @returns The block, whose `counts` are what a caller reports as too small to outline.
+ */
+export function scatterGroupSpread(
+  options: ScatterGroupSpreadOptions,
+): ScatterGroupSpread {
+  const { scores, groupOf, size = DEFAULT_SIZE, minimumPoints = 3 } = options;
+  const groups = Math.max(0, Math.trunc(options.groups));
+  const axes = Math.max(0, Math.min(Math.trunc(options.axes), scores.columns));
+  const counts = new Int32Array(groups);
+  const means = new Float64Array(groups * axes);
+  const covariances = new Float64Array(groups * axes * axes);
+  const spread: ScatterGroupSpread = {
+    axes,
+    groups,
+    counts,
+    means,
+    covariances,
+    standardDeviations: ellipseStandardDeviations(size),
+    minimumPoints,
+  };
+  if (groups === 0 || axes === 0) return spread;
+
+  for (let row = 0; row < scores.rows; row++) {
+    const group = groupAt(groupOf, row, groups);
+    if (group < 0 || !finiteRow(scores, row, axes)) continue;
+    counts[group] = (counts[group] ?? 0) + 1;
+    const base = group * axes;
+    for (let axis = 0; axis < axes; axis++) {
+      means[base + axis] = (means[base + axis] ?? 0) + scores.get(row, axis);
+    }
+  }
+  for (let group = 0; group < groups; group++) {
+    const count = counts[group] ?? 0;
+    if (count === 0) continue;
+    const base = group * axes;
+    for (let axis = 0; axis < axes; axis++) {
+      means[base + axis] = (means[base + axis] ?? 0) / count;
+    }
+  }
+
+  // One scratch row of deviations, reused for every sample: the alternative is
+  // reading each value twice per pair, which is axes² reads instead of axes.
+  const away = new Float64Array(axes);
+  for (let row = 0; row < scores.rows; row++) {
+    const group = groupAt(groupOf, row, groups);
+    if (group < 0 || !finiteRow(scores, row, axes)) continue;
+    const base = group * axes;
+    for (let axis = 0; axis < axes; axis++) {
+      away[axis] = scores.get(row, axis) - (means[base + axis] ?? 0);
+    }
+    const block = group * axes * axes;
+    for (let a = 0; a < axes; a++) {
+      const first = away[a] ?? 0;
+      for (let b = 0; b < axes; b++) {
+        const cell = block + a * axes + b;
+        covariances[cell] = (covariances[cell] ?? 0) + first * (away[b] ?? 0);
+      }
+    }
+  }
+  for (let group = 0; group < groups; group++) {
+    const divisor = (counts[group] ?? 0) - 1;
+    if (divisor < 1) continue;
+    const block = group * axes * axes;
+    for (let cell = 0; cell < axes * axes; cell++) {
+      covariances[block + cell] = (covariances[block + cell] ?? 0) / divisor;
+    }
+  }
+  return spread;
+}
+
+/**
+ * One group's outline for one pair of axes, in data units.
+ *
+ * The two-by-two block cut out of the covariances is a covariance in its own
+ * right — that is what makes the grid affordable — so it decomposes into
+ * radii and a tilt exactly as a pair measured on its own would.
+ * @param spread - The block, from {@link scatterGroupSpread}.
+ * @param group - Which group.
+ * @param xAxis - The axis along the foot of the cell.
+ * @param yAxis - The axis up its side.
+ * @returns The outline, or `null` when the group is too small to have a shape, when either axis is outside the block, or when the requested size is unbounded.
+ */
+export function scatterPairEllipse(
+  spread: ScatterGroupSpread,
+  group: number,
+  xAxis: number,
+  yAxis: number,
+): ConfidenceEllipse | null {
+  const { axes, groups, counts, means, covariances } = spread;
+  const { minimumPoints, standardDeviations } = spread;
+  if (group < 0 || group >= groups) return null;
+  if (xAxis < 0 || yAxis < 0 || xAxis >= axes || yAxis >= axes) return null;
+  const count = counts[group] ?? 0;
+  if (count < Math.max(2, minimumPoints)) return null;
+
+  const base = group * axes;
+  const block = group * axes * axes;
+  const covariance: EllipseCovariance = {
+    xx: covariances[block + xAxis * axes + xAxis] ?? 0,
+    xy: covariances[block + xAxis * axes + yAxis] ?? 0,
+    yy: covariances[block + yAxis * axes + yAxis] ?? 0,
+  };
+  const { rx, ry, angle } = ellipseAxes(covariance, standardDeviations);
+  const cx = means[base + xAxis] ?? 0;
+  const cy = means[base + yAxis] ?? 0;
+  if (!Number.isFinite(rx) || !Number.isFinite(ry)) return null;
+  if (!Number.isFinite(cx) || !Number.isFinite(cy)) return null;
+  return { cx, cy, rx, ry, angle, count, covariance };
+}
+
+/** What a group is outlined at when the caller says nothing. */
+const DEFAULT_SIZE: EllipseSize = { kind: 'coverage', probability: 0.95 };
+
+function groupAt(
+  groupOf: ArrayLike<number>,
+  row: number,
+  groups: number,
+): number {
+  const raw = groupOf[row];
+  if (raw === undefined || !Number.isFinite(raw)) return -1;
+  const group = Math.trunc(raw);
+  return group < 0 || group >= groups ? -1 : group;
+}
+
+function finiteRow(scores: MatrixLike, row: number, axes: number): boolean {
+  for (let axis = 0; axis < axes; axis++) {
+    if (!Number.isFinite(scores.get(row, axis))) return false;
+  }
+  return true;
+}