react-cheminfo 0.9.0 → 0.10.0

package/src/projection/ui/ProjectionMapTab.tsx

@@ -0,0 +1,205 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useMemo, useState } from 'react';
+
+import type { ChartViewport } from '../../chart/core/chartViewport.ts';
+import { ScatterPlot } from '../../scatter/ui/ScatterPlot.tsx';
+import type { SelectionChange } from '../../scatter/ui/useScatterSelection.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 { ProjectionMapCaption } from './ProjectionMapCaption.tsx';
+import { ProjectionMapLegend } from './ProjectionMapLegend.tsx';
+import { ProjectionSurface } from './ProjectionSurface.tsx';
+import type { ProjectionMapChrome } from './projectionMapChrome.ts';
+import {
+  MINIMUM_OUTLINE_POINTS,
+  projectionAxisTitle,
+  projectionMapCloud,
+  projectionMapDomain,
+  projectionMapMarkers,
+  projectionScatterGroups,
+} from './projectionMapModel.ts';
+
+/** What {@link ProjectionMapTab} needs. */
+export interface ProjectionMapTabProps {
+  /** What the run produced, whatever produced it. */
+  result: ProjectionResult;
+  /** The groups, resolved once by the viewer so every tab colours alike. */
+  groups: ResolvedProjectionGroups;
+  /** What the map is showing, already resolved against `result`. */
+  options: ProjectionOptions;
+  /** The words the map writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** The key's title and entries, built once with the bar's explanation. */
+  chrome: ProjectionMapChrome;
+  /**
+   * What each sample is called, in the score matrix's row order, for the map's
+   * "Sample ID" setting to write beside its dot.
+   * @default undefined — the setting has nothing to write and draws nothing
+   */
+  ids?: readonly string[];
+  /** Width of the figure, in pixels. */
+  width: number;
+  /** Height of the figure, in pixels. */
+  height: number;
+  /** The selected rows, as indices into the score matrix. */
+  selected: readonly number[];
+  /**
+   * The frame the map is drawn in, which is what a zoom leaves behind, or
+   * `null` to draw it around every sample.
+   * @default null
+   */
+  viewport?: ChartViewport | null;
+  /**
+   * Called with the frame a wheel or a double click asks for.
+   * @default undefined
+   */
+  onViewportChange?: (viewport: ChartViewport | null) => void;
+  /**
+   * Whether the wheel zooms the map, once the pointer has rested on it.
+   * @default false
+   */
+  wheelZoom?: boolean;
+  /**
+   * What the last gesture picked out, for the line over the plot.
+   * @default null — nothing has happened yet
+   */
+  report?: SelectionReport | null;
+  /**
+   * Called when a lasso is released, a dot is clicked, or the selection is
+   * emptied — never while a lasso is being drawn.
+   * @default undefined
+   */
+  onSelectionChange?: (change: SelectionChange) => void;
+  /**
+   * Called with the row under the pointer, or `-1`.
+   * @default undefined
+   */
+  onHoverChange?: (index: number) => void;
+  /**
+   * The card that follows the pointer. The viewer builds it, because it has to
+   * say the same thing on every tab.
+   * @default undefined — no card is drawn
+   */
+  hoverCard?: ReactNode;
+  /**
+   * Whether a drag on a touch screen draws a lasso rather than scrolling.
+   * @default false
+   */
+  touchLasso?: boolean;
+  /**
+   * Value of the `data-testid` attribute of the figure.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The map: one dot per sample, an outline per group, and a key floating in the
+ * emptiest corner of the plot.
+ *
+ * Colour stands for the group and for nothing else, and a selected dot keeps
+ * its colour and gains a ring — recolouring it would trade the answer the
+ * reader came for against the question they have just asked. A sample the
+ * model was built from is drawn filled and one placed into the finished model
+ * afterwards is drawn hollow, because the second kind can land anywhere and
+ * its landing far out is the finding rather than a fault.
+ *
+ * Nothing stands under the picture. The tab is one figure and its key, so the
+ * height a page gives the viewer is spent on the data; what the map has to say
+ * in words is behind the question mark in the bar above it.
+ * @param props - See {@link ProjectionMapTabProps}.
+ * @returns The figure.
+ */
+export function ProjectionMapTab(props: ProjectionMapTabProps): ReactElement {
+  const { result, groups, options, copy, chrome, width, height } = props;
+  const { ids, selected, viewport = null, report = null } = props;
+  const { onSelectionChange, onHoverChange, hoverCard } = props;
+  const { onViewportChange, wheelZoom, touchLasso, testId } = props;
+  const { scores, fittedCount, markers } = result;
+  const { xAxis, yAxis, colorBy, showGroupMeans, pointRadius } = options;
+  const { showGroupLabels, showIds, selectMode, ellipse: outlines } = options;
+
+  const [drawing, setDrawing] = useState(false);
+  const cloud = useMemo(
+    () => projectionMapCloud(scores, xAxis, yAxis),
+    [scores, xAxis, yAxis],
+  );
+  const xDomain = useMemo(
+    () => projectionMapDomain(scores, xAxis),
+    [scores, xAxis],
+  );
+  const yDomain = useMemo(
+    () => projectionMapDomain(scores, yAxis),
+    [scores, yAxis],
+  );
+
+  const colored = colorBy === 'group' && groups.entries.length > 0;
+  const ellipse = colored ? outlines : null;
+
+  return (
+    <ScatterPlot
+      x={cloud.x}
+      y={cloud.y}
+      width={width}
+      height={height}
+      xAxis={{ domain: xDomain, label: projectionAxisTitle(result, xAxis) }}
+      yAxis={{ domain: yDomain, label: projectionAxisTitle(result, yAxis) }}
+      groupOf={colored ? groups.groupOf : undefined}
+      groups={colored ? projectionScatterGroups(groups) : undefined}
+      ellipse={ellipse}
+      ellipseMinimumPoints={MINIMUM_OUTLINE_POINTS}
+      showGroupMeans={colored && showGroupMeans}
+      showGroupLabels={colored && showGroupLabels}
+      pointLabels={showIds ? ids : undefined}
+      markers={projectionMapMarkers(
+        markers ?? NO_MARKERS,
+        groups,
+        xAxis,
+        yAxis,
+      )}
+      pointRadius={pointRadius}
+      outlinedFrom={fittedCount}
+      selected={selected}
+      viewport={viewport}
+      onViewportChange={onViewportChange}
+      wheelZoom={wheelZoom}
+      onSelectionChange={onSelectionChange}
+      selectMode={selectMode}
+      onHoverChange={onHoverChange}
+      onLassoChange={setDrawing}
+      touchLasso={touchLasso}
+      testId={testId}
+      overlay={
+        <ProjectionSurface>
+          {chrome.entries.length === 0 ? null : (
+            <ProjectionMapLegend
+              title={chrome.title}
+              entries={chrome.entries}
+              cloud={cloud}
+              xDomain={viewport?.x ?? xDomain}
+              yDomain={viewport?.y ?? yDomain}
+              width={width}
+              height={height}
+            />
+          )}
+          <ProjectionMapCaption
+            report={report}
+            copy={copy}
+            mode={selectMode}
+            drawing={drawing}
+          />
+          {hoverCard}
+        </ProjectionSurface>
+      }
+    />
+  );
+}
+
+const NO_MARKERS: readonly ProjectionMarker[] = [];

package/src/projection/ui/ProjectionPairsControls.tsx

@@ -0,0 +1,58 @@
+import type { ReactElement } from 'react';
+
+import type { OverlayTier } from '../../overlay/core/overlayTiers.ts';
+import { OverlayNumber } from '../../overlay/ui/OverlayNumber.tsx';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+
+import { projectionPairsCeiling } from './projectionPairsCeiling.ts';
+
+/** What the pair grid's own stepper is drawn from. */
+export interface ProjectionPairsControlsProps {
+  /** What the grid is showing, already resolved against the result. */
+  options: ProjectionOptions;
+  /** Called with only the options that changed, for the viewer to merge. */
+  onChange: (patch: Partial<ProjectionOptions>) => void;
+  /** The words the bar writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** How many components the run produced, which caps the grid. */
+  axisCount: number;
+  /** Width of the figure, in pixels, which caps it again. */
+  width: number;
+  /**
+   * How much of itself the bar is writing. The caption in front of the
+   * stepper is the first thing to go, since the number beside it is what the
+   * reader is looking at and the name is in every announcement.
+   * @default 'full'
+   */
+  tier?: OverlayTier;
+}
+
+/**
+ * How many components the grid lays out, which is the one thing a reader of
+ * this tab actually changes.
+ *
+ * Its ceiling is three things 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 props - See {@link ProjectionPairsControlsProps}.
+ * @returns The stepper.
+ */
+export function ProjectionPairsControls(
+  props: ProjectionPairsControlsProps,
+): ReactElement {
+  const { options, onChange, copy, axisCount, width, tier = 'full' } = props;
+  const ceiling = projectionPairsCeiling(axisCount, width);
+
+  return (
+    <OverlayNumber
+      label={copy.help.pairCount.title}
+      hideLabel={tier !== 'full'}
+      value={options.pairCount}
+      min={ceiling.min}
+      max={ceiling.max}
+      onChange={(pairCount) => onChange({ pairCount })}
+    />
+  );
+}

package/src/projection/ui/ProjectionPairsMore.tsx

@@ -0,0 +1,95 @@
+import type { ReactElement } from 'react';
+
+import { OverlayNumber } from '../../overlay/ui/OverlayNumber.tsx';
+import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
+import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type {
+  ProjectionColorBy,
+  ProjectionOptions,
+} from '../core/projectionOptions.ts';
+import { PROJECTION_PANEL_NAME } from '../core/projectionStrings.ts';
+import { PROJECTION_TAB_DEFAULTS } from '../core/projectionTabDefaults.ts';
+
+import { projectionColourChoices } from './projectionMapChoices.ts';
+import { projectionPairsCeiling } from './projectionPairsCeiling.ts';
+
+/** What the grid keeps behind the cog is drawn from. */
+export interface ProjectionPairsMoreProps {
+  /** What the grid is showing, already resolved against the result. */
+  options: ProjectionOptions;
+  /** Called with only the options that changed, for the viewer to merge. */
+  onChange: (patch: Partial<ProjectionOptions>) => void;
+  /** The words the bar writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** What the set of groups is called, which is what `Colour by` offers. */
+  groupLabel: string;
+  /** How many components the run produced, which caps the grid. */
+  axisCount: number;
+  /** Width of the figure, in pixels, which caps it again. */
+  width: number;
+  /**
+   * Whether the samples carry groups at all.
+   * @default false
+   */
+  hasGroups?: boolean;
+}
+
+/**
+ * What the grid keeps behind the cog: how many components it lays out, what
+ * the colour means, and how large a dot is in a cell a fifth of the map's
+ * width.
+ *
+ * Three settings get no headings at all. A heading earns its line once the eye
+ * has more than about four names to run down, and a panel of three filed under
+ * two captions has been catalogued rather than laid out.
+ *
+ * The count is here as well as on the bar, and deliberately: the bar writes the
+ * number because it is what the reader is looking at, while the panel is the
+ * only place it is named, explained, and can be put back where it started.
+ * @param props - See {@link ProjectionPairsMoreProps}.
+ * @returns The panel behind the cog.
+ */
+export function ProjectionPairsMore(
+  props: ProjectionPairsMoreProps,
+): ReactElement {
+  const { options, onChange, copy, groupLabel, hasGroups = false } = props;
+  const { axisCount, width } = props;
+  const { bar, help, tab } = copy;
+  const ceiling = projectionPairsCeiling(axisCount, width);
+
+  return (
+    <OverlayPanel
+      title={tab.pairs}
+      onReset={() => onChange(PROJECTION_TAB_DEFAULTS.pairs)}
+    >
+      <OverlayNumber
+        label={PROJECTION_PANEL_NAME.pairCount}
+        help={help.pairCount}
+        value={options.pairCount}
+        min={ceiling.min}
+        max={ceiling.max}
+        onChange={(pairCount) => onChange({ pairCount })}
+      />
+      <OverlaySegmented<ProjectionColorBy>
+        label={PROJECTION_PANEL_NAME.colorBy}
+        help={help.colorBy}
+        value={options.colorBy}
+        disabled={!hasGroups}
+        options={projectionColourChoices(groupLabel, bar.uncoloured)}
+        onChange={(colorBy) => onChange({ colorBy })}
+      />
+      <OverlayNumber
+        label={PROJECTION_PANEL_NAME.pointRadius}
+        help={help.pointRadius}
+        value={options.pointRadius}
+        min={1}
+        max={12}
+        step={0.5}
+        digits={1}
+        unit="px"
+        onChange={(pointRadius) => onChange({ pointRadius })}
+      />
+    </OverlayPanel>
+  );
+}

package/src/projection/ui/ProjectionPairsTab.tsx

@@ -0,0 +1,159 @@
+import type { ReactElement } from 'react';
+import { useMemo } from 'react';
+
+import type { OverlayLegendEntry } from '../../overlay/ui/OverlayLegend.tsx';
+import { OverlayLegend } from '../../overlay/ui/OverlayLegend.tsx';
+import type { ScatterMatrixAxis } from '../../scatter/ui/ScatterMatrix.tsx';
+import { ScatterMatrix } from '../../scatter/ui/ScatterMatrix.tsx';
+import type { ScatterGroup } from '../../scatter/ui/ScatterPlot.tsx';
+import { SCATTER_MATRIX_MOST_AXES } from '../../scatter/ui/scatterMatrixLayout.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import { PROJECTION_COPY, fillCopy } from '../core/projectionCopy.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import { DEFAULT_PROJECTION_OPTIONS } from '../core/projectionOptions.ts';
+import type { ProjectionResult } from '../core/projectionResult.ts';
+import type { ResolvedProjectionGroups } from '../core/projectionSamples.ts';
+
+import { ProjectionSurface } from './ProjectionSurface.tsx';
+import { MINIMUM_OUTLINE_POINTS } from './projectionMapModel.ts';
+import { PROJECTION_TAB_HEIGHT } from './projectionTabStyles.ts';
+
+/** What {@link ProjectionPairsTab} needs. */
+export interface ProjectionPairsTabProps {
+  /** What the run produced. */
+  result: ProjectionResult;
+  /** The groups as every figure of this viewer draws them. */
+  groups: ResolvedProjectionGroups;
+  /**
+   * What the grid is showing.
+   * @default DEFAULT_PROJECTION_OPTIONS
+   */
+  options?: ProjectionOptions;
+  /**
+   * The words the tab writes.
+   * @default PROJECTION_COPY
+   */
+  copy?: ProjectionCopy;
+  /**
+   * Width of the grid, in pixels, from the viewer's measurement.
+   * @default 0 — nothing is drawn until the figure has been measured
+   */
+  width?: number;
+  /**
+   * Height the tab is given, in pixels. The cells are square, so it is a floor
+   * under the block rather than a size the grid is fitted to — without it the
+   * page jumps as the reader moves between the tabs.
+   * @default 420
+   */
+  height?: number;
+  /**
+   * The selected rows, as indices; the rest are drawn faint.
+   * @default undefined — every row is drawn at full strength
+   */
+  selected?: readonly number[];
+  /**
+   * Called with the pair a cell stands for, so the map can take it over.
+   * @default undefined — the cells are not clickable
+   */
+  onSelectPair?: (xAxis: number, yAxis: number) => void;
+  /**
+   * Value of the `data-testid` attribute of the wrapper.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * Every pair of the leading components, drawn as one grid, with the same group
+ * outlines the map draws.
+ *
+ * Colour is the group here, exactly as it is on the map, and that is the point
+ * of the tab: the grid has to read as the same picture seen from more angles,
+ * so a reader who found their clusters on the map can look for the pair that
+ * separates them better. The outlines are what makes that comparison quick —
+ * two rings that overlap in one cell and stand apart in another answer the
+ * tab's question without counting a single dot. Clicking a cell promotes its
+ * pair to the map rather than opening anything, so the finding stays in the
+ * figure the reader already knows how to interrogate.
+ * @param props - See {@link ProjectionPairsTabProps}.
+ * @returns The grid and its key.
+ */
+export function ProjectionPairsTab(
+  props: ProjectionPairsTabProps,
+): ReactElement {
+  const { result, groups, onSelectPair, testId } = props;
+  const { options = DEFAULT_PROJECTION_OPTIONS, copy = PROJECTION_COPY } =
+    props;
+  const { width = 0, height = PROJECTION_TAB_HEIGHT, selected } = props;
+
+  const axes = useMemo<ScatterMatrixAxis[]>(
+    () => result.axes.map((axis) => ({ name: axis.name, share: axis.share })),
+    [result.axes],
+  );
+  const inks = useMemo<ScatterGroup[]>(
+    () => groups.entries.map(({ id, label, color }) => ({ id, label, color })),
+    [groups],
+  );
+
+  const colored = options.colorBy === 'group' && inks.length > 0;
+
+  return (
+    <div style={{ minHeight: height }} data-testid={testId}>
+      <ScatterMatrix
+        scores={result.scores}
+        axes={axes}
+        count={Math.min(options.pairCount, SCATTER_MATRIX_MOST_AXES)}
+        width={width}
+        groupOf={colored ? groups.groupOf : undefined}
+        groups={colored ? inks : undefined}
+        ellipse={colored ? options.ellipse : null}
+        ellipseMinimumPoints={MINIMUM_OUTLINE_POINTS}
+        selected={selected}
+        pointRadius={Math.max(1, options.pointRadius - CROWDED_CELL)}
+        onSelectPair={onSelectPair}
+        overlay={
+          colored ? (
+            <ProjectionSurface>
+              <OverlayLegend
+                placement="top-right"
+                title={fillCopy(copy.legend.mapNoEllipse, {
+                  groups: groups.label,
+                })}
+                entries={legendEntries(groups)}
+              />
+            </ProjectionSurface>
+          ) : undefined
+        }
+      />
+    </div>
+  );
+}
+
+/**
+ * The key: the same groups the map lists, in the same order and the same
+ * colours, because the two tabs have to be read as one picture.
+ *
+ * It floats in the top right corner rather than standing under the grid. The
+ * cell it covers a little of is the mirror of one across the diagonal, so
+ * unlike every other corner of this figure, nothing there is unique.
+ * @param groups - The groups as every figure draws them.
+ * @returns The entries.
+ */
+function legendEntries(groups: ResolvedProjectionGroups): OverlayLegendEntry[] {
+  return groups.entries.map((entry) => ({
+    id: entry.id,
+    label: entry.label,
+    color: entry.color,
+    count: entry.count,
+  }));
+}
+
+/**
+ * How much smaller a dot is in a cell of the grid than on the map.
+ *
+ * A cell is a fifth of the map's width holding every one of its samples, so a
+ * dot sized for the map fills it in solid; the grid answers "does this pair
+ * separate my groups", which needs the shape of the cloud rather than the
+ * individual sample.
+ */
+const CROWDED_CELL = 1.5;