react-cheminfo 0.9.0 → 0.11.0

package/src/projection/ui/projectionMapModel.ts

@@ -0,0 +1,253 @@
+/**
+ * Where a map's samples land, and which corner of the picture is free.
+ *
+ * It sits beside the component rather than inside it because a plot has to
+ * know where its dots fall before it can decide where its controls may sit,
+ * and because all of it is arithmetic that can be checked without rendering
+ * anything. The words the same tab writes are in `projectionMapChrome.ts`.
+ */
+
+import {
+  chartColumnExtent,
+  chartPadExtent,
+} from '../../chart/core/chartExtent.ts';
+import { chartAxisTitle } from '../../chart/core/chartLabels.ts';
+import type { ChartViewport } from '../../chart/core/chartViewport.ts';
+import type { MatrixLike } from '../../chart/core/matrix.ts';
+import { emptiestCorner } from '../../overlay/core/emptiestCorner.ts';
+import type { OverlayCorner } from '../../overlay/core/overlayPlacement.ts';
+import type {
+  ScatterGroup,
+  ScatterMarker,
+} from '../../scatter/ui/ScatterPlot.tsx';
+import type {
+  ProjectionMarker,
+  ProjectionResult,
+} from '../core/projectionResult.ts';
+import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+
+/** Where every sample sits on the map, in the embedding's own units. */
+export interface ProjectionMapCloud {
+  /** Horizontal coordinate of every sample, in row order. */
+  x: Float64Array;
+  /** Vertical coordinate of every sample, in the same order. */
+  y: Float64Array;
+}
+
+/**
+ * A dot, a marker or an average that stands for no group at all.
+ *
+ * It has to be the one ink on the map that names nothing, or a reader counts
+ * it as one more group.
+ */
+export const UNGROUPED_INK = 'var(--text-faint)';
+
+/**
+ * How many samples a group needs before it is outlined at all. Below it the
+ * shape of the outline says more about the one sample than about the group.
+ */
+export const MINIMUM_OUTLINE_POINTS = 3;
+
+/**
+ * The two score columns the map draws, read out of the matrix once.
+ *
+ * The columns are copied because a plot takes two arrays and a matrix cannot
+ * hand out one of its columns. It is the only copy the tab makes: every range,
+ * every outline and every hit test afterwards reads the data where it stands.
+ * @param scores - Where every sample landed.
+ * @param xColumn - Which column runs left to right.
+ * @param yColumn - Which one runs bottom to top.
+ * @returns The two columns.
+ */
+export function projectionMapCloud(
+  scores: MatrixLike,
+  xColumn: number,
+  yColumn: number,
+): ProjectionMapCloud {
+  const count = Math.max(0, scores.rows);
+  const x = new Float64Array(count);
+  const y = new Float64Array(count);
+  for (let row = 0; row < count; row++) {
+    x[row] = scores.get(row, xColumn);
+    y[row] = scores.get(row, yColumn);
+  }
+  return { x, y };
+}
+
+/**
+ * The range one axis covers, over every sample or over a chosen few.
+ *
+ * Handing it a selection is what "zoom to selection" is: the same frame drawn
+ * around fewer rows, rather than a second transform layered under the first.
+ * @param scores - Where every sample landed.
+ * @param column - Which column the axis draws.
+ * @param rows - The rows to cover; an empty or absent list covers them all.
+ * @returns The range, as a frame takes it.
+ */
+export function projectionMapDomain(
+  scores: MatrixLike,
+  column: number,
+  rows?: readonly number[],
+): readonly [number, number] {
+  const covered = rows === undefined || rows.length === 0 ? undefined : rows;
+  const extent = chartColumnExtent(scores, column, { indices: covered });
+  return [extent.min, extent.max];
+}
+
+/**
+ * The frame drawn around a chosen few samples, which is what "zoom to
+ * selection" hands the map.
+ *
+ * Room is left around them: a frame pulled tight on the outermost dots puts
+ * half of them on the edge of the picture, where a dot is hard to read and its
+ * name has nowhere to go.
+ * @param scores - Where every sample landed.
+ * @param xColumn - Which column runs left to right.
+ * @param yColumn - Which one runs bottom to top.
+ * @param rows - The rows to frame; an empty or absent list frames them all.
+ * @param padding - Share added at each end. Defaults to {@link SELECTION_ROOM}.
+ * @returns The frame, in the embedding's own units.
+ */
+export function projectionMapViewport(
+  scores: MatrixLike,
+  xColumn: number,
+  yColumn: number,
+  rows?: readonly number[],
+  padding = SELECTION_ROOM,
+): ChartViewport {
+  return {
+    x: withRoom(projectionMapDomain(scores, xColumn, rows), padding),
+    y: withRoom(projectionMapDomain(scores, yColumn, rows), padding),
+  };
+}
+
+/**
+ * The corner of the map with the fewest dots under it.
+ *
+ * All four are offered. The chrome that asks is laid out inside the plot
+ * rectangle rather than over the figure's box, so no corner of it costs the
+ * reader an axis label, and the only thing left to weigh is how many samples
+ * each one would cover.
+ * @param cloud - Where every sample sits, in data units.
+ * @param xDomain - The range the horizontal axis covers.
+ * @param yDomain - The range the vertical axis covers.
+ * @param width - Width of the plot rectangle, in pixels.
+ * @param height - Its height.
+ * @returns The corner the card sits in.
+ */
+export function projectionMapCorner(
+  cloud: ProjectionMapCloud,
+  xDomain: readonly [number, number],
+  yDomain: readonly [number, number],
+  width: number,
+  height: number,
+): OverlayCorner {
+  return emptiestCorner(
+    placeAlong(cloud.x, xDomain, width, false),
+    placeAlong(cloud.y, yDomain, height, true),
+    { width, height, cardWidth: CARD_WIDTH, cardHeight: CARD_HEIGHT },
+  );
+}
+
+/**
+ * The reference points of a result, placed on the two axes the map draws.
+ * @param markers - The reference points, in the embedding's own units.
+ * @param groups - The groups, whose colours the markers borrow.
+ * @param xColumn - Which axis runs left to right.
+ * @param yColumn - Which one runs bottom to top.
+ * @returns The markers a plot can draw; one standing off the two axes drawn is left out.
+ */
+export function projectionMapMarkers(
+  markers: readonly ProjectionMarker[],
+  groups: ResolvedProjectionGroups,
+  xColumn: number,
+  yColumn: number,
+): ScatterMarker[] {
+  const placed: ScatterMarker[] = [];
+  for (const marker of markers) {
+    const x = marker.position[xColumn];
+    const y = marker.position[yColumn];
+    if (x === undefined || y === undefined) continue;
+    placed.push({
+      label: marker.label,
+      x,
+      y,
+      color: groups.entries[marker.group ?? -1]?.color ?? UNGROUPED_INK,
+      shape: marker.shape ?? 'cross',
+    });
+  }
+  return placed;
+}
+
+/**
+ * The groups in the shape a plot colours by.
+ * @param groups - The groups as the viewer resolved them.
+ * @returns One entry per group, in the order they are coloured.
+ */
+export function projectionScatterGroups(
+  groups: ResolvedProjectionGroups,
+): ScatterGroup[] {
+  const plotted: ScatterGroup[] = [];
+  for (const entry of groups.entries) {
+    plotted.push({ id: entry.id, label: entry.label, color: entry.color });
+  }
+  return plotted;
+}
+
+/**
+ * What one axis of the map is called.
+ *
+ * Built by `chartAxisTitle` rather than assembled here, so a component reads
+ * `PC1 — 73.0 %` in exactly the form every other figure in the package writes
+ * it, and a method that publishes no share gets a bare name instead of a
+ * percentage nobody can stand behind.
+ * @param result - The reduced space being drawn.
+ * @param index - Which axis.
+ * @returns The title, or `undefined` for an axis the result does not have.
+ */
+export function projectionAxisTitle(
+  result: ProjectionResult,
+  index: number,
+): string | undefined {
+  const axis = result.axes[index];
+  if (axis === undefined) return undefined;
+  return chartAxisTitle(axis.name, { share: axis.share });
+}
+
+function withRoom(
+  domain: readonly [number, number],
+  padding: number,
+): readonly [number, number] {
+  const extent = chartPadExtent({ min: domain[0], max: domain[1] }, padding);
+  return [extent.min, extent.max];
+}
+
+function placeAlong(
+  values: Float64Array,
+  domain: readonly [number, number],
+  size: number,
+  flip: boolean,
+): Float64Array {
+  const span = domain[1] - domain[0];
+  const factor = span === 0 ? 0 : size / span;
+  const pixels = new Float64Array(values.length);
+  for (let index = 0; index < values.length; index++) {
+    const along = ((values[index] ?? Number.NaN) - domain[0]) * factor;
+    pixels[index] = flip ? size - along : along;
+  }
+  return pixels;
+}
+
+/**
+ * How much of the plot the floating key is expected to cover.
+ *
+ * It is an estimate on purpose — the card has not been laid out when the
+ * corner is chosen — and it is the compact key's size rather than the roomier
+ * card the overlay domain assumes: a corner counted as three species wide
+ * would call a corner busy that the key never reaches.
+ */
+const CARD_WIDTH = 170;
+const CARD_HEIGHT = 84;
+
+/** Room left around a framed selection, as a share of its own span. */
+const SELECTION_ROOM = 0.1;

