react-cheminfo 0.10.0 → 0.11.0

package/src/scatter3d/core/confidenceEllipsoid.ts

@@ -0,0 +1,177 @@
+/**
+ * The shell that summarises where a group of samples sits in the cloud.
+ *
+ * It is the outline of `scatter/core` with one dimension more, and it is
+ * described the same way — a centre and the axes of the group's own spread,
+ * in the data's units — so that turning it into something an SVG can draw
+ * stays a separate step. Here that step matters more than it does on a map:
+ * a shell has no `<ellipse>` to fall back on and has to be tessellated,
+ * projected and painted back to front.
+ */
+
+import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
+
+import { standardDeviationsForCoverage3 } from './ellipsoidCoverage.ts';
+import type { Vector3 } from './orbitCamera.ts';
+import type { SymmetricMatrix3 } from './symmetricEigen.ts';
+import { symmetricEigen3 } from './symmetricEigen.ts';
+
+/** A group's shell, in the cloud's own units. */
+export interface ConfidenceEllipsoid {
+  /** Centre of the shell, which is the group's average. */
+  center: Vector3;
+  /**
+   * Three orthogonal semi-axes, longest first, each vector as long as its own
+   * radius. A direction the group has no spread in is the zero vector, which
+   * is what flattens the shell rather than giving it a false thickness.
+   */
+  axes: readonly [Vector3, Vector3, Vector3];
+  /** How many finite points went into it. */
+  count: number;
+}
+
+/** How {@link confidenceEllipsoid} measures a group. */
+export interface ConfidenceEllipsoidOptions {
+  /**
+   * How large to draw the shell. A share is read in three dimensions, so the
+   * same share gives a wider shell here than the same call gives on the map.
+   * @default { kind: 'coverage', probability: 0.95 }
+   */
+  size?: EllipseSize;
+  /**
+   * How many finite points a group needs before it is given a shell at all.
+   * Below four a group has no volume to measure — three points lie on a plane
+   * however they are arranged — so fewer than four is read as four.
+   * @default 4
+   */
+  minimumPoints?: number;
+}
+
+/**
+ * The shell that summarises a group of samples.
+ *
+ * Points that are not finite are skipped rather than poisoning the average,
+ * and the spread is measured with the `n - 1` divisor, so the shell estimates
+ * the group rather than describing the handful of samples that happen to have
+ * been measured — both exactly as the two-dimensional outline does.
+ * @param points - The group's samples, in the cloud's own units.
+ * @param options - See {@link ConfidenceEllipsoidOptions}.
+ * @returns The shell, or `null` when the group is too small to have a shape, when its coordinates are so large that squaring them overflows, or when the requested size is unbounded.
+ */
+export function confidenceEllipsoid(
+  points: readonly Vector3[],
+  options: ConfidenceEllipsoidOptions = {},
+): ConfidenceEllipsoid | null {
+  const { size = DEFAULT_SIZE, minimumPoints = 4 } = options;
+  const floor = Math.max(4, minimumPoints);
+
+  let count = 0;
+  let sumX = 0;
+  let sumY = 0;
+  let sumZ = 0;
+  for (const point of points) {
+    if (!isFinitePoint(point)) continue;
+    count++;
+    sumX += point[0];
+    sumY += point[1];
+    sumZ += point[2];
+  }
+  if (count < floor) return null;
+
+  const center: Vector3 = [sumX / count, sumY / count, sumZ / count];
+  const covariance = spreadAbout(points, center, count);
+  if (covariance === null) return null;
+
+  const radius = ellipsoidStandardDeviations(size);
+  if (!Number.isFinite(radius)) return null;
+
+  const { values, vectors } = symmetricEigen3(covariance);
+  const axes: Vector3[] = [];
+  for (let i = 0; i < 3; i++) {
+    const length = radius * Math.sqrt(Math.max(0, values[i] as number));
+    if (!Number.isFinite(length)) return null;
+    const direction = vectors[i] as Vector3;
+    axes.push([
+      direction[0] * length,
+      direction[1] * length,
+      direction[2] * length,
+    ]);
+  }
+
+  return {
+    center,
+    axes: [axes[0] as Vector3, axes[1] as Vector3, axes[2] as Vector3],
+    count,
+  };
+}
+
+/**
+ * How far out a size asks the shell to be drawn.
+ *
+ * Public because a legend has to be able to say what a share came to without
+ * building a shell to ask it.
+ * @param size - How large the shell was asked to be.
+ * @returns The number of standard deviations.
+ */
+export function ellipsoidStandardDeviations(size: EllipseSize): number {
+  if (size.kind === 'standardDeviations') return size.standardDeviations;
+  return standardDeviationsForCoverage3(size.probability);
+}
+
+function spreadAbout(
+  points: readonly Vector3[],
+  center: Vector3,
+  count: number,
+): SymmetricMatrix3 | null {
+  let xx = 0;
+  let xy = 0;
+  let xz = 0;
+  let yy = 0;
+  let yz = 0;
+  let zz = 0;
+  for (const point of points) {
+    if (!isFinitePoint(point)) continue;
+    const dx = point[0] - center[0];
+    const dy = point[1] - center[1];
+    const dz = point[2] - center[2];
+    xx += dx * dx;
+    xy += dx * dy;
+    xz += dx * dz;
+    yy += dy * dy;
+    yz += dy * dz;
+    zz += dz * dz;
+  }
+  const divisor = count - 1;
+  const covariance: SymmetricMatrix3 = {
+    xx: xx / divisor,
+    xy: xy / divisor,
+    xz: xz / divisor,
+    yy: yy / divisor,
+    yz: yz / divisor,
+    zz: zz / divisor,
+  };
+  if (
+    !Number.isFinite(center[0]) ||
+    !Number.isFinite(center[1]) ||
+    !Number.isFinite(center[2]) ||
+    !Number.isFinite(covariance.xx) ||
+    !Number.isFinite(covariance.yy) ||
+    !Number.isFinite(covariance.zz) ||
+    !Number.isFinite(covariance.xy) ||
+    !Number.isFinite(covariance.xz) ||
+    !Number.isFinite(covariance.yz)
+  ) {
+    return null;
+  }
+  return covariance;
+}
+
+function isFinitePoint(point: Vector3): boolean {
+  return (
+    Number.isFinite(point[0]) &&
+    Number.isFinite(point[1]) &&
+    Number.isFinite(point[2])
+  );
+}
+
+const DEFAULT_SIZE: EllipseSize = { kind: 'coverage', probability: 0.95 };

