react-cheminfo 0.69.0 → 0.71.0

package/src/mass/core/massSummary.ts

@@ -0,0 +1,213 @@
+/**
+ * What a spectrum can be said to be, when the file said little or nothing.
+ *
+ * A two-column paste is most pastes, and it carries no acquisition metadata at
+ * all: no instrument, no polarity, no collision energy. A panel that answered
+ * that with an empty table would be saying "this file is a mystery" when the
+ * truth is far more useful — it is this file, read as that format, holding so
+ * many peaks between these two masses. So the facts the viewer knows about
+ * every spectrum, whatever it came from, are gathered here as rows of the same
+ * two-column table the metadata itself fills, and a panel renders one table
+ * either way.
+ *
+ * Everything here is a pure function of one spectrum, so what the panels say
+ * can be tested without mounting them.
+ */
+
+import {
+  formatMz,
+  formatMzRange,
+  massFormatLabel,
+  resolutionBasisLabel,
+  resolutionLabel,
+  resolvingPowerLabel,
+} from './massFormat.ts';
+import { MZ_DECIMALS } from './massResolution.ts';
+import type { MassMetaField, MassSpectrum } from './massSpectrum.ts';
+import { resolutionOf } from './resolutionOf.ts';
+
+/**
+ * The rows the acquisition table shows for a spectrum.
+ *
+ * The file's own records win whenever it wrote any, in the order
+ * `buildMassMeta` fixed — that order is how a method is read, from what the
+ * sample was measured on down to who measured it, and re-sorting it here would
+ * scatter a method across the table. A file that wrote none falls back to what
+ * the viewer knows regardless.
+ * @param spectrum - The spectrum the panel is about.
+ * @param mzDecimals - How many decimals its masses are written with. Defaults
+ * to four.
+ * @returns The rows, in display order, never empty.
+ */
+export function spectrumMetaRows(
+  spectrum: MassSpectrum,
+  mzDecimals = MZ_DECIMALS.high,
+): MassMetaField[] {
+  const fields = spectrum.meta?.fields ?? [];
+  return fields.length > 0 ? fields : spectrumFileFields(spectrum, mzDecimals);
+}
+
+/**
+ * What the viewer knows about a spectrum without the file's help.
+ *
+ * Every row is read off the spectrum as it was loaded — where it came from,
+ * which acquisition of it, and how many points survived the peak picking — so
+ * this answers for a pasted peak list exactly as well as for a scan of a run.
+ * @param spectrum - The spectrum the panel is about.
+ * @param mzDecimals - How many decimals its masses are written with. Defaults
+ * to four.
+ * @returns The rows, in display order.
+ */
+export function spectrumFileFields(
+  spectrum: MassSpectrum,
+  mzDecimals = MZ_DECIMALS.high,
+): MassMetaField[] {
+  const { origin, centroid, profile } = spectrum;
+  const rows: MassMetaField[] = [{ label: 'Name', value: spectrum.name }];
+
+  if (origin.fileName === undefined) {
+    rows.push({
+      label: 'Source',
+      value:
+        origin.format === 'calculated'
+          ? 'Calculated in the viewer'
+          : 'Pasted, not read from a file',
+    });
+  } else {
+    rows.push({ label: 'File', value: origin.fileName });
+  }
+  rows.push({ label: 'Format', value: massFormatLabel(origin.format) });
+
+  if (origin.scanIndex !== undefined) {
+    rows.push({ label: 'Scan', value: scanNumber(origin.scanIndex) });
+  }
+  if (origin.msLevel !== undefined) {
+    rows.push({ label: 'MS level', value: String(origin.msLevel) });
+  }
+  if (origin.polarity !== undefined) {
+    rows.push({ label: 'Polarity', value: origin.polarity });
+  }
+  if (origin.precursorMz !== undefined) {
+    rows.push({ label: 'Precursor m/z', value: formatMz(origin.precursorMz) });
+  }
+  // Only where it differs from the row above. Listed always, it would repeat
+  // the precursor on nearly every Thermo scan and say nothing; listed here, it
+  // is the one place a reader learns that the instrument was after a molecule
+  // the window it cut does not contain.
+  if (
+    origin.precursorMonoisotopicMz !== undefined &&
+    origin.precursorMonoisotopicMz !== origin.precursorMz
+  ) {
+    rows.push({
+      label: 'Monoisotopic m/z',
+      value: formatMz(origin.precursorMonoisotopicMz),
+    });
+  }
+  if (origin.retentionTime !== undefined) {
+    rows.push({
+      label: 'Retention time',
+      value: `${origin.retentionTime.toFixed(2)} min`,
+    });
+  }
+
+  rows.push({ label: 'Peaks', value: String(centroid.x.length) });
+  if (profile !== null) {
+    rows.push({ label: 'Profile points', value: String(profile.x.length) });
+  }
+  const range = formatMzRange(centroid.x, mzDecimals);
+  if (range !== '') rows.push({ label: 'm/z range', value: range });
+  return rows;
+}
+
+/**
+ * The rows that say how finely a spectrum resolves masses, and how that was
+ * decided — the verdict read off the decimals of a peak table is a weaker claim
+ * than one measured on the widths of its peaks, and the table says which.
+ * @param spectrum - The spectrum the panel is about.
+ * @returns One row, or two when a resolving power was measured.
+ */
+export function spectrumResolutionRows(
+  spectrum: MassSpectrum,
+): MassMetaField[] {
+  const resolution = resolutionOf(spectrum);
+  const rows: MassMetaField[] = [
+    {
+      label: 'Resolution',
+      value: `${resolutionLabel(resolution)}, ${resolutionBasisLabel(resolution)}`,
+    },
+  ];
+  if (resolution.resolvingPower !== null) {
+    rows.push({
+      label: 'Resolving power',
+      value: `${resolvingPowerLabel(resolution.resolvingPower)} at half height`,
+    });
+  }
+  return rows;
+}
+
+/** What the line under a spectrum's name says besides its acquisition. */
+export interface SpectrumSubtitleOptions {
+  /**
+   * Whether the line also says what kind of spectrum it is — profile or
+   * centroid first, and its resolution last. Worth it on a list of files that
+   * differ in exactly that; noise on a list of scans out of one run, every one
+   * of which is the same kind as the next.
+   * @default false
+   */
+  describeKind?: boolean;
+}
+
+/**
+ * The one line under a spectrum's name in the list.
+ *
+ * A file of a thousand scans gives a thousand rows whose names all start with
+ * the same file name, so the row has to carry whatever tells one acquisition
+ * from the next — which scan, which MS level, what was fragmented and when it
+ * eluted. Those are exactly the facts the row is picked by.
+ * @param spectrum - The spectrum the row is of.
+ * @param options - See {@link SpectrumSubtitleOptions}.
+ * @returns The line, the peak count alone for a spectrum with no origin facts.
+ * @example
+ * spectrumSubtitle(scan); // 'Scan 12 · MS2 · precursor 452.1900 · 3.42 min · 128 peaks'
+ * spectrumSubtitle(file, { describeKind: true }); // 'profile · 10 peaks · high resolution'
+ */
+export function spectrumSubtitle(
+  spectrum: MassSpectrum,
+  options: SpectrumSubtitleOptions = {},
+): string {
+  const { describeKind = false } = options;
+  const { origin, centroid, profile } = spectrum;
+  const parts: string[] = [];
+
+  if (describeKind) parts.push(profile === null ? 'centroid' : 'profile');
+
+  if (origin.scanIndex !== undefined) {
+    parts.push(`Scan ${scanNumber(origin.scanIndex)}`);
+  }
+  if (origin.msLevel !== undefined) parts.push(`MS${origin.msLevel}`);
+  if (origin.polarity !== undefined) parts.push(origin.polarity);
+  if (origin.precursorMz !== undefined) {
+    parts.push(`precursor ${formatMz(origin.precursorMz)}`);
+  }
+  if (origin.retentionTime !== undefined) {
+    parts.push(`${origin.retentionTime.toFixed(2)} min`);
+  }
+
+  const peaks = centroid.x.length;
+  parts.push(`${peaks} peak${peaks === 1 ? '' : 's'}`);
+  if (describeKind) parts.push(resolutionLabel(resolutionOf(spectrum)));
+  return parts.join(' · ');
+}
+
+/**
+ * Which acquisition of its file a scan is, counted from one as every list of
+ * scans counts them — `MassOrigin.scanIndex` counts from zero, and a scan
+ * listed as 23 in one table and 24 in the next reads as two scans.
+ * @param scanIndex - Which acquisition of the file, counted from zero.
+ * @returns Its number, counted from one.
+ * @example
+ * scanNumber(23); // '24'
+ */
+function scanNumber(scanIndex: number): string {
+  return String(scanIndex + 1);
+}