package/src/projection/ui/projectionMapView.ts

@@ -0,0 +1,233 @@
+/**
+ * What the map is showing that is not an option: the frame it is drawn in, the
+ * sentence reporting the last gesture, and the words its key and its question
+ * mark are built from.
+ *
+ * All of it lives above the tab rather than inside it because the bar spanning
+ * the figure is the viewer's, not the map's: "Zoom to selection" is pressed in
+ * the bar and changes the frame the map draws, and "Clear selection" has to
+ * report itself in exactly the words a released lasso does.
+ */
+
+import { useCallback, useMemo, useState } from 'react';
+
+import type { ChartViewport } from '../../chart/core/chartViewport.ts';
+import { chartClampViewport } from '../../chart/core/chartViewport.ts';
+import type { SelectionChange } from '../../scatter/ui/useScatterSelection.ts';
+import type { OrbitCamera } from '../../scatter3d/core/orbitCamera.ts';
+import { DEFAULT_ORBIT_CAMERA } from '../../scatter3d/core/orbitCamera.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import type {
+  ProjectionMarker,
+  ProjectionResult,
+} from '../core/projectionResult.ts';
+import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+
+import type { SelectionReport } from './ProjectionMapCaption.tsx';
+import type { ProjectionMapChrome } from './projectionMapChrome.ts';
+import {
+  projectionMapChrome,
+  projectionSelectionSentence,
+} from './projectionMapChrome.ts';
+import {
+  MINIMUM_OUTLINE_POINTS,
+  projectionMapDomain,
+  projectionMapViewport,
+} from './projectionMapModel.ts';
+import { MINIMUM_SHELL_POINTS } from './projectionSpaceModel.ts';
+
+/** What {@link useProjectionMapView} needs. */
+export interface ProjectionMapViewInput {
+  /** What the run produced, whatever produced it. */
+  result: ProjectionResult;
+  /** The words the viewer writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** The groups as every figure of this viewer draws them. */
+  groups: ResolvedProjectionGroups;
+  /** Every option, already made safe against the result. */
+  options: ProjectionOptions;
+  /** The selected rows, as indices into the score matrix. */
+  selected: readonly number[];
+  /** Settle a selection, whoever caused it. */
+  onSettle: (change: SelectionChange) => void;
+}
+
+/** The map's own state, and the ways a gesture or a button changes it. */
+export interface ProjectionMapView {
+  /** The key's title, the key's entries, and the paragraph behind the `?`. */
+  chrome: ProjectionMapChrome;
+  /** The same three for the cloud, which promises a different share. */
+  spaceChrome: ProjectionMapChrome;
+  /** Where the reader is standing in the cloud. */
+  camera: OrbitCamera;
+  /** Turn the box. */
+  setCamera: (camera: OrbitCamera) => void;
+  /** How far in the cloud is zoomed. */
+  zoom: number;
+  /** Zoom the box. */
+  setZoom: (zoom: number) => void;
+  /** Put the box back where it was first seen, at the size it was first drawn. */
+  resetSpaceView: () => void;
+  /** The frame the map is drawn in, or `null` when it is drawn around every sample. */
+  viewport: ChartViewport | null;
+  /** Draw the map in another frame, which is what the wheel does. */
+  setViewport: (viewport: ChartViewport | null) => void;
+  /** What the last gesture picked out, or `null` before there was one. */
+  report: SelectionReport | null;
+  /** Settle a selection and report it in the same breath. */
+  settle: (change: SelectionChange) => void;
+  /** Draw the frame around the selected samples. */
+  zoomToSelection: () => void;
+  /** Put the frame back around every sample. */
+  resetView: () => void;
+  /** Empty the selection. */
+  clearSelection: () => void;
+}
+
+/**
+ * The map's frame, its last report, and the words around it.
+ * @param input - See {@link ProjectionMapViewInput}.
+ * @returns See {@link ProjectionMapView}.
+ */
+export function useProjectionMapView(
+  input: ProjectionMapViewInput,
+): ProjectionMapView {
+  const { result, copy, groups, options, selected, onSettle } = input;
+  const { scores, fittedCount, markers } = result;
+  const { colorBy, ellipse, showGroupMeans, xAxis, yAxis } = options;
+
+  const [zoom, setZoom] = useState<AxisFrame | null>(null);
+  const [report, setReport] = useState<SelectionReport | null>(null);
+  const [camera, setCamera] = useState<OrbitCamera>(DEFAULT_ORBIT_CAMERA);
+  const [cloudZoom, setCloudZoom] = useState(1);
+
+  // A frame belongs to the pair of axes it was drawn on. Carrying it onto
+  // another pair would show the reader a corner of a picture they never
+  // framed, so changing the axes shows the whole of the new one instead.
+  const viewport =
+    zoom !== null && zoom.xAxis === xAxis && zoom.yAxis === yAxis
+      ? zoom.viewport
+      : null;
+
+  const setViewport = useCallback(
+    (next: ChartViewport | null) => {
+      setZoom(next === null ? null : { xAxis, yAxis, viewport: next });
+    },
+    [xAxis, yAxis],
+  );
+
+  const zoomToSelection = useCallback(() => {
+    if (selected.length === 0) return;
+    setViewport(
+      chartClampViewport(
+        {
+          x: projectionMapDomain(scores, xAxis),
+          y: projectionMapDomain(scores, yAxis),
+        },
+        projectionMapViewport(scores, xAxis, yAxis, selected),
+      ),
+    );
+  }, [scores, selected, setViewport, xAxis, yAxis]);
+
+  const resetView = useCallback(() => {
+    setViewport(null);
+  }, [setViewport]);
+
+  const resetSpaceView = useCallback(() => {
+    setCamera(DEFAULT_ORBIT_CAMERA);
+    setCloudZoom(1);
+  }, []);
+
+  const colored = colorBy === 'group' && groups.entries.length > 0;
+  const chrome = useMemo(
+    () =>
+      projectionMapChrome({
+        copy,
+        groups,
+        colored,
+        ellipse: colored ? ellipse : null,
+        minimumPoints: MINIMUM_OUTLINE_POINTS,
+        showGroupMeans,
+        markers: markers ?? NO_MARKERS,
+        fittedCount: fittedCount ?? scores.rows,
+        total: scores.rows,
+      }),
+    [
+      copy,
+      groups,
+      colored,
+      ellipse,
+      showGroupMeans,
+      markers,
+      fittedCount,
+      scores,
+    ],
+  );
+
+  const spaceChrome = useMemo(
+    () =>
+      projectionMapChrome({
+        copy,
+        groups,
+        colored,
+        ellipse: colored ? ellipse : null,
+        minimumPoints: MINIMUM_SHELL_POINTS,
+        showGroupMeans: false,
+        markers: NO_MARKERS,
+        fittedCount: fittedCount ?? scores.rows,
+        total: scores.rows,
+        figure: 'space',
+      }),
+    [copy, groups, colored, ellipse, fittedCount, scores],
+  );
+
+  const settle = useCallback(
+    (change: SelectionChange) => {
+      setReport((previous) => ({
+        text: projectionSelectionSentence(
+          copy,
+          change.indices.length,
+          scores.rows,
+        ),
+        at: (previous?.at ?? 0) + 1,
+      }));
+      onSettle(change);
+    },
+    [copy, onSettle, scores],
+  );
+
+  const clearSelection = useCallback(() => {
+    settle({ indices: NO_SELECTION, mode: 'replace', source: 'clear' });
+  }, [settle]);
+
+  return {
+    chrome,
+    spaceChrome,
+    viewport,
+    setViewport,
+    camera,
+    setCamera,
+    zoom: cloudZoom,
+    setZoom: setCloudZoom,
+    resetSpaceView,
+    report,
+    settle,
+    zoomToSelection,
+    resetView,
+    clearSelection,
+  };
+}
+
+/** A frame, and the pair of axes it was drawn on. */
+interface AxisFrame {
+  /** Which column ran left to right when the reader framed it. */
+  xAxis: number;
+  /** Which one ran bottom to top. */
+  yAxis: number;
+  /** The frame itself. */
+  viewport: ChartViewport;
+}
+
+const NO_SELECTION: readonly number[] = [];
+const NO_MARKERS: readonly ProjectionMarker[] = [];