package/src/scatter3d/core/cubeFrame.ts

@@ -0,0 +1,72 @@
+/**
+ * The box the cloud sits in.
+ *
+ * A cloud of dots on an empty background has no orientation at all: turn it
+ * and nothing tells the reader it turned, and a dot near the top could be near
+ * or far. Twelve faint edges and three labelled arms fix that for the cost of
+ * fifteen lines, and they are the reason the projection can stay orthographic
+ * — the frame carries the depth that perspective would otherwise have to, and
+ * unlike perspective it distorts no distance.
+ */
+
+import type { Vector3 } from './orbitCamera.ts';
+
+/** The corner the three labelled arms are drawn from. */
+export const CUBE_ORIGIN: Vector3 = [-1, -1, -1];
+
+/**
+ * The twelve edges of the cube, each as its two corners.
+ *
+ * Every edge, not just the three at the back: which edges are hidden changes
+ * as the box turns, and drawing all twelve faintly reads as a wireframe, while
+ * drawing three reads as an axis system that keeps rearranging itself.
+ * @returns The edges. The order is stable but carries no meaning.
+ */
+export function cubeEdges(): Array<[Vector3, Vector3]> {
+  const corners: Vector3[] = [];
+  for (const x of [-1, 1]) {
+    for (const y of [-1, 1]) {
+      for (const z of [-1, 1]) corners.push([x, y, z]);
+    }
+  }
+
+  const edges: Array<[Vector3, Vector3]> = [];
+  for (let i = 0; i < corners.length; i++) {
+    for (let j = i + 1; j < corners.length; j++) {
+      const a = corners[i] as Vector3;
+      const b = corners[j] as Vector3;
+      // Two corners are joined by an edge exactly when they differ in one
+      // coordinate; differing in two is a face diagonal and in three is the
+      // body diagonal, and drawing either would turn the frame into a mesh.
+      const differing =
+        (a[0] === b[0] ? 0 : 1) +
+        (a[1] === b[1] ? 0 : 1) +
+        (a[2] === b[2] ? 0 : 1);
+      if (differing === 1) edges.push([a, b]);
+    }
+  }
+  return edges;
+}
+
+/** One labelled arm of the frame. */
+export interface CubeArm {
+  /** Which of the three axes it stands for. */
+  axis: 'x' | 'y' | 'z';
+  /** The far end of the arm. */
+  end: Vector3;
+  /** Where its name is written, just beyond the end. */
+  label: Vector3;
+}
+
+/**
+ * The three arms, from the origin corner along each axis.
+ *
+ * The label sits a little past the end of its arm so that it is outside the
+ * cloud whatever the box is turned to; at the end itself it would fall on the
+ * frame from about a third of the angles.
+ */
+export const CUBE_ARMS: readonly CubeArm[] = [
+  { axis: 'x', end: [1, -1, -1], label: [1.18, -1, -1] },
+  { axis: 'y', end: [-1, 1, -1], label: [-1, 1.18, -1] },
+  { axis: 'z', end: [-1, -1, 1], label: [-1, -1, 1.18] },
+];

