react-cheminfo 0.69.0 → 0.71.0

package/src/mass/ui/PeakLabels.tsx

@@ -0,0 +1,242 @@
+import type { CSSProperties, ReactElement } from 'react';
+import { useMemo } from 'react';
+
+import type { PlotRect } from '../../chart/core/chartGeometry.ts';
+import type { ChartScale } from '../../chart/core/chartScale.ts';
+import {
+  CHART_COLORS,
+  CHART_FONT,
+  LABEL_HALO,
+  LABEL_QUIET,
+  PEAK_LABEL,
+} from '../../chart/core/chartTheme.ts';
+import type { HoveredPeak } from '../core/labelStackBox.ts';
+import type { MassSpectrum } from '../core/massSpectrum.ts';
+import type { PeakLabelLineKind } from '../core/peakLabelLines.ts';
+import { planPeakLabels } from '../core/peakLabelPlan.ts';
+
+export interface PeakLabelsProps {
+  /**
+   * The spectrum whose peaks are labelled. Hand it the same one that was drawn:
+   * a mirrored half is drawn normalised, and labels computed from the spectrum
+   * as measured would float above sticks of another height.
+   */
+  spectrum: MassSpectrum;
+  /** Where the plot sits, which is what a stack may not be pushed out of. */
+  plot: PlotRect;
+  /** The m/z axis as it is currently zoomed. */
+  xScale: ChartScale;
+  /**
+   * The intensity axis as it is currently zoomed. Reflect it and the labels
+   * follow the sticks downwards — together with `below`, which turns the stacks
+   * over.
+   */
+  yScale: ChartScale;
+  /**
+   * How many peaks are labelled at most, the most intense first.
+   * @default DEFAULT_LABEL_LIMIT
+   */
+  limit?: number;
+  /**
+   * Whether a peak whose charge was established says so.
+   * @default false
+   */
+  showCharges?: boolean;
+  /**
+   * How many decimals the masses on screen are written with.
+   * @default 4
+   */
+  mzDecimals?: number;
+  /**
+   * What explains each peak, keyed as `peakKey` keys it — the name a host
+   * writes on top of a stack.
+   * @default undefined
+   */
+  annotationLabels?: ReadonlyMap<string, string>;
+  /**
+   * Whether the stacks hang under the sticks rather than standing over them,
+   * which is what the lower half of a mirrored pair wants.
+   * @default false
+   */
+  below?: boolean;
+  /**
+   * The ink the stacks are written in — worth passing the spectrum's own colour
+   * on a chart holding several, where an unattributed m/z belongs to any of them.
+   * @default the theme's label colour
+   */
+  color?: string;
+  /**
+   * What one unit of the measured intensity is written as.
+   * @default 1
+   */
+  intensityScale?: number;
+  /**
+   * Called with the peak whose stack the pointer is resting on, `null` when it
+   * leaves. Without it the stacks answer no pointer at all.
+   * @default undefined
+   */
+  onHover?: (peak: HoveredPeak | null) => void;
+}
+
+/**
+ * The tops of the best peaks of one spectrum, and what each of them reads.
+ *
+ * Two things drawn together because they are one claim: a short mark on the tip
+ * of the picked peak, and the numbers written over it. The mark is the half that
+ * matters when the continuous trace is the one on screen — the centroid is then
+ * not drawn at all, and a stack of numbers floating over a peak shape says which
+ * region was picked but never which point of it, which is the number the stack
+ * is quoting. With the mark on the tip the two agree by construction.
+ *
+ * Which peaks are labelled is `planPeakLabels`'s to decide, and it follows the
+ * zoom: a survey of the whole spectrum labels its base peak and a few others,
+ * and the same spectrum zoomed onto one cluster labels every line in it. Every
+ * line is haloed and none of them is boxed: a number over a peak is written
+ * over whatever the plot has there, and the halo clears a hairline of chart from
+ * around each glyph, where a filled box would hide the very data it is about.
+ *
+ * The numbers take no pointer event; the room they occupy does, as one
+ * transparent rectangle per stack, and only when somebody asked for it — so a
+ * stack can be interrogated without becoming a control, while the crosshair
+ * underneath goes on following the pointer.
+ * @param props - Component props.
+ * @returns The marks and the labels, as SVG.
+ */
+export function PeakLabels(props: PeakLabelsProps): ReactElement {
+  const {
+    spectrum,
+    plot,
+    xScale,
+    yScale,
+    limit,
+    showCharges = false,
+    mzDecimals,
+    annotationLabels,
+    below = false,
+    color = CHART_COLORS.labelText,
+    intensityScale = 1,
+    onHover,
+  } = props;
+
+  const plans = useMemo(
+    () =>
+      planPeakLabels({
+        spectrum,
+        plot,
+        xScale,
+        yScale,
+        showCharges,
+        below,
+        intensityScale,
+        ...(limit === undefined ? {} : { limit }),
+        ...(mzDecimals === undefined ? {} : { mzDecimals }),
+        ...(annotationLabels === undefined ? {} : { annotationLabels }),
+      }),
+    [
+      spectrum,
+      plot,
+      xScale,
+      yScale,
+      limit,
+      showCharges,
+      mzDecimals,
+      annotationLabels,
+      below,
+      intensityScale,
+    ],
+  );
+
+  // Every picked peak is marked; only the ones that kept their room are
+  // written, since a stack over a peak whose neighbour took the room would be
+  // written across that neighbour's.
+  const written = useMemo(
+    () => plans.filter((plan) => Number.isFinite(plan.labelX)),
+    [plans],
+  );
+
+  const stackStyle = useMemo(
+    () => ({ fill: color, fontSize: CHART_FONT.label, ...LABEL_HALO }),
+    [color],
+  );
+  const markStyle = useMemo(() => ({ stroke: color }), [color]);
+
+  return (
+    <g>
+      {/* Its own group, because the stroke that draws a mark would outline every
+          glyph of a label sharing the group with it. */}
+      <g pointerEvents="none" style={markStyle}>
+        {plans.map((plan) => (
+          <line
+            key={plan.key}
+            x1={plan.tipX}
+            y1={plan.tipY}
+            x2={plan.tipX}
+            y2={
+              below
+                ? plan.tipY - PEAK_LABEL.topMark
+                : plan.tipY + PEAK_LABEL.topMark
+            }
+          />
+        ))}
+      </g>
+      <g pointerEvents="none" style={stackStyle}>
+        {written.map((plan) => (
+          <text key={plan.key} textAnchor="middle">
+            {plan.lines.map((line, index) => (
+              <tspan
+                key={line.kind}
+                x={plan.labelX}
+                y={plan.baselines[index]}
+                style={LINE_STYLES[line.kind]}
+              >
+                {line.text}
+              </tspan>
+            ))}
+          </text>
+        ))}
+      </g>
+      {onHover === undefined
+        ? null
+        : written.map((plan) => (
+            <rect
+              key={plan.key}
+              x={plan.box.x}
+              y={plan.box.y}
+              width={plan.box.width}
+              height={plan.box.height}
+              fill="transparent"
+              onPointerEnter={() =>
+                onHover({
+                  key: plan.key,
+                  mz: plan.peak.x,
+                  intensity: plan.peak.y,
+                  charge: plan.peak.charge,
+                  x: plan.labelX,
+                  // A card hangs off the edge of the stack facing away from the
+                  // stick, so it never covers the peak it is about.
+                  y: below ? plan.box.y + plan.box.height : plan.box.y,
+                })
+              }
+              onPointerLeave={() => onHover(null)}
+            />
+          ))}
+    </g>
+  );
+}
+
+/**
+ * How each line of a stack is set.
+ *
+ * Four numbers in one ink and one weight are four things said at once, and the
+ * eye has to read all of them to find the one it came for. So the stack is
+ * graded instead: the name of what the peak is carries the weight, because it is
+ * the only line that is an answer rather than a measurement; the m/z is written
+ * plain, which is what a chemist is nearly always reading; and the charge and
+ * the intensity are let back towards the paper.
+ */
+const LINE_STYLES: Record<PeakLabelLineKind, CSSProperties> = {
+  annotation: { fontWeight: 600 },
+  charge: { fillOpacity: LABEL_QUIET },
+  mz: {},
+  intensity: { fillOpacity: LABEL_QUIET },
+};

