react-cheminfo 0.9.0 → 0.11.0

package/src/projection/core/variableAxis.ts

@@ -0,0 +1,161 @@
+/** Measurements laid out along a number line — a spectrum, a chromatogram. */
+export interface ContinuousVariableAxis {
+  /** Discriminant. */
+  kind: 'continuous';
+  /** One value per measurement, in column order, e.g. wavenumbers. */
+  values: readonly number[];
+  /** What the axis measures, e.g. `Wavenumber`. */
+  label: string;
+  /**
+   * Written after a value, e.g. `cm⁻¹`.
+   * @default '' — no unit is written
+   */
+  unit?: string;
+  /**
+   * Which way the axis runs. `descending` puts high values on the left, the
+   * way an infrared or an NMR spectrum is read.
+   * @default 'ascending'
+   */
+  direction?: 'ascending' | 'descending';
+}
+
+/**
+ * Measurements picked out of a spectrum rather than sampled across one — the
+ * m/z of a peak list, the shifts of an NMR signal list, a band table.
+ *
+ * It carries the same fields as a continuous axis and is a separate kind
+ * because the two are drawn differently and the difference is not one the
+ * panel can see in the numbers. A sampled spectrum sits on a grid, so its
+ * measurements can be laid out in even slots and joined with a line without
+ * saying anything untrue. A peak list does not: the gap between two peaks is a
+ * measurement in its own right, laying them out evenly would draw an empty
+ * stretch of a spectrum as though it were crowded, and joining them with a
+ * line would claim a signal between two masses that were measured apart.
+ * Peaks are drawn as sticks standing where they were measured.
+ */
+export interface PeaksVariableAxis {
+  /** Discriminant. */
+  kind: 'peaks';
+  /** Where each measurement sits, in column order, e.g. the m/z of each peak. */
+  values: readonly number[];
+  /** What the axis measures, e.g. `m/z`. */
+  label: string;
+  /**
+   * Written after a value, e.g. `Da`.
+   * @default '' — no unit is written
+   */
+  unit?: string;
+}
+
+/** Measurements that are a list of names — the columns of a table. */
+export interface NamedVariableAxis {
+  /** Discriminant. */
+  kind: 'named';
+  /** One name per measurement, in column order, e.g. `Petal length`. */
+  names: readonly string[];
+  /**
+   * What the names are, for the axis caption.
+   * @default 'Measurement'
+   */
+  label?: string;
+}
+
+/**
+ * How the original measurements are laid out, which decides how they are drawn.
+ *
+ * The caller states it; the panel never guesses from the data. A continuous
+ * axis is drawn as a line across even slots, a named one as bars from the zero
+ * line, and a peak list as sticks standing at the values themselves on a real
+ * number line.
+ */
+export type VariableAxis =
+  ContinuousVariableAxis | NamedVariableAxis | PeaksVariableAxis;
+
+/**
+ * How many measurements an axis carries.
+ * @param axis - The axis.
+ * @returns The count.
+ */
+export function variableCount(axis: VariableAxis): number {
+  return axis.kind === 'named' ? axis.names.length : axis.values.length;
+}
+
+/**
+ * Where each measurement sits, for an axis that is a number line.
+ * @param axis - The axis.
+ * @returns The positions, or `null` for a named axis, which has none.
+ */
+export function variablePositions(
+  axis: VariableAxis,
+): readonly number[] | null {
+  return axis.kind === 'named' ? null : axis.values;
+}
+
+/**
+ * What one measurement is called, written out.
+ * @param axis - The axis.
+ * @param index - Which measurement, from 0.
+ * @param decimals - Decimals the value is rounded to, from `variableDecimals`,
+ * for a label written under a tick.
+ * @default undefined — the number is written as it was handed in, which is
+ * what a readout naming one slot wants
+ * @returns The name, or the value with its unit — `1650 cm⁻¹`. An index
+ * outside the axis gives an empty string.
+ */
+export function variableLabel(
+  axis: VariableAxis,
+  index: number,
+  decimals?: number,
+): string {
+  if (!Number.isInteger(index) || index < 0) return '';
+  if (axis.kind === 'named') return axis.names[index] ?? '';
+
+  const value = axis.values[index];
+  if (value === undefined) return '';
+  // Asked for in full, a number is written as it was handed in: rounding a
+  // wavenumber to a tidier one would name a slot the reader cannot find in
+  // their own file.
+  const written =
+    decimals === undefined ? String(value) : String(rounded(value, decimals));
+  const unit = axis.unit ?? '';
+  return unit === '' ? written : `${written} ${unit}`;
+}
+
+/**
+ * How many decimals the axis writes its own values with.
+ *
+ * About a hundred steps across the span the axis covers, which is finer than
+ * the dozen-odd ticks a chart labels and coarse enough to drop what a
+ * resampling left behind: a spectrum landed on its own grid carries values
+ * like 878.9834, where every digit past the second says something about the
+ * grid rather than about the measurement, so a tick reads `879 cm⁻¹`. A named
+ * axis has no values to write and gets none.
+ * @param axis - The axis.
+ * @returns The decimals, from 0 to 6.
+ */
+export function variableDecimals(axis: VariableAxis): number {
+  if (axis.kind === 'named') return 0;
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  for (const value of axis.values) {
+    if (!Number.isFinite(value)) continue;
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  const span = max - min;
+  if (!Number.isFinite(span) || span <= 0) return MOST_DECIMALS;
+  const decimals = AXIS_DIGITS - Math.ceil(Math.log10(span));
+  return Math.min(MOST_DECIMALS, Math.max(0, decimals));
+}
+
+function rounded(value: number, decimals: number): number {
+  if (!Number.isFinite(value)) return value;
+  const factor = 10 ** decimals;
+  return Math.round(value * factor) / factor;
+}
+
+/** Digits kept above the decimal point when the axis writes a value. */
+const AXIS_DIGITS = 2;
+
+/** Decimals an axis is never written past, however narrow its span. */
+const MOST_DECIMALS = 6;

package/src/projection/core/variablesView.ts

@@ -0,0 +1,53 @@
+import type { ProjectionVariablesView } from './projectionOptions.ts';
+import type { ProjectionLoadings } from './projectionResult.ts';
+
+/**
+ * The view that can actually be drawn from what the result carries.
+ *
+ * Three of the four views need something beyond the weights, and a result is
+ * free not to publish it: `effect` walks from the average sample along the
+ * component, so it needs both the average and the spread; `rescaled` undoes a
+ * scaling, so it needs the scaling; `sample` rebuilds one sample from the
+ * components, so it needs the average and a sample to rebuild. What is missing
+ * falls back to `weights`, which every result can fill.
+ *
+ * It is one function because it is one question, asked twice — once by the
+ * settings bar deciding which views to offer, and once by the panels deciding
+ * what to draw. Two answers is not a tidiness problem: a bar that offers a
+ * view the panels refuse leaves a reader picking `sample` and watching the
+ * weights redraw, with nothing anywhere saying why.
+ *
+ * `sampleScores` is what tells the two callers apart, and leaving it out is a
+ * third answer rather than a shorthand for none. The bar cannot know what is
+ * selected — a selection is not part of a result — so it omits the argument
+ * and asks only whether the *result* could support the view at all. The panels
+ * always know, so they pass what is selected, and an empty array is a real
+ * answer: nothing to rebuild, so nothing to draw.
+ * @param view - The view that was asked for.
+ * @param loadings - What loads onto each axis, or nothing when the result
+ * published none.
+ * @param sampleScores - The selected sample's scores; empty for a selection of
+ * nothing, omitted by a caller that cannot see the selection.
+ * @returns The view to draw, which is the one asked for or `weights`.
+ */
+export function drawableVariablesView(
+  view: ProjectionVariablesView,
+  loadings: ProjectionLoadings | undefined,
+  sampleScores?: readonly number[],
+): ProjectionVariablesView {
+  if (loadings === undefined || view === 'weights') return 'weights';
+  if (view === 'rescaled') {
+    return loadings.scales === undefined ? 'weights' : 'rescaled';
+  }
+  if (view === 'effect') {
+    const walkable =
+      loadings.mean !== undefined && loadings.spread !== undefined;
+    return walkable ? 'effect' : 'weights';
+  }
+  // `sample` is rebuilt from the average and the sample's own scores. It never
+  // reads the spread, which is what walking to the ends of a component needs
+  // and this does not do.
+  if (loadings.mean === undefined) return 'weights';
+  if (sampleScores === undefined) return 'sample';
+  return sampleScores.length > 0 ? 'sample' : 'weights';
+}

package/src/projection/ui/PcaViewer.tsx

@@ -0,0 +1,80 @@
+import type { ReactElement } from 'react';
+import { useMemo } from 'react';
+
+import type { PcaLike } from '../core/pcaLike.ts';
+import type { PcaResultOptions } from '../core/pcaResult.ts';
+import { pcaResult } from '../core/pcaResult.ts';
+
+import { ProjectionViewer } from './ProjectionViewer.tsx';
+import type { ProjectionViewerProps } from './projectionViewerProps.ts';
+
+/** What {@link PcaViewer} needs on top of what every projection viewer takes. */
+export interface PcaViewerProps
+  extends
+    Omit<ProjectionViewerProps, 'result'>,
+    Omit<PcaResultOptions, 'method'> {
+  /**
+   * The fitted model. It is described structurally, so `ml-pca`'s `PCA`
+   * satisfies it as it is and this package never imports `ml-pca`.
+   */
+  pca: PcaLike;
+}
+
+/**
+ * A fitted principal component analysis, shown as a map a reader can
+ * interrogate.
+ *
+ * It is {@link ProjectionViewer} with one call in front of it: everything the
+ * four tabs draw is built by `pcaResult` into the same record a k-means or a
+ * UMAP run fills in by hand, and no tab, no layer and no callback below this
+ * line knows what a principal component is.
+ *
+ * `projected` is the reason to reach for this rather than call `pcaResult`
+ * first: samples handed to it took no part in choosing where the axes point,
+ * so the map draws them hollow and says so, and a reader can see at a glance
+ * which points the model has already accounted for and which it is being asked
+ * about.
+ * @param props - See {@link PcaViewerProps}.
+ * @returns The viewer.
+ */
+export function PcaViewer(props: PcaViewerProps): ReactElement {
+  const {
+    pca,
+    rows,
+    projected,
+    variables,
+    scores,
+    scaled,
+    count,
+    valueLabel,
+    signConvention,
+    ...viewer
+  } = props;
+
+  const result = useMemo(
+    () =>
+      pcaResult(pca, {
+        rows,
+        projected,
+        variables,
+        scores,
+        scaled,
+        count,
+        valueLabel,
+        signConvention,
+      }),
+    [
+      count,
+      pca,
+      projected,
+      rows,
+      scaled,
+      scores,
+      signConvention,
+      valueLabel,
+      variables,
+    ],
+  );
+
+  return <ProjectionViewer {...viewer} result={result} />;
+}

package/src/projection/ui/ProjectionBar.tsx

@@ -0,0 +1,222 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useMemo } from 'react';
+
+import { FigureDownload } from '../../download/ui/FigureDownload.tsx';
+import type { OverlayMetrics } from '../../overlay/core/overlayMetrics.ts';
+import { overlayMetrics } from '../../overlay/core/overlayMetrics.ts';
+import { OverlayBar } from '../../overlay/ui/OverlayBar.tsx';
+import { OverlayInfo } from '../../overlay/ui/OverlayInfo.tsx';
+import { useCoarsePointer } from '../../overlay/ui/overlaySurface.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type { ProjectionResult } from '../core/projectionResult.ts';
+import type { ProjectionTab } from '../core/projectionTabs.ts';
+
+import { ProjectionSurface } from './ProjectionSurface.tsx';
+import { ProjectionTabStrip } from './ProjectionTabStrip.tsx';
+import {
+  projectionBarEndRoom,
+  projectionBarGlyphs,
+  projectionBarTier,
+} from './projectionBarModel.ts';
+import { projectionBarReadings } from './projectionBarReadings.ts';
+import { projectionBarSlots } from './projectionBarSlots.tsx';
+import {
+  PROJECTION_CAPTION_TEXT_STYLE,
+  projectionBarEndStyle,
+  projectionBarRowStyle,
+  projectionFoldedCaptionStyle,
+} from './projectionBarStyles.ts';
+import type { ProjectionMapView } from './projectionMapView.ts';
+import type { ProjectionModels } from './projectionTabModels.ts';
+import type { ProjectionStateApi } from './useProjectionState.ts';
+
+/** What {@link ProjectionBar} needs. */
+export interface ProjectionBarProps {
+  /** The tab, the options and the selection every tab shares. */
+  state: ProjectionStateApi;
+  /** What the run produced, whatever produced it. */
+  result: ProjectionResult;
+  /** The words the viewer writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** The two figures the bar explains and a tab draws. */
+  models: ProjectionModels;
+  /** The map's frame and the three buttons that change it. */
+  map: ProjectionMapView;
+  /** Stem of the `id` every pill carries, for the panel to name its tab with. */
+  baseId: string;
+  /** The `id` of the panel the pills drive, which is also what is saved. */
+  panelId: string;
+  /** What a figure saved from the bar is called, without its extension. */
+  fileName: string;
+  /** Width of the viewer, in pixels, which decides how much it writes. */
+  width: number;
+}
+
+/**
+ * One bar across the top of the figure: the views at the start, the settings
+ * of the view showing at the end, and the question mark between them.
+ *
+ * It belongs to the viewer rather than to any tab because it is the
+ * component's own chrome — a reader moves between four figures with it, and
+ * four bars, three of them hidden, would be four places for that row to sit a
+ * pixel differently.
+ *
+ * It stays one row at every width, because a bar that wrapped would change the
+ * figure's height as the host page resized. What a narrowing figure costs the
+ * reader is words rather than controls: the key word in front of each setting
+ * goes first, then the long form of the view names, then the boxes around the
+ * settings, which gather into one chip still reading `Species · 95%`. Only on
+ * the narrowest figures does anything leave the row at all, and it is the
+ * question mark — whose paragraph is then written at the head of the panel the
+ * cog opens, so nothing is lost, only moved.
+ *
+ * The one thing on the bar that acts on the figure rather than describing it
+ * is the save glyph, which is why it rides beside the question mark rather than
+ * among the settings: it is offered on every view, because every view draws a
+ * figure somebody may want to keep, and it saves whatever the box below the bar
+ * is currently holding — one map, or the sixteen charts of a pair grid.
+ * @param props - See {@link ProjectionBarProps}.
+ * @returns The bar.
+ */
+export function ProjectionBar(props: ProjectionBarProps): ReactElement {
+  const { state, result, copy, models, map, baseId, panelId } = props;
+  const { fileName, width } = props;
+  const { tab, tabs, options, groups, selected, setOptions, setTab } = state;
+
+  // Read here rather than off the surface below, because the row the bar is
+  // laid into is the surface's own parent: it has to know how tall a control
+  // will be before there is a surface to ask.
+  const pointer = useCoarsePointer() ? 'coarse' : 'fine';
+  const metrics = overlayMetrics('compact', pointer);
+  const strip = tabs.length > 1;
+  const labels = useMemo(
+    () => (strip ? tabNames(tabs, copy.tab) : NO_LABELS),
+    [strip, tabs, copy],
+  );
+  const shortLabels = useMemo(
+    () => (strip ? tabNames(tabs, copy.shortTab) : NO_LABELS),
+    [strip, tabs, copy],
+  );
+
+  const readings = projectionBarReadings({ tab, copy, options, groups });
+  const room = {
+    tabLabels: labels,
+    shortTabLabels: shortLabels,
+    readings,
+    glyphs: projectionBarGlyphs(tab),
+  };
+  const tier = projectionBarTier(width, room, metrics);
+  const strippable = Math.max(
+    metrics.buttonSize,
+    width - projectionBarEndRoom(room, metrics, tier),
+  );
+
+  const slots = projectionBarSlots({
+    tab,
+    result,
+    copy,
+    models,
+    map,
+    options,
+    groups,
+    selected,
+    width,
+    readings,
+    tier,
+    onChange: setOptions,
+  });
+  const folded = tier === 'tiny' && slots.info !== '';
+
+  return (
+    <ProjectionSurface width={width}>
+      <div style={projectionBarRowStyle(metrics)}>
+        <OverlayBar
+          placement="stretch"
+          label={copy.action.options}
+          collapsed={false}
+          morePadded={false}
+          end={<div style={projectionBarEndStyle(metrics)}>{slots.end}</div>}
+          more={
+            folded ? withCaption(slots.info, slots.more, metrics) : slots.more
+          }
+          tools={
+            <FigureDownload
+              targetId={panelId}
+              fileName={`${fileName}-${tab}`}
+              label={copy.action.download}
+            />
+          }
+          info={
+            folded || slots.info === '' ? undefined : (
+              <OverlayInfo>{slots.info}</OverlayInfo>
+            )
+          }
+        >
+          {strip ? (
+            <ProjectionTabStrip
+              tabs={tabs}
+              tab={tab}
+              onTabChange={setTab}
+              labels={copy.tab}
+              shortLabels={copy.shortTab}
+              tier={tier}
+              maxWidth={strippable}
+              baseId={baseId}
+              panelId={panelId}
+            />
+          ) : null}
+        </OverlayBar>
+      </div>
+    </ProjectionSurface>
+  );
+}
+
+/**
+ * What each tab showing is called, in one of the two lengths.
+ * @param tabs - The tabs the result can fill, in reading order.
+ * @param names - What each tab is called at that length.
+ * @returns The names, in the same order.
+ */
+function tabNames(
+  tabs: readonly ProjectionTab[],
+  names: Readonly<Record<ProjectionTab, string>>,
+): readonly string[] {
+  const labels: string[] = [];
+  for (const tab of tabs) labels.push(names[tab]);
+  return labels;
+}
+
+/**
+ * The figure's explanation at the head of the panel the cog opens.
+ *
+ * On the narrowest figures the question mark is the one glyph that leaves the
+ * row, because the settings and the second tier both have to stay reachable —
+ * so its paragraph is written here instead. A reader short of room is exactly
+ * the reader who has not been told what they are looking at, which is why it
+ * is moved rather than dropped.
+ *
+ * It is a band above the panel rather than a row inside it: the panel's rows
+ * are settings the reader changes, and a paragraph filed among them is one
+ * more thing to scan past on the way to the switch they came for.
+ * @param caption - The paragraph the question mark used to open.
+ * @param more - The panel the cog already held.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The panel's contents.
+ */
+function withCaption(
+  caption: string,
+  more: ReactNode,
+  metrics: OverlayMetrics,
+): ReactNode {
+  return (
+    <>
+      <div style={projectionFoldedCaptionStyle(metrics)}>
+        <p style={PROJECTION_CAPTION_TEXT_STYLE}>{caption}</p>
+      </div>
+      {more}
+    </>
+  );
+}
+
+/** No pills at all, which is what one tab gets. */
+const NO_LABELS: readonly string[] = [];

