react-cheminfo 0.11.0 → 0.12.0

package/src/router/ui/useTabRoute.ts

@@ -0,0 +1,35 @@
+import { useCallback, useEffect, useMemo, useSyncExternalStore } from 'react';
+
+import {
+  currentAddress,
+  readRoute,
+  subscribeToRoute,
+} from '../core/history.ts';
+import type { TabRoute, TabRouter } from '../core/tabRouter.ts';
+
+/**
+ * The route the browser is showing, re-rendered on every move — back, forward,
+ * and every `writeRoute` the app makes.
+ *
+ * A legacy hash link is replaced by its path once, after the first render, when
+ * the router adopts such links.
+ * @param router - The site's router, created once at module level.
+ * @returns The route of the address on screen.
+ */
+export function useTabRoute<Tab extends string>(
+  router: TabRouter<Tab>,
+): TabRoute<Tab> {
+  const subscribe = useCallback(
+    (onChange: () => void) => subscribeToRoute(router, onChange),
+    [router],
+  );
+  const address = useSyncExternalStore(
+    subscribe,
+    currentAddress,
+    currentAddress,
+  );
+  useEffect(() => {
+    readRoute(router);
+  }, [router]);
+  return useMemo(() => router.parse(address), [router, address]);
+}

package/src/scatter/core/confidenceEllipse.ts

@@ -6,19 +6,13 @@
  * axes rarely carry the same number of pixels per unit.
  */
 
-import { standardDeviationsForCoverage } from './ellipseCoverage.ts';
+import type { MatrixLike } from '../../chart/core/matrix.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;
+import type { EllipseCovariance } from './ellipseAxes.ts';
+import { ellipseAxes } from './ellipseAxes.ts';
+import { standardDeviationsForCoverage } from './ellipseCoverage.ts';
+import type { ScatterGroupMoments } from './scatterGroupMoments.ts';
+import { scatterGroupMoments } from './scatterGroupMoments.ts';
 
 /** A point of a cloud, or of an outline drawn around one, in data units. */
 export interface EllipsePoint {
@@ -54,15 +48,11 @@ export interface EllipseStandardDeviationSize {
  */
 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;
-}
+/** What a group is outlined at when the caller says nothing: the share holding 95 % of it. */
+export const DEFAULT_ELLIPSE_SIZE: EllipseSize = {
+  kind: 'coverage',
+  probability: 0.95,
+};
 
 /** A group outline, in data units. */
 export interface ConfidenceEllipse {
@@ -114,101 +104,65 @@ 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 { size = DEFAULT_ELLIPSE_SIZE, minimumPoints = 3 } = options;
+  const moments = scatterGroupMoments(pointMatrix(points), null, 1, 2);
+  return momentsEllipse(moments, {
+    group: 0,
+    xAxis: 0,
+    yAxis: 1,
+    standardDeviations: ellipseStandardDeviations(size),
+    minimumPoints,
+  });
+}
 
-  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 };
+/** Which outline {@link momentsEllipse} cuts out of a block of moments. */
+interface MomentsEllipseOptions {
+  /** Which group. */
+  group: number;
+  /** The axis the outline's `x` is read along. */
+  xAxis: number;
+  /** The axis its `y` is read along. */
+  yAxis: number;
+  /** How far out to draw, in standard deviations. */
+  standardDeviations: number;
+  /** How many rows the group needs before it has a shape; below two is read as two. */
+  minimumPoints: number;
 }
 
 /**
- * The semi-axes and the rotation that a covariance describes.
+ * One group's outline for one pair of axes, cut out of measured moments.
  *
- * 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.
+ * The two-by-two block of a covariance is a covariance in its own right, so a
+ * pair grid measuring every axis at once and a map measuring one pair give
+ * the same outline for the same samples.
+ * @param moments - The block, from `scatterGroupMoments`.
+ * @param options - See {@link MomentsEllipseOptions}.
+ * @returns The outline, or `null` when the group is too small to have a shape, when either axis or the group is outside the block, or when the size or the coordinates are not finite.
  */
-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),
-  };
-}
+export function momentsEllipse(
+  moments: ScatterGroupMoments,
+  options: MomentsEllipseOptions,
+): ConfidenceEllipse | null {
+  const { axes, groups, counts, means, covariances } = moments;
+  const { group, xAxis, yAxis, standardDeviations, minimumPoints } = options;
+  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;
 
-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;
+  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 };
 }
 
 /**
@@ -228,3 +182,20 @@ export function ellipseStandardDeviations(size: EllipseSize): number {
   }
   return standardDeviationsForCoverage(size.probability);
 }
+
+/*
+ * A run of points read as a two-column matrix, so a group handed as objects
+ * is measured by the same scan as one handed as a score matrix.
+ */
+function pointMatrix(points: readonly EllipsePoint[]): MatrixLike {
+  return {
+    rows: points.length,
+    columns: 2,
+    get(rowIndex: number, columnIndex: number): number {
+      const point = points[rowIndex];
+      if (point === undefined) return Number.NaN;
+      if (columnIndex === 0) return point.x;
+      return columnIndex === 1 ? point.y : Number.NaN;
+    },
+  };
+}

