react-cheminfo 0.69.0 → 0.71.0

package/src/mass/core/ascendingTrace.ts

@@ -0,0 +1,62 @@
+/**
+ * The one thing both readers have to do to the points a parser hands back.
+ *
+ * Every peak lookup, crosshair and label here finds its point by bisection, and
+ * bisection over a descending axis does not fail — it answers confidently and
+ * wrongly. A JCAMP keeps the order the file wrote, and a peak table pasted out
+ * of a report may be sorted by intensity, so the order is checked and mended
+ * here, once, rather than trusted downstream.
+ */
+
+import type { NumberArray } from 'cheminfo-types';
+import { xyEnsureFloat64, xySortX, xyUniqueX } from 'ml-spectra-processing';
+
+import type { MassTrace } from './massSpectrum.ts';
+
+/**
+ * The points, typed, in increasing m/z, each m/z once.
+ *
+ * A mass written twice is summed into one point rather than kept as two: a
+ * peak list exported from two overlapping scan ranges repeats the masses where
+ * they meet, and two sticks at one m/z are one ion measured twice.
+ * @param x - The masses, in the order the parser read them.
+ * @param y - The intensities, in the same order.
+ * @returns The trace; the arrays handed in themselves when they were already
+ * typed, ascending and free of repeats.
+ */
+export function ascendingTrace(x: NumberArray, y: NumberArray): MassTrace {
+  const typed = xyEnsureFloat64({ x, y });
+  const sorted = isAscending(typed.x) ? typed : xySortX(typed);
+  if (!repeatsMass(sorted.x)) return sorted;
+  return xyEnsureFloat64(
+    xyUniqueX(sorted, { algorithm: 'sum', isSorted: true }),
+  );
+}
+
+/**
+ * Whether an axis never steps backwards.
+ *
+ * Checked rather than sorted unconditionally, because a mass spectrum is
+ * written ascending nearly always and the common case then costs one
+ * comparison per point and no allocation at all.
+ * @param values - The axis.
+ * @returns `true` when each point is at least as far along as the one before.
+ */
+function isAscending(values: Float64Array): boolean {
+  for (let index = 1; index < values.length; index++) {
+    if ((values[index] as number) < (values[index - 1] as number)) return false;
+  }
+  return true;
+}
+
+/**
+ * Whether an ascending axis holds the same mass twice.
+ * @param values - The axis, ascending.
+ * @returns `true` when two neighbours are equal.
+ */
+function repeatsMass(values: Float64Array): boolean {
+  for (let index = 1; index < values.length; index++) {
+    if (values[index] === values[index - 1]) return true;
+  }
+  return false;
+}

package/src/mass/core/centroidPeaks.ts

