react-cheminfo 0.9.0 → 0.11.0

package/src/scatter/core/confidenceEllipse.ts

@@ -0,0 +1,230 @@
+/**
+ * The outline that summarises where a group of samples sits on a scatter plot.
+ *
+ * Everything here is in data units. Turning one of these into something an SVG
+ * can draw is `projectEllipse`, which has to be a separate step because the two
+ * axes rarely carry the same number of pixels per unit.
+ */
+
+import { standardDeviationsForCoverage } from './ellipseCoverage.ts';
+
+/**
+ * A smaller eigenvalue below this share of the larger one is read as zero.
+ *
+ * A group whose spread across the major axis is under a millionth of its
+ * spread along it is collinear for any purpose a plot has, and the rounding of
+ * the covariance alone reaches that far: the nine points on a straight line
+ * used in the tests leave a residue of about 5e-17 where the exact answer is
+ * 0. Without the floor those points would draw a hairline ellipse on one
+ * machine and a segment on the next.
+ */
+const COLLINEAR_FLOOR = 1e-12;
+
+/** A point of a cloud, or of an outline drawn around one, in data units. */
+export interface EllipsePoint {
+  /** Position along the horizontal axis. */
+  x: number;
+  /** Position along the vertical axis. */
+  y: number;
+}
+
+/** An outline drawn to hold a share of its group. */
+export interface EllipseCoverageSize {
+  /** Marks which of the two ways of asking for a size this is. */
+  kind: 'coverage';
+  /** The share of the group to enclose, from 0 to 1. */
+  probability: number;
+}
+
+/** An outline drawn at a multiple of its group's spread. */
+export interface EllipseStandardDeviationSize {
+  /** Marks which of the two ways of asking for a size this is. */
+  kind: 'standardDeviations';
+  /** How far out to draw, in standard deviations. */
+  standardDeviations: number;
+}
+
+/**
+ * How large a group outline is drawn.
+ *
+ * A share is what a reader understands without being taught, and it is the
+ * only mode the shipped control offers; the multiple is kept because a site
+ * whose audience already reads standard deviations should not have to convert
+ * one into the other by hand.
+ */
+export type EllipseSize = EllipseCoverageSize | EllipseStandardDeviationSize;
+
+/** How a cloud is spread, as the three distinct entries of its covariance. */
+export interface EllipseCovariance {
+  /** The spread along the horizontal axis. */
+  xx: number;
+  /** How the two axes move together; zero when they are unrelated. */
+  xy: number;
+  /** The spread along the vertical axis. */
+  yy: number;
+}
+
+/** A group outline, in data units. */
+export interface ConfidenceEllipse {
+  /** Centre of the outline, which is the group's average. */
+  cx: number;
+  /** Centre of the outline, which is the group's average. */
+  cy: number;
+  /** Semi-major axis length. */
+  rx: number;
+  /** Semi-minor axis length; exactly `0` when the group is collinear. */
+  ry: number;
+  /** Rotation of the major axis, in radians counter-clockwise, in `(-π/2, π/2]`. */
+  angle: number;
+  /** How many points went into it, the ones that were not finite left out. */
+  count: number;
+  /** The spread the outline was built from, before any size was applied. */
+  covariance: EllipseCovariance;
+}
+
+/** How {@link confidenceEllipse} measures a group. */
+export interface ConfidenceEllipseOptions {
+  /**
+   * How large to draw the outline.
+   * @default { kind: 'coverage', probability: 0.95 }
+   */
+  size?: EllipseSize;
+  /**
+   * How many finite points a group needs before it is outlined at all. Below
+   * it the shape says more about the sample than about the group. Fewer than
+   * two is read as two, because one point has no spread to measure.
+   * @default 3
+   */
+  minimumPoints?: number;
+}
+
+/**
+ * The outline that summarises a group of samples.
+ *
+ * Points that are not finite are skipped rather than poisoning the average, so
+ * a column with a few gaps still describes its group; `count` reports how many
+ * were actually used. The spread is measured with the `n - 1` divisor, which
+ * is what makes the outline an estimate of the group rather than a statement
+ * about the handful of samples that happen to have been measured.
+ * @param points - The group's samples, in data units.
+ * @param options - See {@link ConfidenceEllipseOptions}.
+ * @returns The outline, or `null` when the group is too small to have a shape, or when its coordinates are so large that squaring them overflows, or when the requested size is unbounded.
+ */
+export function confidenceEllipse(
+  points: readonly EllipsePoint[],
+  options: ConfidenceEllipseOptions = {},
+): ConfidenceEllipse | null {
+  const { size = { kind: 'coverage', probability: 0.95 }, minimumPoints = 3 } =
+    options;
+
+  let count = 0;
+  let sumX = 0;
+  let sumY = 0;
+  for (const point of points) {
+    if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) continue;
+    count++;
+    sumX += point.x;
+    sumY += point.y;
+  }
+  if (count < Math.max(2, minimumPoints)) return null;
+
+  const cx = sumX / count;
+  const cy = sumY / count;
+  let spreadX = 0;
+  let together = 0;
+  let spreadY = 0;
+  for (const point of points) {
+    if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) continue;
+    const dx = point.x - cx;
+    const dy = point.y - cy;
+    spreadX += dx * dx;
+    together += dx * dy;
+    spreadY += dy * dy;
+  }
+
+  const divisor = count - 1;
+  const covariance: EllipseCovariance = {
+    xx: spreadX / divisor,
+    xy: together / divisor,
+    yy: spreadY / divisor,
+  };
+  if (
+    !Number.isFinite(cx) ||
+    !Number.isFinite(cy) ||
+    !Number.isFinite(covariance.xx) ||
+    !Number.isFinite(covariance.xy) ||
+    !Number.isFinite(covariance.yy)
+  ) {
+    return null;
+  }
+
+  const { rx, ry, angle } = ellipseAxes(
+    covariance,
+    ellipseStandardDeviations(size),
+  );
+  if (!Number.isFinite(rx) || !Number.isFinite(ry)) return null;
+  return { cx, cy, rx, ry, angle, count, covariance };
+}
+
+/**
+ * The semi-axes and the rotation that a covariance describes.
+ *
+ * The shape of an outline is the eigen-decomposition of a symmetric two by two
+ * matrix, which has a closed form and so never needs an iterative solver. It
+ * is public because the same three numbers are what turns any covariance into
+ * something drawable — one measured elsewhere, or one already mapped into
+ * pixels.
+ * @param covariance - How the cloud is spread.
+ * @param standardDeviations - How far out to measure. Defaults to `1`.
+ * @returns The two semi-axis lengths and the rotation of the major one, in radians, in `(-π/2, π/2]`. A collinear cloud gives `ry` of exactly `0`, and one with no spread at all gives an angle of `0` because it has no direction to report.
+ */
+export function ellipseAxes(
+  covariance: EllipseCovariance,
+  standardDeviations = 1,
+): Pick<ConfidenceEllipse, 'rx' | 'ry' | 'angle'> {
+  const { xx, xy, yy } = covariance;
+  const middle = (xx + yy) / 2;
+  const half = (xx - yy) / 2;
+  const radius = Math.hypot(half, xy);
+  const major = middle + radius;
+  let minor = middle - radius;
+  if (!(minor > major * COLLINEAR_FLOOR)) minor = 0;
+  return {
+    rx: standardDeviations * Math.sqrt(major),
+    ry: standardDeviations * Math.sqrt(minor),
+    angle: majorAxisAngle(xx, xy, yy, major),
+  };
+}
+
+function majorAxisAngle(
+  xx: number,
+  xy: number,
+  yy: number,
+  major: number,
+): number {
+  // With no cross term the axes already are the eigenvectors, and asking
+  // `atan2` would only turn the exact answer into a rounded one.
+  if (xy === 0) return xx >= yy ? 0 : Math.PI / 2;
+  // `major - xx` is never negative, so this lands in [0, π] and a negative
+  // cross term arrives half a turn away from the direction actually wanted.
+  const angle = Math.atan2(major - xx, xy);
+  return angle > Math.PI / 2 ? angle - Math.PI : angle;
+}
+
+/**
+ * How far out an outline of a given size is drawn.
+ *
+ * Public because a figure that measures its groups itself — a pair grid
+ * decomposing one shared block of covariances rather than calling
+ * {@link confidenceEllipse} per cell — still has to honour the same size the
+ * map was asked for, and a second reading of `EllipseSize` would be a second
+ * place for the two to drift apart.
+ * @param size - How large the outline was asked to be.
+ * @returns The number of standard deviations, never below zero.
+ */
+export function ellipseStandardDeviations(size: EllipseSize): number {
+  if (size.kind === 'standardDeviations') {
+    return Math.max(size.standardDeviations, 0);
+  }
+  return standardDeviationsForCoverage(size.probability);
+}