package/src/projection/ui/projectionPairsCeiling.ts

@@ -0,0 +1,45 @@
+/**
+ * How many components the pair grid may be asked to lay out.
+ *
+ * The bar and the panel behind the cog both offer the count, and a ceiling
+ * worked out twice is a ceiling that ends up different in the two places — so
+ * the reader would find the same stepper dead on one and live on the other.
+ * It sits apart from both of them because it is arithmetic rather than a
+ * control, and a module that exports a component exports nothing else.
+ */
+
+import {
+  SCATTER_MATRIX_MOST_AXES,
+  scatterMatrixAxesThatFit,
+} from '../../scatter/ui/scatterMatrixLayout.ts';
+
+/** How few and how many components the grid may be asked to lay out. */
+export interface ProjectionPairsCeiling {
+  /** The fewest, which is the smallest grid worth drawing. */
+  min: number;
+  /** The most, once the run and the width have both had their say. */
+  max: number;
+}
+
+/**
+ * The range the grid's count is held inside.
+ *
+ * Three things cap it at once: six, which is where thirty-six cells stop being
+ * worth the room; what the run produced; and what the width can draw at a
+ * readable size. Pressing past any of them is dead rather than silently
+ * ignored, so the number in the bar is the number on the screen.
+ * @param axisCount - How many components the run produced.
+ * @param width - Width of the figure, in pixels; `0` before it is measured.
+ * @returns See {@link ProjectionPairsCeiling}.
+ */
+export function projectionPairsCeiling(
+  axisCount: number,
+  width: number,
+): ProjectionPairsCeiling {
+  const wanted = Math.min(SCATTER_MATRIX_MOST_AXES, Math.max(0, axisCount));
+  const fits = width > 0 ? scatterMatrixAxesThatFit(width, wanted) : wanted;
+  return { min: SMALLEST_GRID, max: Math.max(SMALLEST_GRID, fits) };
+}
+
+/** The fewest components a grid is worth drawing for. */
+const SMALLEST_GRID = 2;

