react-cheminfo 0.9.0 → 0.11.0

package/src/projection/ui/ProjectionVariablesMore.tsx

@@ -0,0 +1,144 @@
+import type { ReactElement } from 'react';
+
+import { OverlayGroup } from '../../overlay/ui/OverlayGroup.tsx';
+import { OverlayNumber } from '../../overlay/ui/OverlayNumber.tsx';
+import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
+import { OverlaySelect } from '../../overlay/ui/OverlaySelect.tsx';
+import { OverlayToggle } from '../../overlay/ui/OverlayToggle.tsx';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import type {
+  ProjectionOptions,
+  ProjectionVariablesView,
+} from '../core/projectionOptions.ts';
+import {
+  PROJECTION_PANEL_NAME,
+  PROJECTION_PANEL_SECTION,
+} from '../core/projectionStrings.ts';
+import { PROJECTION_TAB_DEFAULTS } from '../core/projectionTabDefaults.ts';
+
+import type { ProjectionVariablesAvailability } from './projectionViewChoices.ts';
+import { projectionViewChoices } from './projectionViewChoices.ts';
+
+/** What the panels keep behind the cog is drawn from. */
+export interface ProjectionVariablesMoreProps extends ProjectionVariablesAvailability {
+  /** Every option the panels are drawn from. */
+  options: ProjectionOptions;
+  /** The words the bar writes, already merged over the defaults. */
+  copy: ProjectionCopy;
+  /** How many components the run produced, which caps the panel count. */
+  axisCount: number;
+  /** Whether the measurements lie along a number line, which fixes their order. */
+  continuous: boolean;
+  /** Called with only the options that changed, for the viewer to merge. */
+  onChange: (patch: Partial<ProjectionOptions>) => void;
+}
+
+/**
+ * What the "what differs" tab keeps behind the cog: which view the panels
+ * draw, how many of them there are, what they are measured against, and how
+ * the marks along them are drawn.
+ *
+ * Six settings in one column is a list the eye slides off, so the two that
+ * decide what a panel *is* stand at the top under no heading at all, and the
+ * rest are filed under what they are about — the scale the panels are read
+ * against, then the marks drawn on them. The first two need no heading
+ * precisely because they are first: a caption over the top of a panel repeats
+ * the panel's own title.
+ * @param props - See {@link ProjectionVariablesMoreProps}.
+ * @returns The panel behind the cog.
+ */
+export function ProjectionVariablesMore(
+  props: ProjectionVariablesMoreProps,
+): ReactElement {
+  const { options, copy, axisCount, continuous, onChange } = props;
+  const { canShowEffect, canRescale, canPickSample } = props;
+  const { help, tab } = copy;
+
+  return (
+    <OverlayPanel
+      title={tab.variables}
+      onReset={() => onChange(PROJECTION_TAB_DEFAULTS.variables)}
+    >
+      <OverlaySelect<ProjectionVariablesView>
+        label={PROJECTION_PANEL_NAME.variablesView}
+        help={help.variablesView}
+        value={options.variablesView}
+        options={projectionViewChoices(copy, {
+          canShowEffect,
+          canRescale,
+          canPickSample,
+        })}
+        onChange={(variablesView) => onChange({ variablesView })}
+      />
+      <OverlayNumber
+        label={PROJECTION_PANEL_NAME.variablesCount}
+        help={help.variablesCount}
+        value={options.variablesCount}
+        min={1}
+        max={Math.max(1, axisCount)}
+        onChange={(variablesCount) => onChange({ variablesCount })}
+      />
+      <OverlayGroup label={PROJECTION_PANEL_SECTION.scale}>
+        <OverlayToggle
+          label={PROJECTION_PANEL_NAME.sharedScale}
+          help={help.sharedScale}
+          checked={options.sharedScale}
+          onChange={(sharedScale) => onChange({ sharedScale })}
+        />
+        <OverlayNumber
+          label={PROJECTION_PANEL_NAME.spread}
+          help={help.spread}
+          value={options.spread}
+          min={SMALLEST_REACH}
+          max={LARGEST_REACH}
+          step={SMALLEST_REACH}
+          digits={1}
+          disabled={options.variablesView !== 'effect'}
+          onChange={(spread) => onChange({ spread })}
+        />
+      </OverlayGroup>
+      <OverlayGroup label={PROJECTION_PANEL_SECTION.drawing}>
+        <OverlayToggle
+          label={PROJECTION_PANEL_NAME.showAverage}
+          help={help.showAverage}
+          checked={options.showAverage}
+          onChange={(showAverage) => onChange({ showAverage })}
+        />
+        <OverlaySegmented
+          label={PROJECTION_PANEL_NAME.variableOrder}
+          help={help.variableOrder}
+          value={options.variableOrder}
+          disabled={continuous}
+          options={ORDER_CHOICES}
+          onChange={(variableOrder) => onChange({ variableOrder })}
+        />
+      </OverlayGroup>
+    </OverlayPanel>
+  );
+}
+
+/**
+ * The two orders the bars of a panel can be drawn in.
+ *
+ * Both are written as what the reader gets rather than as what the code does,
+ * because "original" and "strongest" name the sort rather than the picture it
+ * produces.
+ */
+const ORDER_CHOICES: ReadonlyArray<
+  OverlayOption<ProjectionOptions['variableOrder']>
+> = [
+  { value: 'original', label: 'Your order' },
+  { value: 'strongest', label: 'Strongest first' },
+];
+
+/**
+ * How far the average sample may be pushed, in standard deviations.
+ *
+ * Half a deviation is the smallest step worth a redraw, and four reaches past
+ * every sample of a well-behaved component in both directions, so anything
+ * beyond it draws a sample nobody in the table resembles.
+ */
+const SMALLEST_REACH = 0.5;
+const LARGEST_REACH = 4;