package/src/scatter/core/ellipseCoverage.ts

@@ -0,0 +1,46 @@
+/**
+ * How far out a group outline is drawn, and how much of the group it then
+ * holds.
+ *
+ * The two directions are exact inverses of one another, so a legend can quote
+ * a share and a control can offer standard deviations without either of them
+ * keeping a table of numbers that would drift apart.
+ */
+
+/**
+ * The share of a two-dimensional normal cloud that falls inside the ellipse
+ * drawn at a number of standard deviations.
+ *
+ * Not the 68, 95 and 99.7 percent that a single measurement is quoted with:
+ * those describe an interval on one axis, while an ellipse has to hold a point
+ * in both directions at once. One, two and three standard deviations therefore
+ * keep about 39, 86 and 99 percent of the cloud, and writing the
+ * one-dimensional figures beside a map is the usual way a scatter legend comes
+ * to promise more than its outlines contain.
+ * @param standardDeviations - How far out the ellipse is drawn.
+ * @returns The share, from 0 to 1. Zero for anything at or below zero, since an ellipse of no size holds nothing.
+ */
+export function coverageForStandardDeviations(
+  standardDeviations: number,
+): number {
+  if (!Number.isFinite(standardDeviations)) {
+    return standardDeviations > 0 ? 1 : 0;
+  }
+  if (standardDeviations <= 0) return 0;
+  return 1 - Math.exp(-(standardDeviations * standardDeviations) / 2);
+}
+
+/**
+ * How far out to draw the ellipse that holds a share of a two-dimensional
+ * normal cloud.
+ *
+ * The inverse of {@link coverageForStandardDeviations}, which is what lets a
+ * control offer `95% of samples` and still hand the geometry a radius.
+ * @param coverage - The share of the cloud to enclose, from 0 to 1.
+ * @returns The number of standard deviations. Zero at or below zero, and infinite at or above one, because no finite ellipse holds every point of a cloud with unbounded tails.
+ */
+export function standardDeviationsForCoverage(coverage: number): number {
+  if (!Number.isFinite(coverage) || coverage <= 0) return 0;
+  if (coverage >= 1) return Number.POSITIVE_INFINITY;
+  return Math.sqrt(-2 * Math.log(1 - coverage));
+}