package/src/scatter/core/ellipseAxes.ts

@@ -0,0 +1,85 @@
+/**
+ * The shape a covariance describes: two semi-axes and the turn of the longer
+ * one, from the closed form of a symmetric two by two eigen-decomposition.
+ *
+ * It is its own module because a map outline, a pair-grid cell and the
+ * silhouette of a shell in a cloud all end in this same decomposition, and a
+ * second copy of it is a second collinear floor to forget.
+ */
+
+/**
+ * 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;
+
+/** 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;
+}
+
+/** The drawable shape of a covariance. */
+export interface EllipseAxes {
+  /** Semi-major axis length. */
+  rx: number;
+  /** Semi-minor axis length; exactly `0` when the spread is collinear. */
+  ry: number;
+  /** Rotation of the major axis, in radians counter-clockwise, in `(-π/2, π/2]`. */
+  angle: number;
+}
+
+/**
+ * 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,
+): EllipseAxes {
+  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;
+}

package/src/scatter/core/ellipseProjection.ts

@@ -10,7 +10,7 @@
 import type { ChartScale } from '../../chart/core/chartScale.ts';
 
 import type { ConfidenceEllipse, EllipsePoint } from './confidenceEllipse.ts';
-import { ellipseAxes } from './confidenceEllipse.ts';
+import { ellipseAxes } from './ellipseAxes.ts';
 
 const HALF_TURN_DEGREES = 180;
 const DEFAULT_STEPS = 64;

package/src/scatter/core/index.ts

@@ -13,7 +13,6 @@
 export type {
   ConfidenceEllipse,
   ConfidenceEllipseOptions,
-  EllipseCovariance,
   EllipseCoverageSize,
   EllipsePoint,
   EllipseSize,
@@ -21,9 +20,10 @@ export type {
 } from './confidenceEllipse.ts';
 export {
   confidenceEllipse,
-  ellipseAxes,
   ellipseStandardDeviations,
 } from './confidenceEllipse.ts';
+export type { EllipseAxes, EllipseCovariance } from './ellipseAxes.ts';
+export { ellipseAxes } from './ellipseAxes.ts';
 export {
   coverageForStandardDeviations,
   standardDeviationsForCoverage,
@@ -38,6 +38,16 @@ export {
   resetLassoPath,
 } from './lassoPath.ts';
 export { pointInPolygon, pointsInPolygon, polygonBounds } from './polygon.ts';
+export type { ScatterGroupMoments } from './scatterGroupMoments.ts';
+export type {
+  ScatterGroupSpread,
+  ScatterGroupSpreadOptions,
+} from './scatterGroupSpread.ts';
+export {
+  scatterGroupSpread,
+  scatterPairEllipse,
+  scatterSkippedGroups,
+} from './scatterGroupSpread.ts';
 export type { ScatterSelectionMode } from './scatterSelection.ts';
 export {
   mergeScatterSelection,

package/src/scatter/core/lassoPath.ts

@@ -1,3 +1,5 @@
+import { chartRoundPixel } from '../../chart/core/chartScale.ts';
+
 const DEFAULT_CAPACITY = 256;
 
 /**
@@ -122,6 +124,5 @@ function growLassoPath(path: LassoPath): void {
 }
 
 function roundToTenth(value: number): number {
-  if (!Number.isFinite(value)) return 0;
-  return Math.round(value * 10) / 10;
+  return Number.isFinite(value) ? chartRoundPixel(value, 1) : 0;
 }

package/src/scatter/core/scatterGroupMoments.ts

@@ -0,0 +1,127 @@
+/**
+ * The one scan every group outline starts from: how many rows a group holds,
+ * where its middle is, and how it varies between every pair of axes.
+ *
+ * A map outline, a cell of a pair grid and a shell in a cloud all ask this of
+ * the same samples, and three copies of the loop are three places for the
+ * divisor or the treatment of a missing value to drift apart.
+ */
+
+import { chartGroupIndex } from '../../chart/core/chartGroups.ts';
+import type { MatrixLike } from '../../chart/core/matrix.ts';
+
+/** How every group is spread over a run of axes. */
+export interface ScatterGroupMoments {
+  /** 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 reader reads either way round.
+   */
+  covariances: Float64Array;
+}
+
+/**
+ * Measure every group over the leading axes, in two passes over the scores
+ * read where they stand.
+ *
+ * A row missing a value in any one of the axes is left out of its group
+ * altogether, so every pair of axes describes the same samples. The spread
+ * uses the `n - 1` divisor, which is what makes it an estimate of the group
+ * rather than a statement about the handful of samples that happen to have
+ * been measured.
+ * @param scores - The coordinates: one row per sample, one column per axis.
+ * @param groupOf - Which group each row belongs to, or `null` when every row is one group.
+ * @param groups - How many groups there are.
+ * @param axes - How many leading axes to measure over.
+ * @returns The moments. A group of fewer than two rows keeps a zero spread.
+ */
+export function scatterGroupMoments(
+  scores: MatrixLike,
+  groupOf: ArrayLike<number> | null,
+  groups: number,
+  axes: number,
+): ScatterGroupMoments {
+  const groupCount = Math.max(0, Math.trunc(groups));
+  const axisCount = Math.max(0, Math.min(Math.trunc(axes), scores.columns));
+  const counts = new Int32Array(groupCount);
+  const means = new Float64Array(groupCount * axisCount);
+  const covariances = new Float64Array(groupCount * axisCount * axisCount);
+  const moments = {
+    axes: axisCount,
+    groups: groupCount,
+    counts,
+    means,
+    covariances,
+  };
+  if (groupCount === 0 || axisCount === 0) return moments;
+
+  for (let row = 0; row < scores.rows; row++) {
+    const group = groupAt(groupOf, row, groupCount);
+    if (group < 0 || !finiteRow(scores, row, axisCount)) continue;
+    counts[group] = (counts[group] ?? 0) + 1;
+    const base = group * axisCount;
+    for (let axis = 0; axis < axisCount; axis++) {
+      means[base + axis] = (means[base + axis] ?? 0) + scores.get(row, axis);
+    }
+  }
+  for (let group = 0; group < groupCount; group++) {
+    const count = counts[group] ?? 0;
+    if (count === 0) continue;
+    const base = group * axisCount;
+    for (let axis = 0; axis < axisCount; 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(axisCount);
+  for (let row = 0; row < scores.rows; row++) {
+    const group = groupAt(groupOf, row, groupCount);
+    if (group < 0 || !finiteRow(scores, row, axisCount)) continue;
+    const base = group * axisCount;
+    for (let axis = 0; axis < axisCount; axis++) {
+      away[axis] = scores.get(row, axis) - (means[base + axis] ?? 0);
+    }
+    const block = group * axisCount * axisCount;
+    for (let a = 0; a < axisCount; a++) {
+      const first = away[a] ?? 0;
+      for (let b = 0; b < axisCount; b++) {
+        const cell = block + a * axisCount + b;
+        covariances[cell] = (covariances[cell] ?? 0) + first * (away[b] ?? 0);
+      }
+    }
+  }
+  const cells = axisCount * axisCount;
+  for (let group = 0; group < groupCount; group++) {
+    const divisor = (counts[group] ?? 0) - 1;
+    if (divisor < 1) continue;
+    const block = group * cells;
+    for (let cell = 0; cell < cells; cell++) {
+      covariances[block + cell] = (covariances[block + cell] ?? 0) / divisor;
+    }
+  }
+  return moments;
+}
+
+function groupAt(
+  groupOf: ArrayLike<number> | null,
+  row: number,
+  groups: number,
+): number {
+  return groupOf === null ? 0 : chartGroupIndex(groupOf, row, groups);
+}
+
+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;
+}

package/src/scatter/core/scatterGroupSpread.ts

@@ -0,0 +1,131 @@
+/**
+ * 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, EllipseSize } from './confidenceEllipse.ts';
+import {
+  DEFAULT_ELLIPSE_SIZE,
+  ellipseStandardDeviations,
+  momentsEllipse,
+} from './confidenceEllipse.ts';
+import type { ScatterGroupMoments } from './scatterGroupMoments.ts';
+import { scatterGroupMoments } from './scatterGroupMoments.ts';
+
+/** How every group is spread over the axes a grid lays out. */
+export interface ScatterGroupSpread extends ScatterGroupMoments {
+  /** 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, groups, axes } = options;
+  const { size = DEFAULT_ELLIPSE_SIZE, minimumPoints = 3 } = options;
+  return {
+    ...scatterGroupMoments(scores, groupOf, groups, axes),
+    standardDeviations: ellipseStandardDeviations(size),
+    minimumPoints,
+  };
+}
+
+/**
+ * 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 { standardDeviations, minimumPoints } = spread;
+  return momentsEllipse(spread, {
+    group,
+    xAxis,
+    yAxis,
+    standardDeviations,
+    minimumPoints,
+  });
+}
+
+/**
+ * The groups that get no outline for one pair of axes.
+ *
+ * An outline that quietly fails to appear reads as a bug in the plot, so a
+ * caption has to account for these. They are exactly the groups for which
+ * {@link scatterPairEllipse} answers `null`, which is what an outline layer
+ * leaves undrawn — so a caller measuring the same points with the same size
+ * and minimum names the same groups the figure leaves out.
+ * @param spread - The block, from {@link scatterGroupSpread}.
+ * @param xAxis - The axis along the foot of the plot.
+ * @param yAxis - The axis up its side.
+ * @returns The group indices, in ascending order.
+ */
+export function scatterSkippedGroups(
+  spread: ScatterGroupSpread,
+  xAxis: number,
+  yAxis: number,
+): number[] {
+  const skipped: number[] = [];
+  for (let group = 0; group < spread.counts.length; group++) {
+    if (scatterPairEllipse(spread, group, xAxis, yAxis) === null) {
+      skipped.push(group);
+    }
+  }
+  return skipped;
+}