package/src/mass/ui/PeakTable.tsx

@@ -0,0 +1,199 @@
+import { memo, useMemo, useRef } from 'react';
+
+import {
+  panelCellStyle,
+  panelColumnButtonStyle,
+  panelNumberCellStyle,
+  panelScrollAreaStyle,
+  panelStickyHeaderStyle,
+  panelTableStyle,
+} from '../../panel/core/panelStyles.ts';
+import { useVirtualRows } from '../../panel/ui/useVirtualRows.ts';
+import type { MassPeakObject } from '../core/centroidPeaks.ts';
+import { formatIntensity, formatMz } from '../core/massFormat.ts';
+
+/** Which column the rows are read in the order of. */
+export type PeakSortKey = 'mz' | 'intensity';
+
+export interface PeakTableProps {
+  /** The peaks to list, in increasing m/z. */
+  peaks: readonly MassPeakObject[];
+  /** How many decimals the masses are written with. */
+  mzDecimals: number;
+  /**
+   * Which column the rows are in the order of: m/z ascending, which is how a
+   * spectrum is read, or intensity descending, which is how its base peak and
+   * its neighbours are found.
+   */
+  sortKey: PeakSortKey;
+  /** Order the rows by a column. */
+  onSort: (key: PeakSortKey) => void;
+  /** The m/z of the peak the pointer is resting on, `null` for none. */
+  highlightMz: number | null;
+  /** Told which peak a row the pointer rests on is, `null` when it leaves. */
+  onHighlight: (mz: number | null) => void;
+  /** Frame a peak on the chart. */
+  onPick: (mz: number) => void;
+}
+
+/**
+ * The peaks, one row each, under a header that sorts them.
+ *
+ * Only the rows in view are drawn: a table opened onto a whole Orbitrap scan is
+ * a thousand rows, and every one of them would otherwise be laid out again on
+ * every hover of the chart beside it.
+ * @param props - Component props.
+ * @returns The table.
+ */
+export function PeakTable(props: PeakTableProps) {
+  const {
+    peaks,
+    mzDecimals,
+    sortKey,
+    onSort,
+    highlightMz,
+    onHighlight,
+    onPick,
+  } = props;
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  const ordered = useMemo(
+    () =>
+      sortKey === 'mz'
+        ? peaks
+        : peaks.toSorted((first, second) => second.y - first.y),
+    [peaks, sortKey],
+  );
+  const rows = useVirtualRows(scrollRef, ordered.length, ROW_HEIGHT);
+  const showsCharge = useMemo(
+    () => peaks.some((peak) => peak.charge !== 0),
+    [peaks],
+  );
+
+  return (
+    <div ref={scrollRef} style={panelScrollAreaStyle}>
+      <table style={panelTableStyle}>
+        <thead>
+          <tr>
+            <th style={panelStickyHeaderStyle}>
+              <button
+                type="button"
+                style={panelColumnButtonStyle}
+                onClick={() => onSort('mz')}
+              >
+                m/z{sortKey === 'mz' ? ' ▲' : ''}
+              </button>
+            </th>
+            <th style={panelStickyHeaderStyle}>
+              <button
+                type="button"
+                style={panelColumnButtonStyle}
+                onClick={() => onSort('intensity')}
+              >
+                intensity{sortKey === 'intensity' ? ' ▼' : ''}
+              </button>
+            </th>
+            {showsCharge ? (
+              <th style={panelStickyHeaderStyle}>
+                <span style={panelColumnButtonStyle}>z</span>
+              </th>
+            ) : null}
+          </tr>
+        </thead>
+        <tbody onPointerLeave={() => onHighlight(null)}>
+          {rows.before > 0 ? <tr style={{ height: rows.before }} /> : null}
+          {rows.indices.map((index) => {
+            const peak = ordered[index] as MassPeakObject;
+            return (
+              <PeakRow
+                key={peak.x}
+                index={index}
+                peak={peak}
+                mzDecimals={mzDecimals}
+                showsCharge={showsCharge}
+                isHighlighted={peak.x === highlightMz}
+                measure={rows.measure}
+                onHighlight={onHighlight}
+                onPick={onPick}
+              />
+            );
+          })}
+          {rows.after > 0 ? <tr style={{ height: rows.after }} /> : null}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+interface PeakRowProps {
+  /** Where the row sits in the list, which is how its height is found again. */
+  index: number;
+  /** The peak. */
+  peak: MassPeakObject;
+  /** How many decimals the mass is written with. */
+  mzDecimals: number;
+  /** Whether the charge column is drawn. */
+  showsCharge: boolean;
+  /** Whether the pointer is resting on this peak, here or on the chart. */
+  isHighlighted: boolean;
+  /** Reports the row's height. */
+  measure: (node: HTMLElement | null) => void;
+  /** Told the peak's m/z when the pointer comes to rest on the row. */
+  onHighlight: (mz: number | null) => void;
+  /** Frames the peak on the chart. */
+  onPick: (mz: number) => void;
+}
+
+/**
+ * One peak. Memoised, because a hover on the chart moves the highlight and only
+ * the row it left and the row it reached have anything new to draw.
+ */
+const PeakRow = memo(function PeakRow(props: PeakRowProps) {
+  const {
+    index,
+    peak,
+    mzDecimals,
+    showsCharge,
+    isHighlighted,
+    measure,
+    onHighlight,
+    onPick,
+  } = props;
+  return (
+    <tr
+      ref={measure}
+      data-index={index}
+      style={isHighlighted ? highlightedRowStyle : rowStyle}
+      title="Click to frame this peak on the chart"
+      // Reachable by Tab as well as by the pointer: framing a peak is the one
+      // thing a row does, and a keyboard has to be able to ask for it.
+      tabIndex={0}
+      onPointerEnter={() => onHighlight(peak.x)}
+      onFocus={() => onHighlight(peak.x)}
+      onClick={() => onPick(peak.x)}
+      onKeyDown={(event) => {
+        if (event.key !== 'Enter' && event.key !== ' ') return;
+        event.preventDefault();
+        onPick(peak.x);
+      }}
+    >
+      <td style={panelCellStyle}>{formatMz(peak.x, mzDecimals)}</td>
+      <td style={panelNumberCellStyle}>
+        {formatIntensity(peak.y, mzDecimals)}
+      </td>
+      {showsCharge ? (
+        <td style={panelNumberCellStyle}>
+          {peak.charge === 0 ? '' : peak.charge}
+        </td>
+      ) : null}
+    </tr>
+  );
+});
+
+/** What one row is worth before one has been measured. */
+const ROW_HEIGHT = 18;
+
+const rowStyle = { cursor: 'pointer' } as const;
+
+/** The row of the peak being looked at, wherever it was pointed at. */
+const highlightedRowStyle = { ...rowStyle, background: '#e8f1fb' } as const;

package/src/mass/ui/PeaksPanel.tsx

@@ -0,0 +1,182 @@
+import { useCallback, useMemo, useState } from 'react';
+import { SelectedTotal, Toolbar } from 'react-science/ui';
+
+import { useCopyToClipboard } from '../../clipboard/ui/useCopyToClipboard.ts';
+import {
+  panelBodyStyle,
+  panelEmptyStyle,
+  panelStyle,
+  panelToolbarCountStyle,
+  panelToolbarStyle,
+} from '../../panel/core/panelStyles.ts';
+import { mzFrame } from '../core/massDomain.ts';
+import {
+  PEAK_TABLE_LIMIT,
+  PEAK_TABLE_THRESHOLD,
+  peakTableRows,
+  peakTableToTsv,
+} from '../core/peakTable.ts';
+
+import { MzDecimalsMenu } from './MzDecimalsMenu.tsx';
+import type { PeakSortKey } from './PeakTable.tsx';
+import { PeakTable } from './PeakTable.tsx';
+import { useMassCommandProps } from './massCommandContext.tsx';
+import { useMassActions, useMassEditorState } from './massStateContext.ts';
+
+export interface PeaksPanelProps {
+  /**
+   * The m/z of the peak the pointer is resting on, wherever it was hovered.
+   * @default null
+   */
+  highlightMz?: number | null;
+  /**
+   * Told which peak a row the pointer rests on is, `null` when it leaves.
+   * @default undefined
+   */
+  onHighlight?: (mz: number | null) => void;
+}
+
+/**
+ * What is actually in the selected spectrum, peak by peak.
+ *
+ * The centroid rather than the profile, because the centroid is what every
+ * number downstream is computed from — a profile lists the dozens of points one
+ * ion's peak shape covers, and none of them is the ion. For a profile these are
+ * the peaks the picking found in it.
+ *
+ * The window is the chart's by default: zoom into a cluster and the question
+ * becomes what is in *that* cluster, and a table that went on listing every row
+ * would have to be searched for the answer the chart is already pointing at. A
+ * floor of a hundredth of the base peak leaves the baseline out, and both are a
+ * toggle away. Resting on a row lights the peak on the chart, and clicking one
+ * frames it there.
+ * @param props - Component props.
+ * @returns The panel.
+ */
+export function PeaksPanel(props: PeaksPanelProps) {
+  const { highlightMz = null, onHighlight } = props;
+  const {
+    state,
+    visibleSpectra,
+    selectedSpectrum,
+    mzDecimals,
+    autoMzDecimals,
+  } = useMassEditorState();
+  const actions = useMassActions();
+  const command = useMassCommandProps();
+  const { domain } = state.view;
+  const { showLabels, showCharges } = state.settings;
+
+  const [inWindow, setInWindow] = useState(true);
+  const [withFloor, setWithFloor] = useState(true);
+  const [sortKey, setSortKey] = useState<PeakSortKey>('mz');
+  const { copied, copy } = useCopyToClipboard();
+
+  const peaks = useMemo(
+    () =>
+      selectedSpectrum === null
+        ? []
+        : peakTableRows(selectedSpectrum, {
+            domain: inWindow ? domain : null,
+            threshold: withFloor ? PEAK_TABLE_THRESHOLD : 0,
+          }),
+    [selectedSpectrum, inWindow, domain, withFloor],
+  );
+
+  // Stable across a pointer move, so the memoised rows survive one.
+  const onPick = useCallback(
+    (mz: number) => actions.setDomain(mzFrame(mz, visibleSpectra, domain)),
+    [actions, visibleSpectra, domain],
+  );
+  const highlight = useCallback(
+    (mz: number | null) => onHighlight?.(mz),
+    [onHighlight],
+  );
+
+  const total = selectedSpectrum?.centroid.x.length ?? 0;
+
+  return (
+    <div style={panelStyle}>
+      <div style={panelToolbarStyle}>
+        <Toolbar aria-label="Peaks">
+          <Toolbar.Item
+            icon="zoom-to-fit"
+            active={inWindow}
+            tooltip="Only the peaks the chart is showing"
+            aria-label="Only the peaks the chart is showing"
+            onClick={() => setInWindow(!inWindow)}
+          />
+          <Toolbar.Item
+            icon="filter"
+            active={withFloor}
+            tooltip="Leave out the peaks under 1 % of the base peak"
+            aria-label="Leave out the peaks under 1 % of the base peak"
+            onClick={() => setWithFloor(!withFloor)}
+          />
+          <Toolbar.Item
+            icon="label"
+            active={showLabels}
+            {...command('toggleLabels')}
+          />
+          <Toolbar.Item
+            icon="numerical"
+            active={showCharges}
+            {...command('toggleCharges')}
+          />
+          <MzDecimalsMenu
+            setting={state.settings.mzDecimals}
+            autoDecimals={autoMzDecimals}
+            onChange={(setting) => actions.setSettings({ mzDecimals: setting })}
+          />
+          <Toolbar.Item
+            icon={copied ? 'tick' : 'duplicate'}
+            tooltip="Copy the rows as tab-separated text"
+            aria-label="Copy the rows as tab-separated text"
+            disabled={peaks.length === 0}
+            onClick={() => void copy(peakTableToTsv(peaks, mzDecimals))}
+          />
+        </Toolbar>
+        <div
+          style={panelToolbarCountStyle}
+          title={`${peaks.length} of the ${total} peaks of this spectrum listed`}
+        >
+          <SelectedTotal count={peaks.length} total={total} />
+        </div>
+      </div>
+
+      <div style={panelBodyStyle}>
+        {selectedSpectrum === null ? (
+          <p style={panelEmptyStyle}>
+            No spectrum is selected. Click one in the Spectra panel and its
+            peaks are listed here.
+          </p>
+        ) : peaks.length === 0 ? (
+          <p style={panelEmptyStyle}>
+            No peak stands in the window above the floor. Zoom out, or switch
+            the window or the floor off in the toolbar.
+          </p>
+        ) : (
+          <>
+            {peaks.length === PEAK_TABLE_LIMIT ? (
+              <p style={noteStyle}>
+                The {PEAK_TABLE_LIMIT} most intense peaks are listed. Zoom in to
+                list the rest.
+              </p>
+            ) : null}
+            <PeakTable
+              peaks={peaks}
+              mzDecimals={mzDecimals}
+              sortKey={sortKey}
+              onSort={setSortKey}
+              highlightMz={highlightMz}
+              onHighlight={highlight}
+              onPick={onPick}
+            />
+          </>
+        )}
+      </div>
+    </div>
+  );
+}
+
+const noteStyle = { margin: 0, fontSize: 11, opacity: 0.7 } as const;