package/src/scatter/core/ellipseProjection.ts

@@ -0,0 +1,126 @@
+/**
+ * Putting a data-space outline on the screen.
+ *
+ * Kept apart from `confidenceEllipse` because the measurement is a property of
+ * the samples and the projection is a property of the plot: the same outline
+ * is drawn again at every zoom and every resize, and only this half has to be
+ * redone.
+ */
+
+import type { ChartScale } from '../../chart/core/chartScale.ts';
+
+import type { ConfidenceEllipse, EllipsePoint } from './confidenceEllipse.ts';
+import { ellipseAxes } from './confidenceEllipse.ts';
+
+const HALF_TURN_DEGREES = 180;
+const DEFAULT_STEPS = 64;
+const MINIMUM_STEPS = 3;
+
+/** An ellipse ready to be handed to an SVG `<ellipse>` element. */
+export interface PixelEllipse {
+  /** Centre of the ellipse, in pixels. */
+  cx: number;
+  /** Centre of the ellipse, in pixels. */
+  cy: number;
+  /** Semi-major axis length, in pixels. */
+  rx: number;
+  /** Semi-minor axis length, in pixels; `0` for a perfectly collinear group. */
+  ry: number;
+  /** Rotation of the major axis, in degrees, for `transform="rotate(...)"`. */
+  angleDegrees: number;
+}
+
+/**
+ * Map a data-space ellipse onto the plot, keeping it exact when the two axes
+ * carry different numbers of pixels per data unit.
+ *
+ * Scaling `rx` and `ry` and reusing the data-space angle is wrong: an
+ * anisotropic map turns the ellipse by a different amount and changes the
+ * ratio of its axes — on a 640 by 400 plot of one measured cloud the naive
+ * route was 47 pixels out. The covariance is therefore transformed first and
+ * only then decomposed, which is exact for any linear axis and lets the
+ * browser draw a real curve at any zoom. Drawing a data-space ellipse inside a
+ * scaled `<g>` would be geometrically right and visually wrong, because SVG
+ * scales the stroke with the group.
+ * @param ellipse - An ellipse in data units.
+ * @param x - The plot's horizontal data-to-pixel mapping.
+ * @param y - Its vertical mapping, whose `factor` is negative.
+ * @returns The ellipse in pixels, or `null` when the mapping overflows.
+ */
+export function projectEllipse(
+  ellipse: ConfidenceEllipse,
+  x: ChartScale,
+  y: ChartScale,
+): PixelEllipse | null {
+  const cosine = Math.cos(ellipse.angle);
+  const sine = Math.sin(ellipse.angle);
+  const along = ellipse.rx * ellipse.rx;
+  const across = ellipse.ry * ellipse.ry;
+
+  // The quadratic form of the drawn ellipse, which shares its shape with a
+  // covariance and so decomposes the same way.
+  const xx = along * cosine * cosine + across * sine * sine;
+  const xy = (along - across) * cosine * sine;
+  const yy = along * sine * sine + across * cosine * cosine;
+
+  // Only the linear part of the mapping changes the shape; the offsets move
+  // the centre and nothing else. A negative vertical factor flips the cross
+  // term, which is what turns a counter-clockwise data angle into the
+  // clockwise one SVG rotates by.
+  const factors = x.factor * y.factor;
+  const projected = ellipseAxes({
+    xx: x.factor * x.factor * xx,
+    xy: factors * xy,
+    yy: y.factor * y.factor * yy,
+  });
+
+  const result: PixelEllipse = {
+    cx: x.offset + ellipse.cx * x.factor,
+    cy: y.offset + ellipse.cy * y.factor,
+    rx: projected.rx,
+    ry: projected.ry,
+    angleDegrees: (projected.angle * HALF_TURN_DEGREES) / Math.PI,
+  };
+  if (
+    !Number.isFinite(result.cx) ||
+    !Number.isFinite(result.cy) ||
+    !Number.isFinite(result.rx) ||
+    !Number.isFinite(result.ry) ||
+    !Number.isFinite(result.angleDegrees)
+  ) {
+    return null;
+  }
+  return result;
+}
+
+/**
+ * Sample the outline of a data-space ellipse, for a plot whose axes are not
+ * linear and where the shape is therefore no longer an ellipse on screen.
+ *
+ * Prefer {@link projectEllipse} on linear axes: it is exact, it is constant
+ * time, and the browser draws a curve rather than a polygon.
+ * @param ellipse - An ellipse in data units.
+ * @param steps - Points around the outline, at least three. Sixty-four keeps the flat sides under a third of a pixel on a 640 by 400 plot. Defaults to `64`.
+ * @returns The outline in data units, the first point not repeated at the end.
+ */
+export function ellipsePolygon(
+  ellipse: ConfidenceEllipse,
+  steps = DEFAULT_STEPS,
+): EllipsePoint[] {
+  const total = Number.isFinite(steps)
+    ? Math.max(MINIMUM_STEPS, Math.floor(steps))
+    : DEFAULT_STEPS;
+  const cosine = Math.cos(ellipse.angle);
+  const sine = Math.sin(ellipse.angle);
+  const outline: EllipsePoint[] = new Array(total);
+  for (let index = 0; index < total; index++) {
+    const turn = (2 * Math.PI * index) / total;
+    const along = ellipse.rx * Math.cos(turn);
+    const across = ellipse.ry * Math.sin(turn);
+    outline[index] = {
+      x: ellipse.cx + along * cosine - across * sine,
+      y: ellipse.cy + along * sine + across * cosine,
+    };
+  }
+  return outline;
+}