package/src/projection/ui/projectionSelection.ts

@@ -0,0 +1,87 @@
+/**
+ * What a viewer says about its selection, and the translation between the two
+ * ways of naming a row.
+ *
+ * A plot works in row numbers because that is what it drew, and a caller works
+ * in names because that is what its own table holds. Keeping the translation
+ * here, in one direction each way, is what lets the boundary between them be a
+ * documented promise rather than a habit each tab has to remember.
+ */
+
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+
+/** What a gesture did to a projection viewer's selection. */
+export interface ProjectionSelection {
+  /** The selected rows, by name, in the score matrix's row order. */
+  ids: readonly string[];
+  /** The same rows as indices into the score matrix. */
+  indices: readonly number[];
+  /** Whether the gesture replaced the previous selection, added to it, or cut from it. */
+  mode: ScatterSelectionMode;
+  /** Which gesture produced it. */
+  source: 'lasso' | 'point' | 'keyboard' | 'group' | 'clear' | 'all';
+}
+
+/**
+ * Where each name sits in the score matrix.
+ *
+ * The first row wins a repeated name. A duplicate id then costs the reader one
+ * unselectable row, which is a great deal better than silently moving their
+ * selection to whichever sample happened to be named the same thing last.
+ * @param ids - The row names, in the score matrix's row order.
+ * @returns The row each name stands for.
+ */
+export function indexProjectionIds(
+  ids: readonly string[],
+): ReadonlyMap<string, number> {
+  const rows = new Map<string, number>();
+  for (let index = 0; index < ids.length; index++) {
+    const id = ids[index];
+    if (id !== undefined && !rows.has(id)) rows.set(id, index);
+  }
+  return rows;
+}
+
+/**
+ * The rows a list of names stands for, ready for a plot to draw.
+ *
+ * A name nothing answers to is dropped rather than reported as a missing row:
+ * a caller restoring a selection saved before its data was filtered should get
+ * back the samples that are still there, not an error about the ones that are
+ * not.
+ * @param names - The names, or nothing at all.
+ * @param rowOfId - From {@link indexProjectionIds}.
+ * @returns The rows, in the order the names were given.
+ */
+export function projectionRowsOf(
+  names: readonly string[] | undefined,
+  rowOfId: ReadonlyMap<string, number>,
+): readonly number[] {
+  if (names === undefined) return EMPTY_SELECTION;
+  const rows: number[] = [];
+  for (const name of names) {
+    const row = rowOfId.get(name);
+    if (row !== undefined) rows.push(row);
+  }
+  return rows;
+}
+
+/**
+ * The names a list of rows stands for, ready to hand back to a caller.
+ * @param rows - The rows, as indices into the score matrix.
+ * @param ids - The row names.
+ * @returns The names, in the order the rows were given.
+ */
+export function projectionNamesOf(
+  rows: readonly number[],
+  ids: readonly string[],
+): readonly string[] {
+  const names: string[] = [];
+  for (const row of rows) {
+    const name = ids[row];
+    if (name !== undefined) names.push(name);
+  }
+  return names;
+}
+
+const EMPTY_SELECTION: readonly number[] = [];

package/src/projection/ui/projectionSpaceModel.ts

@@ -0,0 +1,14 @@
+/**
+ * The one number the cloud sets differently from the map.
+ */
+
+/**
+ * How many samples a group needs before it is given a shell.
+ *
+ * One more than the map asks for, and for the same reason the map asks for
+ * three: a shape fitted to the fewest points that can define it describes those
+ * points and not the group they came from. Three samples lie on a plane
+ * however they are arranged, so three is the number at which a shell is
+ * arithmetic rather than a finding.
+ */
+export const MINIMUM_SHELL_POINTS = 4;