@@ -0,0 +1,114 @@
+/**
+ * The centroid as `ms-spectrum` wants to see it, and the windowing built on it.
+ *
+ * Everything that package does to a peak table — filtering it to a window,
+ * keeping the most intense, ranking the best — takes and returns an array of
+ * `{ x, y }` objects, while this package holds peaks as three parallel typed
+ * arrays. The translation is therefore paid on every zoom and every pointer
+ * move unless it is paid once, which is what this file is for.
+ */
+
+import { getPeaks } from 'ms-spectrum';
+
+import type { MassPeaks } from './massSpectrum.ts';
+
+/**
+ * One peak in the shape `ms-spectrum` speaks.
+ *
+ * `charge` is always present and `0` stands for "none was established", where
+ * `ms-spectrum` leaves the property off entirely — the column it comes from is
+ * dense, and a consumer reading `peak.charge > 1` should not have to remember
+ * which of the two conventions it is holding.
+ */
+export interface MassPeakObject {
+  /** Where the peak sits, in m/z. */
+  x: number;
+  /** Its intensity, on the 0–100 scale the analysis normalised to. */
+  y: number;
+  /** The charge of the series it belongs to, `0` where none was established. */
+  charge: number;
+}
+
+/** Which peaks of a centroid a window is interested in. */
+export interface SelectCentroidPeaksOptions {
+  /**
+   * Lowest m/z considered.
+   * @default the m/z of the first peak
+   */
+  from?: number;
+  /**
+   * Highest m/z considered.
+   * @default the m/z of the last peak
+   */
+  to?: number;
+  /**
+   * Smallest intensity kept, as a fraction of the base peak of the whole
+   * spectrum rather than of the window — zooming into the baseline shows the
+   * baseline, not peaks promoted by their neighbours scrolling off.
+   * @default 0.01
+   */
+  threshold?: number;
+  /**
+   * How many peaks at most, keeping the most intense. `0` is read as no limit.
+   * @default undefined
+   */
+  limit?: number;
+}
+
+/**
+ * The peaks of a centroid as objects, built once and handed out again.
+ *
+ * Kept in a `WeakMap` on the centroid itself rather than recomputed: a spectrum
+ * is windowed on every zoom and every pointer move, and a hundred thousand
+ * short-lived objects a gesture is what makes a viewer stutter. The centroid is
+ * replaced on a change and never written into, so its identity is a sound key,
+ * and the entry goes when the spectrum does. The objects are shared with every
+ * caller and with the cache — read them, never write into them.
+ * @param centroid - The picked peaks.
+ * @returns The same peaks as objects, in increasing m/z.
+ * @throws {RangeError} When the three columns are not the same length.
+ */
+export function centroidPeakObjects(centroid: MassPeaks): MassPeakObject[] {
+  const cached = peakObjectCache.get(centroid);
+  if (cached !== undefined) return cached;
+
+  const count = centroid.x.length;
+  if (centroid.y.length !== count || centroid.charge.length !== count) {
+    throw new RangeError(
+      `The centroid carries ${count} masses, ${centroid.y.length} intensities and ${centroid.charge.length} charges; every peak needs one of each`,
+    );
+  }
+  const objects = new Array<MassPeakObject>(count);
+  for (let index = 0; index < count; index++) {
+    objects[index] = {
+      x: centroid.x[index] as number,
+      y: centroid.y[index] as number,
+      charge: centroid.charge[index] as number,
+    };
+  }
+  peakObjectCache.set(centroid, objects);
+  return objects;
+}
+
+/**
+ * The peaks of a window, at most so many of them and the most intense kept.
+ *
+ * What a peak table asks for on every zoom: a centroid has far more peaks than
+ * anybody reads, and which ones are worth a row changes with the window. It
+ * reads the cached objects, so a zoom costs the filtering alone.
+ * @param centroid - The picked peaks.
+ * @param options - The window, and how many peaks it has room for.
+ * @returns The selected peaks, in increasing m/z, sharing the cached objects.
+ */
+export function selectCentroidPeaks(
+  centroid: MassPeaks,
+  options: SelectCentroidPeaksOptions = {},
+): MassPeakObject[] {
+  const objects = centroidPeakObjects(centroid);
+  // `getPeaks` reads the window it was given no bounds for off the first and
+  // last peak, which it cannot do when there are none.
+  if (objects.length === 0) return [];
+  return getPeaks(objects, options) as MassPeakObject[];
+}
+
+const peakObjectCache = new WeakMap<MassPeaks, MassPeakObject[]>();

package/src/mass/core/detectMassFormat.ts