package/src/mass/core/mzDecimalsSetting.ts

@@ -0,0 +1,52 @@
+/**
+ * How many decimals the masses on screen are written with: as the spectra
+ * decide, or as the reader chose.
+ *
+ * The spectra decide well for what they are — an Orbitrap scan to four
+ * decimals, a library spectrum in whole masses — but not for what the reader
+ * is doing with them: an ion-trap run read against its precursors wants a
+ * decimal its verdict calls noise, and a table pasted into a report wants
+ * fewer digits than the instrument gave. So the decision is a setting, `'auto'`
+ * until somebody picks a number.
+ */
+
+import type { MassSpectrum } from './massSpectrum.ts';
+import { mzDecimalsOf } from './resolutionOf.ts';
+
+/** `'auto'` to let the spectra decide, or the number of decimals chosen. */
+export type MzDecimalsSetting = 'auto' | number;
+
+/** The most decimals that can be chosen; past it a mass is all noise. */
+export const MAXIMUM_MZ_DECIMALS = 5;
+
+/**
+ * How many decimals the masses of spectra shown together are written with.
+ * @param setting - What the reader chose, `'auto'` for nothing.
+ * @param spectra - The spectra being shown together.
+ * @returns The decimals: the choice, or what `mzDecimalsOf` decides.
+ */
+export function mzDecimalsFor(
+  setting: MzDecimalsSetting,
+  spectra: readonly MassSpectrum[],
+): number {
+  return setting === 'auto' ? mzDecimalsOf(spectra) : setting;
+}
+
+/**
+ * A decimals setting as it may be stored, read back from whatever was.
+ *
+ * A setting arrives from a saved workspace, a host's props or a URL, none of
+ * which this viewer wrote, so anything other than `'auto'` or a finite number
+ * is not a setting at all — and a number is rounded and held to what can be
+ * chosen rather than refused, since `4.0` and `9` both say plainly enough what
+ * was meant.
+ * @param value - What was stored.
+ * @returns The setting, or `undefined` for something that is not one.
+ */
+export function readMzDecimalsSetting(
+  value: unknown,
+): MzDecimalsSetting | undefined {
+  if (value === 'auto') return 'auto';
+  if (typeof value !== 'number' || !Number.isFinite(value)) return undefined;
+  return Math.min(MAXIMUM_MZ_DECIMALS, Math.max(0, Math.round(value)));
+}

