react-cheminfo 0.69.0 → 0.71.0

package/src/mass/core/peakLabelPlan.ts

@@ -0,0 +1,246 @@
+/**
+ * Where every labelled peak's numbers go, worked out before anything is drawn.
+ *
+ * Which peaks are labelled is `selectLabelledPeaks`, and the slots it makes that
+ * choice with are cut from the *window*: ten of them, whatever the chart is. A
+ * label is not — it is a number set at a fixed size, and `527.1607` is fifty
+ * pixels wide on a plot of any width. So a chart narrow enough for its slots to
+ * be thinner than that hands back two peaks whose stacks are written one across
+ * the other, and the two masses that result are neither.
+ *
+ * What settles it: **the taller peak keeps the room, and the fainter one goes
+ * without**. Never a nudge sideways — on a chart, distance from a stick is the
+ * only thing saying which stick a number belongs to, and a mass slid clear of
+ * its neighbour is a mass now hanging over somebody else's peak. The peak that
+ * loses its numbers keeps the mark on its tip, so it is not read as a peak the
+ * spectrum lacks, and a zoom widens the room and brings its stack straight back.
+ *
+ * Kept out of the component so that which peak was labelled, and at what pixel,
+ * is worth a test that no browser has to stand by for.
+ */
+
+import type { PlotRect } from '../../chart/core/chartGeometry.ts';
+import type { ChartScale } from '../../chart/core/chartScale.ts';
+import { chartPixel, chartValue } from '../../chart/core/chartScale.ts';
+import { PEAK_LABEL } from '../../chart/core/chartTheme.ts';
+import { labelStackBaselines } from '../../chart/core/labelStack.ts';
+
+import type { StackBox } from './labelStackBox.ts';
+import { labelStackBox } from './labelStackBox.ts';
+import type { LabelledPeak } from './labelledPeaks.ts';
+import { selectLabelledPeaks } from './labelledPeaks.ts';
+import type { MassSpectrum } from './massSpectrum.ts';
+import type { PeakLabelLine } from './peakLabelLines.ts';
+import { peakKey, peakLabelLines } from './peakLabelLines.ts';
+
+/** The clear space kept between two stacks standing side by side. */
+export const LABEL_SPACING = 4;
+
+/** One labelled peak: its stick, its numbers, and where both are drawn. */
+export interface PeakLabelPlan {
+  /** The peak being labelled. */
+  peak: LabelledPeak;
+  /** `${spectrumId}:${index}`, which is how anything said about it is found. */
+  key: string;
+  /** Where its stick stands, in pixels across the SVG. */
+  tipX: number;
+  /** Where the tip of that stick is, in pixels down the SVG. */
+  tipY: number;
+  /**
+   * Where the stack is centred, which is over the tip unless the peak stands so
+   * near the edge of the plot that its numbers would be written half outside it.
+   * `NaN` for a peak crowded out of its numbers by a taller neighbour, which is
+   * still marked — it simply is not written.
+   */
+  labelX: number;
+  /** What the stack says, farthest line from the peak first. */
+  lines: PeakLabelLine[];
+  /** Where each of those lines is written, in the order the lines are in. */
+  baselines: Float64Array;
+  /** The room the stack takes, which is what answers the pointer. */
+  box: StackBox;
+}
+
+/** What a set of stacks is planned against. */
+export interface PlanPeakLabelsOptions {
+  /** The spectrum whose peaks are labelled, as it is drawn. */
+  spectrum: MassSpectrum;
+  /** Where the plot sits, which is what a stack may not be written outside of. */
+  plot: PlotRect;
+  /** The m/z axis as it is currently zoomed. */
+  xScale: ChartScale;
+  /** The intensity axis as it is currently zoomed. */
+  yScale: ChartScale;
+  /**
+   * How many peaks are labelled at most, the most intense first.
+   * @default the selection's own default
+   */
+  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.
+   * @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;
+  /**
+   * What one unit of the measured intensity is written as.
+   * @default 1
+   */
+  intensityScale?: number;
+}
+
+/**
+ * Plan the stacks for the window on screen.
+ *
+ * The crowding is settled before a single line is composed, and settled in
+ * descending intensity: the tallest peak of the window asks for its stretch of
+ * the axis first and keeps it, and every fainter peak standing closer than a
+ * label is wide loses its `labelX`. What comes back is in ascending m/z, so the
+ * drawing order is the axis order and a stack keeps its key from one render to
+ * the next.
+ * @param options - The spectrum, the axes, and what the stacks may say.
+ * @returns One plan per peak that earned a label, in ascending m/z, those
+ * crowded out among them.
+ */
+export function planPeakLabels(
+  options: PlanPeakLabelsOptions,
+): PeakLabelPlan[] {
+  const {
+    spectrum,
+    plot,
+    xScale,
+    yScale,
+    limit,
+    showCharges = false,
+    mzDecimals,
+    annotationLabels,
+    below = false,
+    intensityScale = 1,
+  } = options;
+
+  const peaks = selectLabelledPeaks(spectrum, {
+    from: chartValue(xScale, plot.left),
+    to: chartValue(xScale, plot.right),
+    // The far edge of the half this spectrum is drawn in: the top of the plot
+    // for an ordinary chart, its bottom for a half drawn through a reflected
+    // scale.
+    maxValue: chartValue(yScale, below ? plot.bottom : plot.top),
+    ...(limit === undefined ? {} : { limit }),
+  });
+  if (peaks.length === 0) return [];
+
+  const centres = placeStacks(peaks, plot, xScale);
+  const bounds: [number, number] = [plot.top, plot.bottom];
+  const plans: PeakLabelPlan[] = [];
+  for (let index = 0; index < peaks.length; index++) {
+    const peak = peaks[index] as LabelledPeak;
+    const key = peakKey(spectrum.id, peak.index);
+    const lines = peakLabelLines(peak, {
+      ...(mzDecimals === undefined ? {} : { mzDecimals }),
+      showCharges,
+      intensityScale,
+      ...(annotationLabels === undefined
+        ? {}
+        : { annotationLabel: annotationLabels.get(key) }),
+    });
+    const tipY = chartPixel(yScale, peak.y);
+    const labelX = centres[index] as number;
+    const baselines = labelStackBaselines(tipY, lines.length, bounds, below);
+    plans.push({
+      peak,
+      key,
+      tipX: chartPixel(xScale, peak.x),
+      tipY,
+      labelX,
+      lines,
+      baselines,
+      box: labelStackBox(labelX, baselines),
+    });
+  }
+  return plans;
+}
+
+/**
+ * Where each stack may stand, `NaN` for one crowded out by a taller peak.
+ *
+ * A stack whose peak stands at the very edge of the plot is slid back inside it
+ * and never further, which is a different thing from clearing a neighbour: the
+ * mark stays on the stick, the number moves by a few pixels rather than by its
+ * own width, and what it avoids is being written half over the axis.
+ * @param peaks - The peaks that earned a label, in ascending m/z.
+ * @param plot - Where the plot sits inside the SVG.
+ * @param xScale - The m/z axis as it is currently zoomed.
+ * @returns The centre each stack was given, indexed as the peaks are.
+ */
+function placeStacks(
+  peaks: readonly LabelledPeak[],
+  plot: PlotRect,
+  xScale: ChartScale,
+): Float64Array {
+  const half = PEAK_LABEL.hoverHalfWidth;
+  const step = half * 2 + LABEL_SPACING;
+  // A plot too narrow to hold one whole label has no inside to slide anything
+  // back into, and the clamp would put every stack in the same place.
+  const roomy = plot.width >= half * 2;
+  const centres = new Float64Array(peaks.length).fill(Number.NaN);
+  const placed: number[] = [];
+
+  for (const index of tallestFirst(peaks)) {
+    const wanted = chartPixel(xScale, (peaks[index] as LabelledPeak).x);
+    const centre = roomy
+      ? Math.min(Math.max(wanted, plot.left + half), plot.right - half)
+      : wanted;
+    if (!clearOfPlaced(placed, centre, step)) continue;
+    placed.push(centre);
+    centres[index] = centre;
+  }
+  return centres;
+}
+
+/**
+ * The indices of the peaks, the tallest first — the order the room is handed
+ * out in, so that a base peak is labelled on every chart it appears on.
+ * @param peaks - The peaks that earned a label.
+ * @returns Their indices, descending by intensity.
+ */
+function tallestFirst(peaks: readonly LabelledPeak[]): Uint32Array {
+  const order = new Uint32Array(peaks.length);
+  for (let index = 0; index < peaks.length; index++) order[index] = index;
+  return order.toSorted(
+    (first, second) =>
+      (peaks[second] as LabelledPeak).y - (peaks[first] as LabelledPeak).y,
+  );
+}
+
+/**
+ * Whether a stack may stand where it wants to, given the ones already placed.
+ * @param placed - The centres already given out, in pixels.
+ * @param centre - The centre being asked for.
+ * @param step - How far apart two centres have to be for both to be readable.
+ * @returns Whether it clears every one of them.
+ */
+function clearOfPlaced(
+  placed: readonly number[],
+  centre: number,
+  step: number,
+): boolean {
+  for (const taken of placed) {
+    if (Math.abs(taken - centre) < step) return false;
+  }
+  return true;
+}