package/src/projection/ui/ProjectionMapCaption.tsx

@@ -0,0 +1,96 @@
+import type { ReactElement } from 'react';
+import { useEffect, useState } from 'react';
+
+import { OverlayCaption } from '../../overlay/ui/OverlayCaption.tsx';
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+
+/** What a gesture just picked out, and when. */
+export interface SelectionReport {
+  /** The sentence to show, already written out. */
+  text: string;
+  /** A number that rises with every gesture, so two identical reports are still two reports. */
+  at: number;
+}
+
+/** What {@link ProjectionMapCaption} needs. */
+export interface ProjectionMapCaptionProps {
+  /** What the last gesture picked out, or `null` before there was one. */
+  report: SelectionReport | null;
+  /** The words the map writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** What a plain drag does, which is what a drag under way is promised to do. */
+  mode: ScatterSelectionMode;
+  /**
+   * Whether a lasso is being drawn right now.
+   * @default false
+   */
+  drawing?: boolean;
+}
+
+/**
+ * The one sentence on this figure that is not behind the question mark.
+ *
+ * Everything the map has to say about itself standing still — what a dot is,
+ * what an outline holds — waits behind the `?` in the bar, because an embedded
+ * figure cannot spend three lines of somebody else's page on a paragraph most
+ * readers will not read twice. This sentence is the exception, and it is a
+ * different kind of thing: it says what is happening *now*, and a reader half
+ * way through a lasso cannot open a popover to find out whether letting go
+ * will replace what they had already picked or add to it.
+ *
+ * So it appears only while a gesture is under way, and for a few seconds after
+ * one, and it takes no room at all in between. That is also what lets it sit
+ * across the strip the horizontal axis is titled in: a standing caption there
+ * would cost the reader the axis name for good, while this one hands it back
+ * on its own a moment later, and during a drag the reader is watching the loop
+ * rather than the axis.
+ * @param props - See {@link ProjectionMapCaptionProps}.
+ * @returns The line, or nothing at all when nothing is happening.
+ */
+export function ProjectionMapCaption(
+  props: ProjectionMapCaptionProps,
+): ReactElement | null {
+  const { report, copy, mode, drawing = false } = props;
+  const [faded, setFaded] = useState(0);
+
+  useEffect(() => {
+    if (report === null) return undefined;
+    const { at } = report;
+    const timer = setTimeout(() => setFaded(at), ANNOUNCEMENT_MS);
+    return () => clearTimeout(timer);
+  }, [report]);
+
+  if (drawing) {
+    return (
+      <OverlayCaption tone="strong" live>
+        {copy.sentence[LASSO_SENTENCES[mode]]}
+      </OverlayCaption>
+    );
+  }
+  if (report !== null && faded !== report.at) {
+    return (
+      <OverlayCaption tone="strong" live>
+        {report.text}
+      </OverlayCaption>
+    );
+  }
+  return null;
+}
+
+/** Which sentence describes a drag under way, per mode. */
+const LASSO_SENTENCES = {
+  replace: 'lassoReplace',
+  add: 'lassoAdd',
+  remove: 'lassoRemove',
+} as const satisfies Record<
+  ScatterSelectionMode,
+  keyof ProjectionCopy['sentence']
+>;
+
+/**
+ * How long a report holds the line. Long enough to read a short sentence
+ * twice, short enough that a reader who has moved on is not still being told
+ * what they did.
+ */
+const ANNOUNCEMENT_MS = 4000;