@@ -0,0 +1,113 @@
+/**
+ * Which reader a dropped file belongs to, decided from the file itself.
+ *
+ * The extension is the least reliable thing about a spectrum file: instruments
+ * export JCAMP as `.txt`, LIMS systems rename everything to `.dat`, and a user
+ * pasting into a text box has no extension at all. So the content decides and
+ * the name is consulted only when the content stayed silent.
+ */
+
+/** What a file can turn out to be, as far as this viewer reads it. */
+export type DetectedMassFormat = 'jcamp' | 'text' | 'unknown';
+
+/**
+ * How much of the file the decision is taken on.
+ *
+ * The one marker looked for sits at the very top — `##TITLE=` opens a JCAMP —
+ * so reading further would only cost a decode of the whole file.
+ */
+const HEADER_BYTES = 4096;
+
+/**
+ * Extensions that name a format outright, once the content has said nothing.
+ *
+ * A `Map` rather than an object, because the key comes off a file name the user
+ * chose: `spectrum.constructor` read out of an object literal answers with a
+ * function inherited from `Object.prototype`, which is neither a format nor
+ * `undefined` and so passes every check made of it.
+ */
+const EXTENSIONS = new Map<string, DetectedMassFormat>([
+  ['jdx', 'jcamp'],
+  ['dx', 'jcamp'],
+  ['jcamp', 'jcamp'],
+  ['txt', 'text'],
+  ['csv', 'text'],
+  ['tsv', 'text'],
+  ['xy', 'text'],
+  ['asc', 'text'],
+  ['dat', 'text'],
+]);
+
+/**
+ * The one decoder the header is read through, kept because a drop of fifty
+ * files would otherwise build fifty of them for four kilobytes each.
+ */
+const DECODER = new TextDecoder();
+
+/**
+ * Decide what a dropped file is, from its first bytes and only then its name.
+ *
+ * Returns `'unknown'` rather than guessing `'text'` for the two cases the
+ * readers cannot survive: nothing at all, and bytes that are plainly not text.
+ * Handing either to the text reader produces an empty spectrum and a message
+ * about missing columns, which sends whoever dropped the file looking in the
+ * wrong place.
+ * @param data - The file, or the pasted text.
+ * @param fileName - Its name, when it has one.
+ * @returns The format, or `'unknown'` when nothing in the file names one.
+ */
+export function detectMassFormat(
+  data: Uint8Array | string,
+  fileName?: string,
+): DetectedMassFormat {
+  const header = stripByteOrderMark(readHeader(data)).trimStart();
+  if (header.startsWith('##')) return 'jcamp';
+
+  const named = formatFromExtension(fileName);
+  if (named !== undefined && named !== 'text') return named;
+  if (header.length === 0) return 'unknown';
+  // A binary file decodes to replacement characters; a peak list decodes to
+  // digits. Telling them apart on the decode is what stops a stray `.raw` from
+  // reaching the text reader and being told it holds no columns of numbers.
+  if (header.includes('�') || header.includes('\0')) return 'unknown';
+  return 'text';
+}
+
+/**
+ * The first bytes of the file, as text.
+ * @param data - The file, or the pasted text.
+ * @returns The decoded prefix; a byte sequence cut in half at the end decodes
+ * to a replacement character, which the marker looked for does not contain.
+ */
+function readHeader(data: Uint8Array | string): string {
+  if (typeof data === 'string') return data.slice(0, HEADER_BYTES);
+  return DECODER.decode(data.subarray(0, HEADER_BYTES));
+}
+
+/**
+ * Drop a leading UTF-8 byte order mark.
+ *
+ * This is the whole reason the header is normalised before it is tested: a
+ * `U+FEFF` in front of `##TITLE=` makes a plain `startsWith('##')` fail, and a
+ * JCAMP carrying one then goes silently to the text reader, which reads its
+ * records as unparsable lines and reports two columns of nothing.
+ * @param header - The decoded prefix.
+ * @returns The prefix without its mark.
+ */
+function stripByteOrderMark(header: string): string {
+  return header.startsWith('') ? header.slice(1) : header;
+}
+
+/**
+ * The format a file name claims, used only once the content has said nothing.
+ * @param fileName - The name, when the file has one.
+ * @returns The format, or `undefined` when the extension names none.
+ */
+function formatFromExtension(
+  fileName?: string,
+): DetectedMassFormat | undefined {
+  if (fileName === undefined) return undefined;
+  const extension = fileName.split('.').pop();
+  if (extension === undefined || extension === fileName) return undefined;
+  return EXTENSIONS.get(extension.toLowerCase());
+}

package/src/mass/core/downloadSpectra.ts

@@ -0,0 +1,52 @@
+/**
+ * Handing spectra over as a file, from the list they are drawn from.
+ *
+ * Kept apart from `spectrumJcamp.ts` so that what a file holds can be tested
+ * without a DOM, and so that a page wanting the text for something other than a
+ * download — a POST to an ELN, a zip of a whole session — reaches for the writer
+ * and not for this.
+ */
+
+import { downloadText } from '../../download/core/downloadText.ts';
+import { sanitizeFileName } from '../../download/core/sanitizeFileName.ts';
+
+import type { MassSpectrum } from './massSpectrum.ts';
+import {
+  JCAMP_EXTENSION,
+  JCAMP_MIME_TYPE,
+  massSpectraToJcamp,
+  massSpectrumToJcamp,
+} from './spectrumJcamp.ts';
+
+/**
+ * Download one spectrum, named after what the list calls it.
+ * @param spectrum - The spectrum.
+ */
+export function downloadMassSpectrum(spectrum: MassSpectrum): void {
+  downloadText(
+    massSpectrumToJcamp(spectrum),
+    `${sanitizeFileName(spectrum.name, 'spectrum')}${JCAMP_EXTENSION}`,
+    JCAMP_MIME_TYPE,
+  );
+}
+
+/**
+ * Download the whole list as one file.
+ *
+ * A list of one is saved under that spectrum's own name, since the file is that
+ * spectrum: a chemist who has one spectrum open and asks the panel for it should
+ * not have to work out which of their downloads `spectra.jdx` was.
+ * @param spectra - The spectra, in the order the list holds them.
+ */
+export function downloadMassSpectra(spectra: readonly MassSpectrum[]): void {
+  const only = spectra.length === 1 ? spectra[0] : undefined;
+  if (only !== undefined) {
+    downloadMassSpectrum(only);
+    return;
+  }
+  downloadText(
+    massSpectraToJcamp(spectra),
+    `spectra${JCAMP_EXTENSION}`,
+    JCAMP_MIME_TYPE,
+  );
+}