package/src/scatter3d/core/cubePoints.ts

@@ -0,0 +1,75 @@
+/**
+ * Three runs of numbers, stretched into the cube the cloud is drawn in.
+ *
+ * A map draws its two axes at whatever scale each one needs, and the tick
+ * labels are the reader's record of that. A cloud has no such record: it is
+ * one solid seen from an angle, so three axes drawn at three scales would make
+ * a group lean in a direction that is an artefact of the scaling and not
+ * anything in the data. Every axis is therefore stretched to the same cube,
+ * the frame is labelled with which axis is which, and the numbers stay in the
+ * card the pointer raises.
+ *
+ * The shells are fitted in this cube for the same reason the map fits its
+ * outlines in pixels: a shell has to sit on the cloud the reader is looking
+ * at, not on a cloud in units nothing draws.
+ */
+
+import {
+  chartPadExtent,
+  chartValuesExtent,
+} from '../../chart/core/chartExtent.ts';
+
+import type { Vector3 } from './orbitCamera.ts';
+
+/** How {@link cubePoints} stretches the runs it is given. */
+export interface CubePointsOptions {
+  /**
+   * Share of each axis' span left empty at both ends, so the cloud does not
+   * touch the frame.
+   * @default 0.05
+   */
+  padding?: number;
+}
+
+/**
+ * Three runs of numbers, each stretched to `[-1, 1]`.
+ * @param x - Where every sample sits along the axis that runs left to right.
+ * @param y - Along the axis that runs bottom to top, in the same order.
+ * @param z - Along the axis that runs away from the reader.
+ * @param options - See {@link CubePointsOptions}.
+ * @returns One point per sample, as many as the shortest run holds. An axis with no spread at all puts every sample at the middle of it rather than dividing by zero, and a value that is not finite stays that way so nothing draws it.
+ */
+export function cubePoints(
+  x: ArrayLike<number>,
+  y: ArrayLike<number>,
+  z: ArrayLike<number>,
+  options: CubePointsOptions = {},
+): Vector3[] {
+  const { padding = 0.05 } = options;
+  const toCube = [x, y, z].map((values) => axisMapper(values, padding));
+  const across = toCube[0] as Mapper;
+  const up = toCube[1] as Mapper;
+  const away = toCube[2] as Mapper;
+
+  const count = Math.min(x.length, y.length, z.length);
+  const points = new Array<Vector3>(count);
+  for (let index = 0; index < count; index++) {
+    points[index] = [
+      across(x[index] as number),
+      up(y[index] as number),
+      away(z[index] as number),
+    ];
+  }
+  return points;
+}
+
+type Mapper = (value: number) => number;
+
+function axisMapper(values: ArrayLike<number>, padding: number): Mapper {
+  const { min, max } = chartPadExtent(chartValuesExtent(values), padding);
+  const span = max - min;
+  if (!Number.isFinite(span) || span <= 0) {
+    return (value: number) => (Number.isFinite(value) ? 0 : Number.NaN);
+  }
+  return (value: number) => (2 * (value - min)) / span - 1;
+}

package/src/scatter3d/core/ellipsoidCoverage.ts

