react-cheminfo 0.8.0 → 0.10.0

package/src/projection/ui/useProjectionState.ts

@@ -0,0 +1,224 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import type { SelectionChange } from '../../scatter/ui/useScatterSelection.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import { resolveProjectionOptions } from '../core/projectionOptions.ts';
+import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+import { resolveProjectionGroups } from '../core/projectionSamples.ts';
+import type { ProjectionTab } from '../core/projectionTabs.ts';
+import { projectionTabs } from '../core/projectionTabs.ts';
+
+import type { ProjectionSelection } from './projectionSelection.ts';
+import {
+  indexProjectionIds,
+  projectionNamesOf,
+  projectionRowsOf,
+} from './projectionSelection.ts';
+import type { ProjectionViewerProps } from './projectionViewerProps.ts';
+
+/**
+ * What {@link useProjectionState} needs: the run, the rows, and the three
+ * pieces of state a caller may take over.
+ *
+ * It is the viewer's own props narrowed rather than a second list of the same
+ * eleven fields, so a default documented on the component is the default the
+ * hook actually applies and the two cannot drift apart.
+ */
+export type ProjectionStateOptions = Pick<
+  ProjectionViewerProps,
+  | 'result'
+  | 'samples'
+  | 'tab'
+  | 'defaultTab'
+  | 'onTabChange'
+  | 'selected'
+  | 'defaultSelected'
+  | 'onSelectionChange'
+  | 'options'
+  | 'panels'
+  | 'defaultOptions'
+  | 'onOptionsChange'
+>;
+
+/** What every tab reads, and the five ways any of them changes it. */
+export interface ProjectionStateApi {
+  /** The tabs this result can fill, in reading order. */
+  tabs: readonly ProjectionTab[];
+  /** The one showing. */
+  tab: ProjectionTab;
+  /** Move to another tab. One the result cannot fill is ignored. */
+  setTab: (tab: ProjectionTab) => void;
+  /** The groups as every figure draws them, resolved once per change. */
+  groups: ResolvedProjectionGroups;
+  /** Every option, already made safe against the result. */
+  options: ProjectionOptions;
+  /** Change some of them; the rest are carried over and checked again. */
+  setOptions: (patch: Partial<ProjectionOptions>) => void;
+  /** The selected rows, as indices, which is what a plot draws. */
+  selected: readonly number[];
+  /** Settle a selection a plot's own gesture produced. */
+  settleSelection: (change: SelectionChange) => void;
+  /** Settle one from elsewhere — a legend entry, a table beside the figure. */
+  selectRows: (
+    rows: readonly number[],
+    mode: ScatterSelectionMode,
+    source: ProjectionSelection['source'],
+  ) => void;
+  /** Draw one pair of axes on the map, which is what a cell of the grid does. */
+  selectPair: (xAxis: number, yAxis: number) => void;
+}
+
+/**
+ * The tab, the pair of axes, the selection and the options, controlled or not.
+ *
+ * The tabs are one tool only while they agree, which is why this is one hook
+ * and not four pieces of state in the shell: a pair promoted from the grid has
+ * to arrive on the map, and a lasso drawn there has to still be selected when
+ * the reader comes back to it.
+ *
+ * Each of tab, selection and options is owned by the caller from the moment
+ * its prop is passed and by the hook otherwise, and the two are never mixed: a
+ * controlled value wins on every render, so a caller told about a change that
+ * does not pass the new value back sees the figure stay where it was, rather
+ * than drift out of step with the address bar it is driven from. A `default`
+ * is read once, when the viewer mounts, and changing it later moves nothing.
+ *
+ * Selections cross this boundary as names rather than row numbers. A caller
+ * lighting up its own table already holds the names; handing back indices
+ * would make it keep a second copy of the row order, and that copy is exactly
+ * what goes stale the first time the data behind it is filtered.
+ * @param options - See {@link ProjectionStateOptions}.
+ * @returns The shared state. See {@link ProjectionStateApi}.
+ */
+export function useProjectionState(
+  options: ProjectionStateOptions,
+): ProjectionStateApi {
+  const {
+    result,
+    samples,
+    tab,
+    defaultTab,
+    onTabChange,
+    selected,
+    defaultSelected,
+    onSelectionChange,
+    options: heldOptions,
+    defaultOptions,
+    onOptionsChange,
+    panels,
+  } = options;
+
+  const { ids } = samples;
+  const tabs = useMemo(() => projectionTabs(result, panels), [result, panels]);
+  const rowOfId = useMemo(() => indexProjectionIds(ids), [ids]);
+
+  const [ownTab, setOwnTab] = useState<ProjectionTab | undefined>(defaultTab);
+  const [ownSelected, setOwnSelected] = useState<readonly number[]>(() =>
+    projectionRowsOf(defaultSelected, rowOfId),
+  );
+  const [ownOptions, setOwnOptions] = useState<Partial<ProjectionOptions>>(
+    () => defaultOptions ?? {},
+  );
+
+  const groups = useMemo(
+    () => resolveProjectionGroups(samples, result.scores.rows),
+    [result, samples],
+  );
+  const settled = useMemo(
+    () => resolveProjectionOptions(heldOptions ?? ownOptions, result),
+    [heldOptions, ownOptions, result],
+  );
+
+  const setTab = useCallback(
+    (wanted: ProjectionTab) => {
+      const reachable = inReach(wanted, tabs);
+      if (reachable === undefined) return;
+      if (tab === undefined) setOwnTab(reachable);
+      onTabChange?.(reachable);
+    },
+    [onTabChange, tab, tabs],
+  );
+
+  const setOptions = useCallback(
+    (patch: Partial<ProjectionOptions>) => {
+      const next = resolveProjectionOptions({ ...settled, ...patch }, result);
+      if (heldOptions === undefined) setOwnOptions(next);
+      onOptionsChange?.(next);
+    },
+    [heldOptions, onOptionsChange, result, settled],
+  );
+
+  const selectRows = useCallback(
+    (
+      rows: readonly number[],
+      mode: ScatterSelectionMode,
+      source: ProjectionSelection['source'],
+    ) => {
+      if (selected === undefined) setOwnSelected(rows);
+      onSelectionChange?.({
+        ids: projectionNamesOf(rows, ids),
+        indices: rows,
+        mode,
+        source,
+      });
+    },
+    [ids, onSelectionChange, selected],
+  );
+
+  const settleSelection = useCallback(
+    (change: SelectionChange) => {
+      selectRows(change.indices, change.mode, change.source);
+    },
+    [selectRows],
+  );
+
+  const selectPair = useCallback(
+    (xAxis: number, yAxis: number) => {
+      setOptions({ xAxis, yAxis });
+      setTab('map');
+    },
+    [setOptions, setTab],
+  );
+
+  return {
+    tabs,
+    // The last resort is the first tab offered, never the map: a site that
+    // narrowed `panels` away from it would otherwise be shown the one panel it
+    // said it had no room for, under a strip that does not name it.
+    tab: inReach(tab, tabs) ?? inReach(ownTab, tabs) ?? tabs[0] ?? 'map',
+    setTab,
+    groups,
+    options: settled,
+    setOptions,
+    selected:
+      selected === undefined
+        ? ownSelected
+        : projectionRowsOf(selected, rowOfId),
+    settleSelection,
+    selectRows,
+    selectPair,
+  };
+}
+
+/**
+ * The wanted tab, when the result can actually fill it.
+ *
+ * A saved tab outlives the data it was saved on: a page reopening on the
+ * shares tab and handed a UMAP would otherwise show an empty panel with no
+ * obvious way back, so an unreachable tab is answered with nothing and the
+ * caller falls through to the first tab there is.
+ * @param wanted - The tab asked for, if any.
+ * @param tabs - The tabs the result can fill.
+ * @returns The tab, or `undefined` when it is not one of them.
+ */
+function inReach(
+  wanted: ProjectionTab | undefined,
+  tabs: readonly ProjectionTab[],
+): ProjectionTab | undefined {
+  if (wanted === undefined) return undefined;
+  for (const tab of tabs) {
+    if (tab === wanted) return wanted;
+  }
+  return undefined;
+}

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';