package/src/mass/core/fromJcamp.ts

@@ -0,0 +1,151 @@
+/**
+ * Read a JCAMP-DX file into mass spectra, through `jcampconverter`.
+ *
+ * Every block, never the first: a JCAMP is a container, a `LINK` block holds
+ * several spectra and a GC/MS export writes one page per scan of an `NTUPLES`
+ * block. Taking only the first would quietly drop what the chemist exported the
+ * file for, and would do it without an error, which is the worst way to lose
+ * data.
+ *
+ * Two things the converter reports are deliberately not believed. The order of
+ * the points, which `ascendingTrace` mends. And its `isPeaktable` flag, which is
+ * set for *any* table of explicit `x y` pairs — instrument software writes
+ * continuous Orbitrap scans as `##PEAK TABLE=(XY..XY)` as a matter of course,
+ * because the compressed alternative rebuilds the axis from a first x and an
+ * increment, and an FT scan is not evenly sampled. Taken at its word, ten
+ * thousand points of a profile draw as ten thousand sticks; so the claim is
+ * dropped and the spacing of the points decides.
+ */
+
+import { convert } from 'jcampconverter';
+
+import { describeSource, errorMessage } from '../../error/core/index.ts';
+
+import { ascendingTrace } from './ascendingTrace.ts';
+import { otherTechnique } from './jcampTechnique.ts';
+import type { LoadedMassSpectrum } from './loadedMassSpectrum.ts';
+import { buildMassMeta, recordText } from './massMeta.ts';
+
+/** How a JCAMP is read. */
+export interface MassJcampReadOptions {
+  /**
+   * The file's name, carried onto every spectrum it produced.
+   * @default undefined
+   */
+  fileName?: string;
+  /** At most how many spectra to read out of it. */
+  maxSpectra: number;
+}
+
+/** What a JCAMP turned out to hold. */
+export interface MassJcampReadResult {
+  /** The spectra, in the order the file wrote them. */
+  spectra: LoadedMassSpectrum[];
+  /** How many spectra `maxSpectra` left unread, `0` when none. */
+  dropped: number;
+}
+
+/**
+ * Read every mass spectrum a JCAMP-DX file holds.
+ * @param data - The file, as bytes or as text.
+ * @param options - The file's name, and how many spectra to read at most.
+ * @returns The spectra, and how many were left unread.
+ * @throws {Error} When the converter gave up on the file, or when no block of
+ * it holds a mass spectrum — with a sentence saying which of the two.
+ */
+export function fromJcamp(
+  data: Uint8Array | string,
+  options: MassJcampReadOptions,
+): MassJcampReadResult {
+  const { fileName, maxSpectra } = options;
+
+  let entries: ReturnType<typeof convert>['flatten'];
+  try {
+    entries = convert(data, { keepRecordsRegExp: /.*/ }).flatten;
+  } catch (error) {
+    // The converter's own words are kept because they name the record it
+    // stopped on, which is more than anything written here could say — but they
+    // are said about nothing, and a chemist who has just dropped eleven files
+    // needs to know which of them this is.
+    throw new Error(
+      `${describeSource(fileName)} could not be read as JCAMP-DX — the converter stopped on it with: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  }
+
+  const spectra: LoadedMassSpectrum[] = [];
+  const refused: string[] = [];
+  let found = 0;
+  for (const entry of entries) {
+    const technique = otherTechnique(entry);
+    if (technique !== null) {
+      refused.push(technique);
+      continue;
+    }
+    const meta = buildMassMeta({
+      info: entry.info,
+      meta: entry.meta,
+      ...(entry.title === undefined ? {} : { title: entry.title }),
+    });
+    const title = recordText(entry.title);
+    const pages = entry.spectra.length;
+    for (const page of entry.spectra) {
+      const x = page.data.x ?? [];
+      const y = page.data.y ?? [];
+      if (x.length === 0) continue;
+      found++;
+      if (spectra.length >= maxSpectra) continue;
+      const loaded: LoadedMassSpectrum = {
+        trace: ascendingTrace(x, y),
+        meta,
+        origin: { format: 'jcamp' },
+      };
+      const name = pageName(title, pages > 1 ? recordText(page.page) : '');
+      if (name !== '') loaded.name = name;
+      spectra.push(loaded);
+    }
+  }
+
+  if (spectra.length === 0) {
+    throw new Error(nothingToRead(describeSource(fileName), refused));
+  }
+  // Numbered only when there is more than one to tell apart: a file holding
+  // one spectrum has no acquisition to point at but the whole file.
+  for (let index = 0; spectra.length > 1 && index < spectra.length; index++) {
+    (spectra[index] as LoadedMassSpectrum).origin.scanIndex = index;
+  }
+  for (const spectrum of spectra) {
+    if (fileName !== undefined) spectrum.origin.fileName = fileName;
+  }
+  return { spectra, dropped: found - spectra.length };
+}
+
+/**
+ * What to call one spectrum of a file: its title, and its page when the block
+ * holds several — `T= 720` is how a GC/MS export names the scan at 720 s.
+ * @param title - The block's title, `''` when it carries none.
+ * @param page - The page's own label, `''` for a block of one spectrum.
+ * @returns The name, `''` when there is nothing to call it.
+ */
+function pageName(title: string, page: string): string {
+  if (page === '') return title;
+  return title === '' ? page : `${title} (${page})`;
+}
+
+/**
+ * The sentence for a file that was read and held nothing this viewer wants.
+ *
+ * Two files end here and only one of them is broken: a file of infrared
+ * spectra is a perfectly good JCAMP opened by the wrong viewer, and saying so
+ * sends its owner to the right one rather than to the file.
+ * @param named - How to name the file at the start of a sentence.
+ * @param refused - What each block that stated another technique called itself.
+ * @returns The sentence to throw.
+ */
+function nothingToRead(named: string, refused: readonly string[]): string {
+  if (refused.length > 0) {
+    const stated = [...new Set(refused)].join(', ');
+    return `${named} was read as JCAMP-DX but holds no mass spectrum — its blocks state ${stated}. A mass spectrum is read from a block whose ##DATA TYPE names mass spectrometry, or that names no other technique at all.`;
+  }
+  return `${named} was read as JCAMP-DX but holds no spectrum — no block in it carries points under ##XYDATA=, ##PEAK TABLE=, ##DATA TABLE= or ##NTUPLES=.`;
+}

package/src/mass/core/fromText.ts

@@ -0,0 +1,58 @@
+/**
+ * Read two columns of m/z and intensity, through `xy-parser`.
+ *
+ * Whatever separates the columns — a tab, a comma, spaces, a semicolon — and
+ * whatever header lines come before the numbers, `xy-parser` finds the numbers,
+ * so a peak list copied out of an instrument report, a CSV export and a
+ * hand-typed table are all one format here.
+ */
+
+import { parseXY } from 'xy-parser';
+
+import { describeSource } from '../../error/core/index.ts';
+
+import { ascendingTrace } from './ascendingTrace.ts';
+import type { LoadedMassSpectrum } from './loadedMassSpectrum.ts';
+
+/** How a text file is read. */
+export interface MassTextReadOptions {
+  /**
+   * The file's name, carried onto the spectrum.
+   * @default undefined
+   */
+  fileName?: string;
+}
+
+/**
+ * Read the one spectrum two columns of numbers make.
+ *
+ * Nothing is said about the acquisition, because two columns say nothing: the
+ * spectrum comes back with no metadata and no name of its own, and is called
+ * after its file.
+ * @param data - The file, as bytes or as text.
+ * @param options - The file's name.
+ * @returns The spectrum, as a list of one, the way every reader answers.
+ * @throws {Error} When no line of it holds two numbers.
+ */
+export function fromText(
+  data: Uint8Array | string,
+  options: MassTextReadOptions = {},
+): LoadedMassSpectrum[] {
+  const { fileName } = options;
+  const { x, y } = parseXY(data);
+  if (x.length === 0) {
+    throw new Error(
+      `${describeSource(fileName)} holds no two columns of numbers — a spectrum in text is one line per point, the m/z first and the intensity after it.`,
+    );
+  }
+  return [
+    {
+      trace: ascendingTrace(x, y),
+      meta: null,
+      origin:
+        fileName === undefined
+          ? { format: 'text' }
+          : { format: 'text', fileName },
+    },
+  ];
+}