@@ -0,0 +1,86 @@
+/**
+ * How far out a group's shell is drawn, and how much of the group it then
+ * holds.
+ *
+ * The two-dimensional pair in `scatter/core` cannot answer this, and the
+ * difference is not a rounding: a shell has to hold a sample in three
+ * directions at once, so the same two standard deviations that keep 86 per
+ * cent of a flat cloud keep only 74 per cent of a solid one. Quoting the flat
+ * figure beside a cloud is the usual way a legend comes to promise more than
+ * its shells contain, which is why the map and the cloud each ask their own
+ * dimension.
+ */
+
+/**
+ * The share of a three-dimensional normal cloud inside the shell drawn at a
+ * number of standard deviations.
+ * @param standardDeviations - How far out the shell is drawn.
+ * @returns The share, from 0 to 1. Zero at or below zero, since a shell of no size holds nothing.
+ */
+export function coverageForStandardDeviations3(
+  standardDeviations: number,
+): number {
+  if (!Number.isFinite(standardDeviations)) {
+    return standardDeviations > 0 ? 1 : 0;
+  }
+  if (standardDeviations <= 0) return 0;
+  const radius = standardDeviations;
+  const inside = erf(radius / Math.SQRT2);
+  const shell =
+    radius * Math.sqrt(2 / Math.PI) * Math.exp(-(radius * radius) / 2);
+  return Math.min(1, Math.max(0, inside - shell));
+}
+
+/**
+ * How far out to draw the shell that holds a share of a three-dimensional
+ * normal cloud.
+ *
+ * The inverse of {@link coverageForStandardDeviations3}. There is no closed
+ * form for it, so it is bisected — the share grows strictly with the radius,
+ * so fifty halvings settle it far below the width of the line the shell is
+ * drawn with, and the search runs once per group rather than once per face.
+ * @param coverage - The share 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 shell holds every point of a cloud with unbounded tails.
+ */
+export function standardDeviationsForCoverage3(coverage: number): number {
+  if (!Number.isFinite(coverage) || coverage <= 0) return 0;
+  if (coverage >= 1) return Number.POSITIVE_INFINITY;
+
+  let low = 0;
+  // Nine standard deviations hold every share a control can ask for: the
+  // remainder there is under 1e-17, which no `number` can tell from zero.
+  let high = 9;
+  for (let step = 0; step < 50; step++) {
+    const middle = (low + high) / 2;
+    if (coverageForStandardDeviations3(middle) < coverage) {
+      low = middle;
+    } else {
+      high = middle;
+    }
+  }
+  return (low + high) / 2;
+}
+
+/**
+ * The error function, to about a part in ten million.
+ *
+ * Abramowitz and Stegun 7.1.26. That is coarser than the library's usual
+ * standard and is deliberately so: it decides the radius of a shell drawn a
+ * few hundred pixels across, where a part in ten million is a part in ten
+ * thousand of one pixel, and the alternative is a series that costs more to
+ * read than the whole module around it.
+ * @param x - The argument.
+ * @returns The error function at `x`.
+ */
+function erf(x: number): number {
+  const sign = x < 0 ? -1 : 1;
+  const absolute = Math.abs(x);
+  const t = 1 / (1 + 0.327_591_1 * absolute);
+  const series =
+    t *
+    (0.254_829_592 +
+      t *
+        (-0.284_496_736 +
+          t * (1.421_413_741 + t * (-1.453_152_027 + t * 1.061_405_429))));
+  return sign * (1 - series * Math.exp(-absolute * absolute));
+}

package/src/scatter3d/core/ellipsoidSilhouette.ts