package/src/scatter/core/index.ts

@@ -0,0 +1,48 @@
+/**
+ * What a scatter plot has to work out before it can draw: which point the
+ * pointer is nearest, which points a lasso caught, and the outline that holds
+ * a given share of a group.
+ *
+ * The ellipse is the part worth reading twice. A group's outline is computed
+ * in the data's own units and drawn in pixels, and because the two axes rarely
+ * carry the same number of units per pixel, the rotation is not the same in
+ * both — which is why the outline is projected rather than handed to an SVG
+ * `<ellipse>` with a data-space angle.
+ */
+
+export type {
+  ConfidenceEllipse,
+  ConfidenceEllipseOptions,
+  EllipseCovariance,
+  EllipseCoverageSize,
+  EllipsePoint,
+  EllipseSize,
+  EllipseStandardDeviationSize,
+} from './confidenceEllipse.ts';
+export {
+  confidenceEllipse,
+  ellipseAxes,
+  ellipseStandardDeviations,
+} from './confidenceEllipse.ts';
+export {
+  coverageForStandardDeviations,
+  standardDeviationsForCoverage,
+} from './ellipseCoverage.ts';
+export type { PixelEllipse } from './ellipseProjection.ts';
+export { ellipsePolygon, projectEllipse } from './ellipseProjection.ts';
+export type { LassoPath } from './lassoPath.ts';
+export {
+  appendLassoPoint,
+  createLassoPath,
+  lassoPathData,
+  resetLassoPath,
+} from './lassoPath.ts';
+export { pointInPolygon, pointsInPolygon, polygonBounds } from './polygon.ts';
+export type { ScatterSelectionMode } from './scatterSelection.ts';
+export {
+  mergeScatterSelection,
+  scatterSelectedIndices,
+  scatterSelectionMask,
+} from './scatterSelection.ts';
+export type { PixelBounds, ScreenPoints } from './screenPoints.ts';
+export { nearestPointIndex, pointsWithinBounds } from './screenPoints.ts';