package/src/mass/core/nearestPeak.ts

@@ -0,0 +1,130 @@
+/**
+ * Which peak the pointer is asking about.
+ *
+ * One question, asked by the crosshair, by the click that frames a peak and by
+ * the hover that lights a row of the peak table — so it is answered once, here,
+ * and all three agree about what is under the pointer.
+ */
+
+import { xFindClosestIndex } from 'ml-spectra-processing';
+
+import type { ChartScale } from '../../chart/core/chartScale.ts';
+import { chartPixel, chartValue } from '../../chart/core/chartScale.ts';
+
+import type { MassSpectrum } from './massSpectrum.ts';
+import { isSpectrumDrawn } from './massSpectrum.ts';
+
+/**
+ * How far from a stick the pointer may be and still be on it, in screen pixels.
+ *
+ * A screen distance, not a mass one: it is the size of a pointing gesture and
+ * has nothing to say about how close two m/z values are. Six pixels is about the
+ * jitter of a hand resting on a trackpad, and narrow enough that two sticks a
+ * few tenths apart on a zoomed axis stay separately reachable.
+ */
+export const PEAK_HIT_RADIUS = 6;
+
+/** The peak under the pointer, and which spectrum it belongs to. */
+export interface NearestPeak {
+  /** The spectrum whose centroid holds it. */
+  spectrumId: string;
+  /** Where it sits in that centroid, for looking its charge up. */
+  index: number;
+  /** Its m/z, exactly as the centroid records it. */
+  mz: number;
+  /** Its intensity. */
+  intensity: number;
+}
+
+/**
+ * The peak the pointer is on, tested on m/z alone.
+ *
+ * Only the horizontal distance is measured, so the whole column above a stick is
+ * within reach up to the top of the plot. Matching in two dimensions instead
+ * sounds more precise and is unusable: the target for a peak at one percent of
+ * the base peak would be the few pixels around its tip, so the smallest peaks —
+ * the ones worth interrogating — become the hardest to reach.
+ * @param spectra - What the chart draws; those with neither trace drawn are
+ * skipped. A spectrum drawn as its profile answers with its picked peaks all the
+ * same — they are what the pointer is really asking after.
+ * @param xScale - The m/z axis as it is currently zoomed.
+ * @param pixelX - Where the pointer is, in the same pixels the scale speaks.
+ * @param maxDistance - How far away a stick may be, in pixels; a stick exactly
+ * that far away misses. Defaults to `PEAK_HIT_RADIUS`.
+ * @returns The closest peak within that distance, `null` when there is none.
+ */
+export function nearestPeakMz(
+  spectra: readonly MassSpectrum[],
+  xScale: ChartScale,
+  pixelX: number,
+  maxDistance = PEAK_HIT_RADIUS,
+): NearestPeak | null {
+  const target = chartValue(xScale, pixelX);
+  let best: NearestPeak | null = null;
+  let bestDistance = maxDistance;
+  for (const spectrum of spectra) {
+    if (!isSpectrumDrawn(spectrum)) continue;
+    const { x, y } = spectrum.centroid;
+    if (x.length === 0) continue;
+    const index = xFindClosestIndex(x, target);
+    const mz = x[index] as number;
+    const distance = Math.abs(chartPixel(xScale, mz) - pixelX);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = {
+        spectrumId: spectrum.id,
+        index,
+        mz,
+        intensity: y[index] as number,
+      };
+    }
+  }
+  return best;
+}
+
+/**
+ * The peak a gesture landed on, given where it landed in m/z.
+ *
+ * A gesture is reported in the units the chart is measured in, while how near a
+ * stick has to be to be the one meant is a distance on the screen — so the mass
+ * goes back through the scale rather than the radius being turned into a mass,
+ * which would be a different tolerance at every zoom.
+ * @param spectra - What the chart draws.
+ * @param xScale - The m/z axis as it is currently zoomed.
+ * @param mz - Where the gesture landed, in m/z.
+ * @param maxDistance - How far away a stick may be, in pixels. Defaults to
+ * `PEAK_HIT_RADIUS`.
+ * @returns The closest peak within that distance, `null` when there is none.
+ */
+export function peakAtMz(
+  spectra: readonly MassSpectrum[],
+  xScale: ChartScale,
+  mz: number,
+  maxDistance = PEAK_HIT_RADIUS,
+): NearestPeak | null {
+  return nearestPeakMz(spectra, xScale, chartPixel(xScale, mz), maxDistance);
+}
+
+/**
+ * Whether two answers about the peak under the pointer say the same thing.
+ *
+ * The m/z is compared exactly, and that is not an oversight: both numbers were
+ * read out of the same centroid by the same index, so either they are the very
+ * same measurement or they are two different peaks. A tolerance here would
+ * declare an isotopologue pair a millimass unit apart to be one peak.
+ * @param current - What was last reported.
+ * @param next - What would be reported now.
+ * @returns Whether the report can be skipped.
+ */
+export function sameNearestPeak(
+  current: NearestPeak | null,
+  next: NearestPeak | null,
+): boolean {
+  if (current === next) return true;
+  if (current === null || next === null) return false;
+  return (
+    current.spectrumId === next.spectrumId &&
+    current.index === next.index &&
+    current.mz === next.mz
+  );
+}