package/src/mass/core/peakTable.ts

@@ -0,0 +1,82 @@
+/**
+ * The rows the peak table lists, and the text they are copied out as.
+ *
+ * The rows are the centroid's own peaks, read through `selectCentroidPeaks` —
+ * the same windowing the chart is read through — so the table and the chart
+ * can never disagree about which peaks exist.
+ */
+
+import type { MassPeakObject } from './centroidPeaks.ts';
+import { selectCentroidPeaks } from './centroidPeaks.ts';
+import { formatIntensity, formatMz } from './massFormat.ts';
+import type { MassDomain, MassSpectrum } from './massSpectrum.ts';
+
+/**
+ * How many rows the table lists at most, the most intense kept.
+ *
+ * Far more than anybody reads, and few enough that a centroid of fifty
+ * thousand peaks does not lay out fifty thousand rows under a pointer move.
+ */
+export const PEAK_TABLE_LIMIT = 1000;
+
+/**
+ * The floor the table starts at, as a fraction of the base peak: where a
+ * chemist's own peak list starts, and where everything under it is the
+ * baseline the compound sits on.
+ */
+export const PEAK_TABLE_THRESHOLD = 0.01;
+
+/** Which peaks the table lists. */
+export interface PeakTableOptions {
+  /**
+   * The window the chart shows, when the table is to follow it; `null` for the
+   * whole spectrum.
+   * @default null
+   */
+  domain?: MassDomain | null;
+  /**
+   * The floor, as a fraction of the base peak; `0` lists every peak.
+   * @default PEAK_TABLE_THRESHOLD
+   */
+  threshold?: number;
+}
+
+/**
+ * The peaks the table lists for one spectrum, in increasing m/z.
+ * @param spectrum - The spectrum the table is about.
+ * @param options - The window, and the floor.
+ * @returns The peaks, shared with the centroid's cache — read, never written.
+ */
+export function peakTableRows(
+  spectrum: MassSpectrum,
+  options: PeakTableOptions = {},
+): MassPeakObject[] {
+  const { domain = null, threshold = PEAK_TABLE_THRESHOLD } = options;
+  return selectCentroidPeaks(spectrum.centroid, {
+    ...(domain === null ? {} : { from: domain.x[0], to: domain.x[1] }),
+    threshold,
+    limit: PEAK_TABLE_LIMIT,
+  });
+}
+
+/**
+ * The rows as tab-separated text, the way a spreadsheet takes a paste.
+ *
+ * Written to the decimals the table shows rather than as the doubles are held,
+ * so what is pasted is what was read on screen.
+ * @param peaks - The rows, in the order they are listed.
+ * @param mzDecimals - How many decimals the masses are written with.
+ * @returns A header line and one line per peak.
+ */
+export function peakTableToTsv(
+  peaks: readonly MassPeakObject[],
+  mzDecimals: number,
+): string {
+  const lines = ['m/z\tintensity\tcharge'];
+  for (const peak of peaks) {
+    lines.push(
+      `${formatMz(peak.x, mzDecimals)}\t${formatIntensity(peak.y, mzDecimals)}\t${peak.charge === 0 ? '' : peak.charge}`,
+    );
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/mass/core/resolutionOf.ts

@@ -0,0 +1,100 @@
+/**
+ * The resolution of a spectrum as everything downstream asks for it, and the
+ * decimals every number on screen is written with.
+ */
+
+import type { MassResolution } from './massResolution.ts';
+import { MZ_DECIMALS, statedResolution } from './massResolution.ts';
+import type { MassMeta, MassSpectrum } from './massSpectrum.ts';
+import { writtenResolution } from './writtenResolution.ts';
+
+/** The evidence a verdict is decided on. */
+export interface DecideResolutionOptions {
+  /** What the peak widths measured, `null` for a peak table. */
+  measured: MassResolution | null;
+  /** What the file said about the acquisition. */
+  meta: MassMeta | null;
+  /** The m/z of every picked peak. */
+  masses: Float64Array;
+}
+
+/**
+ * The strongest verdict there is evidence for.
+ *
+ * A measurement wins outright. Otherwise the instrument the file names decides
+ * the kind, but never the decimals beyond what the masses were written with:
+ * an ion trap exporting four decimals resolves one, and a table of whole
+ * numbers stays whole whatever instrument it came off — writing `330.0` claims
+ * a decimal nobody wrote.
+ * @param options - The measurement, the file's records and the masses.
+ * @returns The verdict.
+ */
+export function decideResolution(
+  options: DecideResolutionOptions,
+): MassResolution {
+  const { measured, meta, masses } = options;
+  if (measured !== null) return measured;
+  const written = writtenResolution(masses);
+  const stated = statedResolution(meta);
+  if (stated === null || written.kind === 'nominal') return written;
+  return { ...stated, decimals: Math.min(stated.decimals, written.decimals) };
+}
+
+/**
+ * The verdict on a spectrum: the one it was read with, or else the one its file
+ * and its masses imply.
+ *
+ * A spectrum a host built itself carries no verdict, and has no peak widths to
+ * measure one from either, so what the file named and what the masses were
+ * written with are all there is. Cached per centroid, since the verdict is
+ * asked of every drawn spectrum on every change of what is drawn, and a
+ * centroid is replaced rather than written into.
+ * @param spectrum - The spectrum.
+ * @returns How finely it resolves masses.
+ */
+export function resolutionOf(spectrum: MassSpectrum): MassResolution {
+  if (spectrum.resolution !== undefined) return spectrum.resolution;
+  const cached = decidedCache.get(spectrum.centroid.x);
+  if (cached !== undefined) return cached;
+  const resolution = decideResolution({
+    measured: null,
+    meta: spectrum.meta,
+    masses: spectrum.centroid.x,
+  });
+  decidedCache.set(spectrum.centroid.x, resolution);
+  return resolution;
+}
+
+/**
+ * How many decimals the masses of spectra drawn together are written with when
+ * nobody chose: high-resolution masses or nominal ones, nothing in between.
+ *
+ * A high-resolution spectrum is written to the decimals its verdict allows —
+ * four, or fewer where the file wrote fewer, since padding `330.12` out to
+ * `330.1200` claims digits nobody measured. Anything else is written as the
+ * nominal mass: a low-resolution instrument's decimals are where its noise
+ * lives, and a reader who wants them chooses a number of decimals instead.
+ *
+ * Asked of all of them at once rather than of each, so one table and one axis
+ * never disagree about how wide a number is — and the most precise spectrum
+ * wins: put a calculated isotopic pattern beside a nominal peak table and the
+ * masses go back to four decimals, because rounding the pattern to match would
+ * hide the very difference the comparison was made to show.
+ * @param spectra - The spectra being shown together.
+ * @returns The decimals; four when none of them holds a peak.
+ */
+export function mzDecimalsOf(spectra: readonly MassSpectrum[]): number {
+  let decimals = -1;
+  for (const spectrum of spectra) {
+    if (spectrum.centroid.x.length === 0) continue;
+    const resolution = resolutionOf(spectrum);
+    decimals = Math.max(
+      decimals,
+      resolution.kind === 'high' ? resolution.decimals : MZ_DECIMALS.nominal,
+    );
+  }
+  return decimals === -1 ? MZ_DECIMALS.high : decimals;
+}
+
+/** The verdicts already decided, keyed by the masses they were decided on. */
+const decidedCache = new WeakMap<Float64Array, MassResolution>();

package/src/mass/core/scanFilter.ts

@@ -0,0 +1,119 @@
+/**
+ * What a Thermo scan filter states, mined for the fields the records left blank.
+ *
+ * The structured `##$` records are the polite answer and the scan filter is the
+ * honest one: a real Exploris export writes `##$IONISATION=` with nothing after
+ * the equals sign and then names `NSI` in the middle of the conditions block
+ * two lines later. So every field falls back to this, per field and never
+ * wholesale — an explicit record always wins, because the exporter that wrote
+ * it knew something the filter line does not say.
+ *
+ * A filter reads like
+ * `FTMS + p NSI Full ms2 194.5000@hcd50.00 [44.0860-220.4300]`, preceded by the
+ * raw file name and followed by `Scan #:` and `RT:` lines.
+ */
+
+/**
+ * Read every field a conditions block states.
+ *
+ * Keyed by the same labels the metadata table uses, so a caller only has to
+ * look up the label it failed to fill — nothing here has to know which fields
+ * exist or what order they are shown in.
+ * @param conditions - The instrument's own scan description, verbatim.
+ * @returns The fields it states, by label; empty when it states none.
+ */
+export function parseScanFilter(conditions: string): Record<string, string> {
+  if (!conditions) return {};
+  const derived: Record<string, string> = {};
+
+  const analyser = group(/^(?<value>FTMS|ITMS|TOFMS)\b/m, conditions);
+  if (analyser) derived.Analyser = analyser;
+
+  const ionisation = group(/\b(?<value>ESI|NSI|APCI|MALDI)\b/, conditions);
+  if (ionisation) derived.Ionization = ionisation;
+
+  // The sign is read between the analyser and the ion source rather than on its
+  // own, because a bare `-` also separates the two ends of the scan range.
+  if (/(?:FTMS|ITMS|TOFMS) \+ /.test(conditions)) {
+    derived.Polarity = 'positive';
+  } else if (/(?:FTMS|ITMS|TOFMS) - /.test(conditions)) {
+    derived.Polarity = 'negative';
+  }
+
+  readFragmentation(conditions, derived);
+
+  const range = /\[(?<from>[\d.]+)-(?<to>[\d.]+)\]/.exec(conditions);
+  const from = range?.groups?.from;
+  const to = range?.groups?.to;
+  if (from !== undefined && to !== undefined) {
+    derived['Scan range'] = `${Number(from)}–${Number(to)} m/z`;
+  }
+
+  const retentionTime = group(/^RT:\s*(?<value>.+)$/m, conditions);
+  if (retentionTime) derived['Retention time'] = `${retentionTime} min`;
+
+  const scans = group(/^Scan #:\s*(?<value>.+)$/m, conditions);
+  if (scans) derived.Scans = scans;
+
+  const rawFile = group(/^(?<value>\S+\.raw)$/m, conditions);
+  if (rawFile) derived['Raw file'] = rawFile;
+
+  return derived;
+}
+
+/**
+ * Read the level a scan was taken at, and what it isolated to get there.
+ *
+ * The level is read first and everything else only under it, because the
+ * isolation and the energy are the level's own clause: a survey scan that
+ * happens to be described one line below a product scan states no level of its
+ * own, and reading its `@hcd50.00` anyway would report a collision energy for a
+ * spectrum nothing was ever fragmented into.
+ *
+ * The level is not tied to the shape of that clause, though — `Full ms2
+ * 194.5000@etd` and `SIM ms [190.0000-200.0000]` are both real filters, and an
+ * MS2 that loses its level because the activation was spelled unusually loses
+ * the precursor the annotator would have searched for.
+ * @param conditions - The instrument's own scan description.
+ * @param derived - The fields read so far, added to in place.
+ */
+function readFragmentation(
+  conditions: string,
+  derived: Record<string, string>,
+): void {
+  const level = /\b(?:Full|SIM|SRM) ms(?<level>\d*)\b/.exec(conditions)?.groups
+    ?.level;
+  if (level === undefined) return;
+  if (level === '') {
+    derived['MS level'] = 'MS1';
+    return;
+  }
+  derived['MS level'] = `MS${level}`;
+
+  // The isolation is anchored to the level the filter just stated, so an MS3
+  // reports the window it was isolated at rather than the one before it.
+  const isolation = group(
+    new RegExp(String.raw` ms${level} (?<value>\d+(?:\.\d+)?)`),
+    conditions,
+  );
+  if (isolation) derived['Isolation m/z'] = isolation;
+
+  const clause = /@(?<activation>[a-z]+)(?<energy>\d+(?:\.\d+)?)/.exec(
+    conditions,
+  );
+  const activation = clause?.groups?.activation;
+  const energy = clause?.groups?.energy;
+  if (activation !== undefined && energy !== undefined) {
+    derived['Collision energy'] = `${activation.toUpperCase()} ${energy}`;
+  }
+}
+
+/**
+ * The `value` capture of a pattern, trimmed.
+ * @param pattern - A regular expression carrying a `value` named group.
+ * @param conditions - The text to read it out of.
+ * @returns The capture, or `''` when the pattern does not match.
+ */
+function group(pattern: RegExp, conditions: string): string {
+  return pattern.exec(conditions)?.groups?.value?.trim() ?? '';
+}