@@ -0,0 +1,76 @@
+/**
+ * The outline a shell has on screen, which is an ellipse and nothing else.
+ *
+ * An orthographic camera sends the unit sphere to a filled ellipse, so a shell
+ * — a sphere carried by three semi-axes — has an exact elliptical silhouette
+ * whatever it is turned to. Taking it as such is what keeps the glass smooth:
+ * a tessellated shell is only as round as the number of faces it was cut into,
+ * and every seam between two of those faces is a line the reader can see.
+ */
+
+import type { ConfidenceEllipsoid } from './confidenceEllipsoid.ts';
+import type { OrbitCamera } from './orbitCamera.ts';
+import { rotatePoint } from './orbitCamera.ts';
+
+/** Where a shell's outline sits, in cube units, for one camera. */
+export interface EllipsoidSilhouette {
+  /** Half the outline's longest width, along the angle below. */
+  rx: number;
+  /** Half its width across that, never longer than `rx`. */
+  ry: number;
+  /**
+   * How far the long axis is turned from the horizontal, in radians, measured
+   * the way the screen measures — down from the right — since the projection
+   * flips the vertical axis on its way to pixels.
+   */
+  angle: number;
+}
+
+/**
+ * The outline of a shell, for the camera it is seen from.
+ *
+ * The three semi-axes are turned with the camera and their depth dropped,
+ * which leaves a `2 x 3` map from the unit sphere to the screen. The image of
+ * that sphere is the ellipse whose shape matrix is the map times its own
+ * transpose, so the two radii are the square roots of that matrix's
+ * eigenvalues and the tilt is half the angle of its off-diagonal term.
+ *
+ * A group flat in one direction gives a matrix with a zero eigenvalue and
+ * comes back as a segment, which is the honest picture of a group that has no
+ * spread to show.
+ * @param ellipsoid - The shell, in cube units.
+ * @param camera - Where the reader is standing.
+ * @returns See {@link EllipsoidSilhouette}.
+ */
+export function ellipsoidSilhouette(
+  ellipsoid: ConfidenceEllipsoid,
+  camera: OrbitCamera,
+): EllipsoidSilhouette {
+  const [first, second, third] = ellipsoid.axes;
+  const a = rotatePoint(first, camera);
+  const b = rotatePoint(second, camera);
+  const c = rotatePoint(third, camera);
+
+  // The screen's own frame: across, and down — hence the sign on the second.
+  const acrossX = a[0];
+  const acrossY = b[0];
+  const acrossZ = c[0];
+  const downX = -a[1];
+  const downY = -b[1];
+  const downZ = -c[1];
+
+  const xx = acrossX * acrossX + acrossY * acrossY + acrossZ * acrossZ;
+  const yy = downX * downX + downY * downY + downZ * downZ;
+  const xy = acrossX * downX + acrossY * downY + acrossZ * downZ;
+
+  const middle = (xx + yy) / 2;
+  const spread = Math.hypot((xx - yy) / 2, xy);
+  const major = Math.max(0, middle + spread);
+  const minor = Math.max(0, middle - spread);
+
+  return {
+    rx: Math.sqrt(major),
+    ry: Math.sqrt(minor),
+    angle: 0.5 * Math.atan2(2 * xy, xx - yy),
+  };
+}

package/src/scatter3d/core/index.ts

@@ -0,0 +1,52 @@
+/**
+ * A cloud of samples in three dimensions: where the reader is standing, where
+ * a sample lands on screen from there, and the shell that holds a group.
+ *
+ * It is the two-dimensional `scatter` domain with one axis more, and the extra
+ * axis changes more than it looks. Nothing can be handed to an SVG shape any
+ * more — a shell has to be cut into faces, projected, and painted back to
+ * front — and the three axes have to share one scale, because a solid seen
+ * from an angle has no tick labels to record three different ones with.
+ *
+ * Nothing here knows what produced the coordinates, and nothing here draws:
+ * every function is arithmetic over plain numbers, so the geometry can be
+ * checked without a DOM.
+ */
+
+export type {
+  ConfidenceEllipsoid,
+  ConfidenceEllipsoidOptions,
+} from './confidenceEllipsoid.ts';
+export {
+  confidenceEllipsoid,
+  ellipsoidStandardDeviations,
+} from './confidenceEllipsoid.ts';
+export type { CubeArm } from './cubeFrame.ts';
+export { CUBE_ARMS, CUBE_ORIGIN, cubeEdges } from './cubeFrame.ts';
+export {
+  coverageForStandardDeviations3,
+  standardDeviationsForCoverage3,
+} from './ellipsoidCoverage.ts';
+export type { EllipsoidSilhouette } from './ellipsoidSilhouette.ts';
+export { ellipsoidSilhouette } from './ellipsoidSilhouette.ts';
+export type {
+  OrbitCamera,
+  OrbitViewport,
+  ProjectedPoint,
+  Vector3,
+} from './orbitCamera.ts';
+export {
+  CUBE_HALF_DIAGONAL,
+  DEFAULT_ORBIT_CAMERA,
+  ORBIT_PITCH_LIMIT,
+  ORBIT_RADIANS_PER_PIXEL,
+  depthFraction,
+  orbitByDrag,
+  projectPoint,
+  rotatePoint,
+} from './orbitCamera.ts';
+export type { CloudGesture } from './cloudGesture.ts';
+export type { CubePointsOptions } from './cubePoints.ts';
+export { cubePoints } from './cubePoints.ts';
+export type { SymmetricEigen3, SymmetricMatrix3 } from './symmetricEigen.ts';
+export { symmetricEigen3 } from './symmetricEigen.ts';