package/src/projection/ui/ProjectionVariablesTab.tsx

@@ -0,0 +1,216 @@
+import type { ReactElement } from 'react';
+import { useMemo } from 'react';
+
+import { chartAxisTitle } from '../../chart/core/chartLabels.ts';
+import type { ChartTrackEvent } from '../../chart/ui/TrackedLineChart.tsx';
+import { TrackedLineChart } from '../../chart/ui/TrackedLineChart.tsx';
+import { TrackedStickChart } from '../../chart/ui/TrackedStickChart.tsx';
+import type { LoadingProfiles } from '../core/loadingProfiles.ts';
+import type { ProjectionCopy } from '../core/projectionCopy.ts';
+import { PROJECTION_COPY } from '../core/projectionCopy.ts';
+import type { ProjectionOptions } from '../core/projectionOptions.ts';
+import { DEFAULT_PROJECTION_OPTIONS } from '../core/projectionOptions.ts';
+
+import {
+  PANEL_TITLE_ROOM,
+  PANEL_TITLE_STYLE,
+  PROJECTION_TAB_HEIGHT,
+  SMALLEST_PANEL,
+  STACK_STYLE,
+  SWATCH_STYLE,
+} from './projectionTabStyles.ts';
+import type { ProjectionVariableTrack } from './projectionVariablesModel.ts';
+import {
+  namesOfSlots,
+  panelSeries,
+  panelSticks,
+  ticksOfSlots,
+  variableTrack,
+  writeValue,
+} from './projectionVariablesModel.ts';
+import { axisCaption, legendTitle } from './projectionVariablesWords.ts';
+
+export type { ProjectionVariableTrack } from './projectionVariablesModel.ts';
+
+/** What {@link ProjectionVariablesTab} needs. */
+export interface ProjectionVariablesTabProps {
+  /**
+   * The panels as the viewer built them, or `null` when the run reported no
+   * weights and there is nothing to draw.
+   */
+  profiles: LoadingProfiles | null;
+  /**
+   * What the panels are showing.
+   * @default DEFAULT_PROJECTION_OPTIONS
+   */
+  options?: ProjectionOptions;
+  /**
+   * The words the tab writes.
+   * @default PROJECTION_COPY
+   */
+  copy?: ProjectionCopy;
+  /**
+   * What the one selected sample is called, which the `sample` view rebuilds.
+   * @default 'the selected sample'
+   */
+  sampleName?: string;
+  /**
+   * Width of the panels, in pixels, from the viewer's measurement.
+   * @default 0 — nothing is drawn until the figure has been measured
+   */
+  width?: number;
+  /**
+   * Height the whole stack is given, in pixels, shared out between the panels.
+   * @default 420
+   */
+  height?: number;
+  /**
+   * Called on every measurement the pointer enters, and with `null` when it
+   * leaves. The readout is written here rather than left to the caller, so a
+   * page lighting a band on a spectrum beside the viewer never has to work out
+   * what the slot it was handed is called.
+   * @default undefined
+   */
+  onTrackVariable?: (track: ProjectionVariableTrack | null) => void;
+  /**
+   * How a number is written in the readout.
+   * @default a rounding to three decimals with the trailing zeros dropped
+   */
+  formatValue?: (value: number) => string;
+  /**
+   * Value of the `data-testid` attribute of the stack.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * One panel per component, each drawing what that component leans on.
+ *
+ * Colour is the component here and nothing else: the palette's component order
+ * is disjoint from its group order over the first four of each, so a reader
+ * who learnt "blue is setosa" on the map never reads "blue is PC 1" here as
+ * though it meant the same thing. A component's direction is arbitrary, so its
+ * sign is carried by geometry — above or below the zero line — and never by a
+ * second colour, which would advertise a meaning the arithmetic does not have.
+ * Nothing is coloured along the horizontal axis either: a rainbow across the
+ * measurements encodes the slot number, which the reader can already see.
+ *
+ * The panels carry no key. Every one of them is titled with its own swatch and
+ * its own name, so a key would repeat what the titles already say; the one
+ * thing the titles cannot say — that the faint grey line behind them is the
+ * average sample — is the first thing the question mark in the bar does.
+ * @param props - See {@link ProjectionVariablesTabProps}.
+ * @returns The stack of panels.
+ */
+export function ProjectionVariablesTab(
+  props: ProjectionVariablesTabProps,
+): ReactElement {
+  const { profiles, onTrackVariable, testId } = props;
+  const { options = DEFAULT_PROJECTION_OPTIONS, copy = PROJECTION_COPY } =
+    props;
+  const { width = 0, height = PROJECTION_TAB_HEIGHT } = props;
+  const { sampleName = A_SAMPLE, formatValue = writeValue } = props;
+
+  const categories = useMemo(() => namesOfSlots(profiles), [profiles]);
+  const tickLabels = useMemo(() => ticksOfSlots(profiles), [profiles]);
+
+  function report(panel: number, event: ChartTrackEvent | null): void {
+    if (onTrackVariable === undefined || profiles === null) return;
+    onTrackVariable(
+      event === null
+        ? null
+        : variableTrack(profiles, event.index, panel, formatValue),
+    );
+  }
+
+  if (profiles === null) {
+    return <div style={STACK_STYLE} data-testid={testId} />;
+  }
+
+  const average = options.showAverage && profiles.mean !== undefined;
+  const last = profiles.profiles.length - 1;
+  const room = Math.max(SMALLEST_PANEL, Math.floor(height / (last + 1)));
+  const bars = profiles.axis.kind === 'named' && !inTheirOwnUnits(profiles);
+  const peaks = profiles.axis.kind === 'peaks' ? profiles.axis : null;
+  const scale = profiles.sharedScale
+    ? { domain: [profiles.domain.min, profiles.domain.max] as const }
+    : {};
+
+  return (
+    <div style={STACK_STYLE} data-testid={testId}>
+      {profiles.profiles.map((profile, panel) => (
+        <div key={profile.index}>
+          <span style={PANEL_TITLE_STYLE}>
+            <span style={{ ...SWATCH_STYLE, background: profile.color }} />
+            {chartAxisTitle(profile.label, { share: profile.share })}
+          </span>
+          {peaks === null ? (
+            <TrackedLineChart
+              categories={categories}
+              tickLabels={tickLabels}
+              series={panelSeries(profiles, profile, bars, average, copy)}
+              width={width}
+              height={room - PANEL_TITLE_ROOM}
+              y={{ ...scale, label: profiles.valueLabel }}
+              xLabel={panel === last ? axisCaption(profiles.axis) : undefined}
+              label={`${profile.label}. ${legendTitle(profiles, copy, sampleName)}`}
+              onTrack={(event) => {
+                report(panel, event);
+              }}
+            />
+          ) : (
+            <TrackedStickChart
+              positions={positionsOf(peaks.values, profiles.order)}
+              categories={categories}
+              series={panelSticks(profiles, profile, average, copy)}
+              width={width}
+              height={room - PANEL_TITLE_ROOM}
+              y={{ ...scale, label: profiles.valueLabel }}
+              xLabel={panel === last ? axisCaption(profiles.axis) : undefined}
+              label={`${profile.label}. ${legendTitle(profiles, copy, sampleName)}`}
+              onTrack={(event) => {
+                report(panel, event);
+              }}
+            />
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/**
+ * Where each drawn slot sits on the axis.
+ *
+ * A slot is not a measurement: the panels can be ordered by strength rather
+ * than by position, and a stick has to stand where its measurement was
+ * measured whichever order they were drawn in.
+ * @param values - Where each measurement sits.
+ * @param order - Which measurement each slot holds.
+ * @returns One position per slot.
+ */
+function positionsOf(values: readonly number[], order: Int32Array): number[] {
+  const positions = new Array<number>(order.length);
+  for (let slot = 0; slot < order.length; slot++) {
+    positions[slot] = values[order[slot] ?? slot] ?? Number.NaN;
+  }
+  return positions;
+}
+
+/**
+ * Whether the panels are drawing the data's own units rather than weights.
+ *
+ * Bars are read from the zero line, and in those two views zero is not where
+ * the reader's eye starts: an absorbance sits on a baseline, so bars grown
+ * from nothing would be one tall column per measurement with the pattern
+ * hidden in their tips. Those views draw lines whatever the axis is.
+ * @param built - The panels as they were built.
+ * @returns Whether zero is a meaningless place to grow a bar from.
+ */
+function inTheirOwnUnits(built: LoadingProfiles): boolean {
+  return built.view === 'effect' || built.view === 'sample';
+}
+
+/** What the rebuilt sample is called when the viewer has not named it. */
+const A_SAMPLE = 'the selected sample';

package/src/projection/ui/ProjectionViewer.tsx

@@ -0,0 +1,146 @@
+import type { CSSProperties, ReactElement } from 'react';
+import { useId, useMemo, useRef } from 'react';
+
+import { useContainerSize } from '../../hooks/ui/useContainerSize.ts';
+import { mergeProjectionCopy } from '../core/projectionCopy.ts';
+
+import { ProjectionBar } from './ProjectionBar.tsx';
+import { ProjectionPanel } from './ProjectionPanel.tsx';
+import { formatProjectionValue } from './projectionFormat.ts';
+import { useProjectionMapView } from './projectionMapView.ts';
+import { useProjectionModels } from './projectionTabModels.ts';
+import { PROJECTION_TAB_HEIGHT } from './projectionTabStyles.ts';
+import type { ProjectionViewerProps } from './projectionViewerProps.ts';
+import { useProjectionState } from './useProjectionState.ts';
+
+export type { ProjectionVariableTrack } from './ProjectionVariablesTab.tsx';
+export type { ProjectionSelection } from './projectionSelection.ts';
+export type { ProjectionSampleOpen } from './projectionViewerProps.ts';
+export type { ProjectionViewerProps } from './projectionViewerProps.ts';
+
+/**
+ * A dimension-reduction result, shown as a map a reader can interrogate.
+ *
+ * It knows nothing about principal components: a method fills in what it has
+ * and leaves the rest out, and the viewer offers exactly the tabs the result
+ * can support — which is why a two-dimensional UMAP renders as one clean chart
+ * with no strip of views rather than four tabs, three of them empty.
+ *
+ * It is built to be a guest on somebody else's page, so it is one bar and one
+ * figure and nothing else: the views, the settings of the view showing and the
+ * question mark that explains it share a single thirty-pixel row above the
+ * picture, and every pixel below that row is the picture. Nothing stands under
+ * it — the key floats in the emptiest corner of the plot, and the paragraph
+ * that used to sit beneath the figure is behind the question mark, kept whole
+ * for the reader who wants it and costing nothing to the reader who does not.
+ *
+ * The four tabs are one tool rather than four because they share one piece of
+ * state: a pair promoted from the grid arrives on the map, and the lasso drawn
+ * there is still selected when the reader comes back to it. What the reader
+ * picked leaves by name — `onSelectionChange` reports the ids from
+ * `samples.ids` — so a page filtering its own table beside the figure never
+ * has to keep a second copy of the row order to read them with.
+ * @param props - See {@link ProjectionViewerProps}.
+ * @returns The viewer.
+ */
+export function ProjectionViewer(props: ProjectionViewerProps): ReactElement {
+  const { result, samples, className, testId, onTrackVariable } = props;
+  const { onHoverSample, touchLasso, height = PROJECTION_TAB_HEIGHT } = props;
+  const { onSampleDoubleClick } = props;
+  const { wheelZoom = true } = props;
+  const { formatValue = formatProjectionValue, fileName = 'projection' } =
+    props;
+
+  const copy = useMemo(() => mergeProjectionCopy(props.copy), [props.copy]);
+  const state = useProjectionState(props);
+  const figure = useRef<HTMLDivElement>(null);
+  const measured = useContainerSize(figure);
+  const width = measured.width > 0 ? measured.width : ASSUMED_WIDTH;
+
+  const models = useProjectionModels({
+    result,
+    samples,
+    options: state.options,
+    selected: state.selected,
+  });
+  const map = useProjectionMapView({
+    result,
+    copy,
+    groups: state.groups,
+    options: state.options,
+    selected: state.selected,
+    onSettle: state.settleSelection,
+  });
+
+  const baseId = useId();
+  const panelId = `${baseId}-panel`;
+  const strip = state.tabs.length > 1;
+
+  return (
+    <div
+      ref={figure}
+      className={
+        className === undefined
+          ? 'projection-viewer'
+          : `projection-viewer ${className}`
+      }
+      data-testid={testId}
+      style={VIEWER_STYLE}
+    >
+      <ProjectionBar
+        state={state}
+        result={result}
+        copy={copy}
+        models={models}
+        map={map}
+        baseId={baseId}
+        panelId={panelId}
+        fileName={fileName}
+        width={width}
+      />
+      <ProjectionPanel
+        state={state}
+        result={result}
+        samples={samples}
+        copy={copy}
+        models={models}
+        map={map}
+        width={width}
+        height={height}
+        formatValue={formatValue}
+        baseId={baseId}
+        panelId={panelId}
+        strip={strip}
+        onHoverSample={onHoverSample}
+        onSampleDoubleClick={onSampleDoubleClick}
+        onTrackVariable={onTrackVariable}
+        touchLasso={touchLasso}
+        wheelZoom={wheelZoom}
+      />
+    </div>
+  );
+}
+
+/**
+ * The width a figure is drawn at before its container has been measured.
+ *
+ * A guess corrected on the first measurement beats an empty box: the viewer
+ * then renders on a server, renders in a test with no DOM at all, and never
+ * leaves a hole in the page for the frame or two a resize observer takes to
+ * report. The number is a common single-column figure, so the correction is
+ * usually small enough that nothing visibly jumps.
+ */
+const ASSUMED_WIDTH = 640;
+
+/**
+ * The bar and the figure, with nothing between them.
+ *
+ * The gap is zero on purpose: the bar carries a hairline along its foot, and
+ * that line is what separates the chrome from the picture. A gap as well would
+ * read as a seam between two components rather than as one figure.
+ */
+const VIEWER_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  width: '100%',
+} as const satisfies CSSProperties;

package/src/projection/ui/index.ts

@@ -0,0 +1,20 @@
+/**
+ * The viewer a dimension-reduction run is read in.
+ *
+ * Only the two components a site mounts are exported. The four tabs, their
+ * option bars and the arithmetic behind them stay inside the package: a tab is
+ * offered because the result can fill it, never because a caller asked for it,
+ * and exporting them separately would invite a site to show an empty one.
+ *
+ * `ProjectionViewer` takes any result — a principal component analysis, a
+ * k-means run, a UMAP embedding — while `PcaViewer` is the shortcut for the
+ * commonest of them, taking a fitted model and the rows it was fitted on.
+ */
+
+export type { PcaViewerProps } from './PcaViewer.tsx';
+export { PcaViewer } from './PcaViewer.tsx';
+export type { ProjectionSampleOpen } from './projectionViewerProps.ts';
+export type { ProjectionSelection } from './projectionSelection.ts';
+export type { ProjectionVariableTrack } from './projectionVariablesModel.ts';
+export type { ProjectionViewerProps } from './projectionViewerProps.ts';
+export { ProjectionViewer } from './ProjectionViewer.tsx';