package/src/scatter/core/lassoPath.ts

@@ -0,0 +1,127 @@
+const DEFAULT_CAPACITY = 256;
+
+/**
+ * The outline a pointer has drawn, as a buffer that is only partly in use.
+ *
+ * The two arrays are grown by doubling and never shrunk, and `length` says how
+ * much of them is the path. A drag emits a pointer move every frame or more
+ * often; growing the buffer on each one would put a fresh pair of typed arrays
+ * in front of the collector sixty times a second, during the one interaction
+ * where a dropped frame is visible as a kink in the line the user is drawing.
+ */
+export interface LassoPath {
+  /** Horizontal position of each vertex; only the first `length` are in use. */
+  xs: Float64Array;
+  /** Vertical position of each vertex; only the first `length` are in use. */
+  ys: Float64Array;
+  /** How many vertices have been kept. */
+  length: number;
+}
+
+/**
+ * An empty path, with room to grow.
+ * @param capacity - How many vertices to make room for before the first growth; at least one, and rounded down. Defaults to 256, which is a couple of seconds of dragging.
+ * @returns The path, holding no vertex yet.
+ */
+export function createLassoPath(capacity = DEFAULT_CAPACITY): LassoPath {
+  const size = Number.isFinite(capacity)
+    ? Math.max(1, Math.floor(capacity))
+    : DEFAULT_CAPACITY;
+  return { xs: new Float64Array(size), ys: new Float64Array(size), length: 0 };
+}
+
+/**
+ * Empty a path without giving up the room it has claimed.
+ *
+ * The buffers are kept, so the second lasso of a session and the fiftieth cost
+ * nothing to start. Whatever is left past `length` is never read.
+ * @param path - The path to empty.
+ */
+export function resetLassoPath(path: LassoPath): void {
+  path.length = 0;
+}
+
+/**
+ * Add a vertex, unless it is too near the last one kept.
+ *
+ * The distance is measured from the last vertex that was kept, not from the
+ * last position the pointer reported, so consecutive vertices are always at
+ * least `minDistance` apart however slowly the pointer is moving. Measuring
+ * from the raw sample instead would let a slow drag across the whole plot keep
+ * a single vertex, and the outline would close as a straight line between
+ * where the drag started and where it ended.
+ * @param path - The path to add to; its buffers are doubled when full.
+ * @param x - Horizontal position of the vertex, in pixels.
+ * @param y - Vertical position of the vertex, in pixels.
+ * @param minDistance - How far the pointer has to have moved for the vertex to be worth keeping, in pixels. Nothing is dropped when it is zero, negative, or not finite.
+ * @returns Whether the vertex was kept. A position that is not finite never is.
+ */
+export function appendLassoPoint(
+  path: LassoPath,
+  x: number,
+  y: number,
+  minDistance: number,
+): boolean {
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return false;
+
+  if (path.length > 0) {
+    const lastX = path.xs[path.length - 1];
+    const lastY = path.ys[path.length - 1];
+    if (lastX !== undefined && lastY !== undefined) {
+      const gate =
+        Number.isFinite(minDistance) && minDistance > 0
+          ? minDistance * minDistance
+          : 0;
+      const deltaX = x - lastX;
+      const deltaY = y - lastY;
+      if (deltaX * deltaX + deltaY * deltaY < gate) return false;
+    }
+  }
+
+  if (path.length >= path.xs.length || path.length >= path.ys.length) {
+    growLassoPath(path);
+  }
+  path.xs[path.length] = x;
+  path.ys[path.length] = y;
+  path.length += 1;
+  return true;
+}
+
+/**
+ * The path as an SVG `d` attribute.
+ *
+ * Coordinates are rounded to a tenth of a pixel. A lasso is drawn at a
+ * resolution the eye cannot resolve past that, and the full doubles would put
+ * seventeen characters per vertex into an attribute that is rewritten on every
+ * frame of the drag.
+ * @param path - The path to write out.
+ * @param close - Whether to close the ring with a `Z`, which is what turns the drawn line into the shape that is about to be tested.
+ * @returns The `d` attribute, or an empty string when the path holds no vertex.
+ */
+export function lassoPathData(path: LassoPath, close: boolean): string {
+  const count = Math.min(path.length, path.xs.length, path.ys.length);
+  let data = '';
+  for (let index = 0; index < count; index++) {
+    const x = path.xs[index];
+    const y = path.ys[index];
+    if (x === undefined || y === undefined) break;
+    data += `${index === 0 ? 'M' : ' L'}${roundToTenth(x)},${roundToTenth(y)}`;
+  }
+  if (data.length === 0) return '';
+  return close ? `${data}Z` : data;
+}
+
+function growLassoPath(path: LassoPath): void {
+  const capacity = Math.max(1, Math.min(path.xs.length, path.ys.length)) * 2;
+  const xs = new Float64Array(capacity);
+  const ys = new Float64Array(capacity);
+  xs.set(path.xs);
+  ys.set(path.ys);
+  path.xs = xs;
+  path.ys = ys;
+}
+
+function roundToTenth(value: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.round(value * 10) / 10;
+}