package/src/mass/core/peakLabelLines.ts

@@ -0,0 +1,112 @@
+/**
+ * What the stack of labels above a peak says.
+ *
+ * A label is never one line: a peak carries its m/z and its intensity always,
+ * its charge when one was established, and the name of whatever explains it
+ * when a host says something does. Which of those are present changes from peak
+ * to peak, so the stack is built as a list and measured from its length — **an
+ * absent line consumes no slot**, and a peak nothing explains is not drawn with
+ * a gap where its name would have been.
+ *
+ * The lines come back farthest-from-the-peak first, which for a stack standing
+ * over a stick is also top-to-bottom reading order. Where those lines are then
+ * written is `labelStackBaselines` in the shared chart, which is the same sum
+ * for every kind of spectrum.
+ */
+
+import type { MassPeakObject } from './centroidPeaks.ts';
+import { formatIntensity, formatMz } from './massFormat.ts';
+import { MZ_DECIMALS } from './massResolution.ts';
+
+/** What one line of a stack is about. */
+export type PeakLabelLineKind = 'annotation' | 'charge' | 'mz' | 'intensity';
+
+/** One line of the stack above a peak. */
+export interface PeakLabelLine {
+  /** What it is about, which is also its key within the stack. */
+  kind: PeakLabelLineKind;
+  /** What it says. */
+  text: string;
+}
+
+/** What a stack is allowed to say about one peak. */
+export interface PeakLabelLinesOptions {
+  /**
+   * How many decimals the masses on screen are written with, as `mzDecimalsOf`
+   * decides, so a nominal-mass table is not written out to four decimals it
+   * never measured.
+   * @default 4
+   */
+  mzDecimals?: number;
+  /**
+   * Whether a peak whose charge was established says so. A charge of `0` means
+   * none was established and is never written, whatever this says.
+   * @default false
+   */
+  showCharges?: boolean;
+  /**
+   * The name of whatever explains this peak, absent when nothing does.
+   * @default undefined
+   */
+  annotationLabel?: string;
+  /**
+   * What one unit of the measured intensity is written as.
+   *
+   * One for every spectrum on the 0–100 scale; a spectrum that kept the counts
+   * its instrument recorded — a pixel of an imaging run — is written through a
+   * factor its host settles for the whole chart, so the numbers over the peaks
+   * and the numbers up the axis cannot disagree.
+   * @default 1
+   */
+  intensityScale?: number;
+}
+
+/**
+ * The lines the stack above one peak is made of.
+ *
+ * Ordered by how much of an answer each line is, the answer farthest from the
+ * stick and the measurement nearest it: the name of whatever explains the peak,
+ * then the charge, which qualifies the mass below it, then the m/z, which is
+ * what a chemist came to read, and the intensity last, sitting on the stick
+ * whose height already said it.
+ * @param peak - The peak being labelled.
+ * @param options - What the stack is allowed to say.
+ * @returns The lines, farthest from the peak first, never empty.
+ */
+export function peakLabelLines(
+  peak: MassPeakObject,
+  options: PeakLabelLinesOptions = {},
+): PeakLabelLine[] {
+  const {
+    mzDecimals = MZ_DECIMALS.high,
+    showCharges = false,
+    annotationLabel,
+    intensityScale = 1,
+  } = options;
+
+  const lines: PeakLabelLine[] = [];
+  if (annotationLabel !== undefined && annotationLabel !== '') {
+    lines.push({ kind: 'annotation', text: annotationLabel });
+  }
+  if (showCharges && peak.charge !== 0) {
+    lines.push({ kind: 'charge', text: `z = ${peak.charge}` });
+  }
+  lines.push(
+    { kind: 'mz', text: formatMz(peak.x, mzDecimals) },
+    {
+      kind: 'intensity',
+      text: formatIntensity(peak.y * intensityScale, mzDecimals),
+    },
+  );
+  return lines;
+}
+
+/**
+ * How one peak of one spectrum is keyed, wherever something is said about it.
+ * @param spectrumId - Identity of the spectrum.
+ * @param index - Where the peak sits in that spectrum's centroid.
+ * @returns `${spectrumId}:${index}`.
+ */
+export function peakKey(spectrumId: string, index: number): string {
+  return `${spectrumId}:${index}`;
+}