react-cheminfo 0.69.0 → 0.71.0

package/src/mass/core/index.ts

@@ -0,0 +1,194 @@
+/**
+ * What a mass spectrum is, and everything true of one that draws nothing.
+ *
+ * Reading a JCAMP-DX or a two-column text file, picking the peaks of a profile,
+ * deciding whether the spectrum is high resolution, choosing which peaks are
+ * worth a label, writing the spectra back out as JCAMP — none of it needs
+ * React, so a script that reads a directory of spectra loads none.
+ *
+ * Nothing here knows what a glycan, a peptide or a polymer is, and nothing
+ * should: a mass spectrum answers for whatever was put in the source.
+ */
+
+export type {
+  AnalyseSpectrumOptions,
+  AnalysedSpectrum,
+} from './analyseSpectrum.ts';
+export { analyseSpectrum } from './analyseSpectrum.ts';
+export { ascendingTrace } from './ascendingTrace.ts';
+export type {
+  MassPeakObject,
+  SelectCentroidPeaksOptions,
+} from './centroidPeaks.ts';
+export { centroidPeakObjects, selectCentroidPeaks } from './centroidPeaks.ts';
+export type { DetectedMassFormat } from './detectMassFormat.ts';
+export { detectMassFormat } from './detectMassFormat.ts';
+export {
+  downloadMassSpectra,
+  downloadMassSpectrum,
+} from './downloadSpectra.ts';
+export type { MassJcampReadOptions, MassJcampReadResult } from './fromJcamp.ts';
+export type { MassTextReadOptions } from './fromText.ts';
+export type { JcampBlockHeader } from './jcampTechnique.ts';
+export { otherTechnique } from './jcampTechnique.ts';
+export type { HoveredPeak, StackBox } from './labelStackBox.ts';
+export { labelStackBox } from './labelStackBox.ts';
+export type {
+  LabelledPeak,
+  SelectLabelledPeaksOptions,
+} from './labelledPeaks.ts';
+export {
+  LABEL_SLOTS,
+  LABEL_THRESHOLD,
+  selectLabelledPeaks,
+} from './labelledPeaks.ts';
+export type {
+  LoadMassSpectraOptions,
+  LoadMassSpectraResult,
+} from './loadMassSpectra.ts';
+export { DEFAULT_MAX_SPECTRA, loadMassSpectra } from './loadMassSpectra.ts';
+export type { LoadedMassSpectrum } from './loadedMassSpectrum.ts';
+export type {
+  MassCommand,
+  MassCommandHandlers,
+  MassCommandId,
+  MassGesture,
+  MassShortcut,
+  RunMassCommand,
+} from './massCommands.ts';
+export { massCommandLabel, massCommands } from './massCommands.ts';
+export type { MzFrameOptions } from './massDomain.ts';
+export {
+  MZ_FRAME_HALF_WIDTH,
+  X_DOMAIN_PADDING,
+  Y_DOMAIN_HEADROOM,
+  basePeakOf,
+  fittedTo,
+  fullDomain,
+  mzFrame,
+} from './massDomain.ts';
+export type {
+  MassEditorHandle,
+  MassPlotClick,
+  ZoomToMzOptions,
+} from './massEditorApi.ts';
+export {
+  INTENSITY_DECIMALS,
+  formatIntensity,
+  formatMz,
+  formatMzRange,
+  massFormatLabel,
+  resolutionBasisLabel,
+  resolutionLabel,
+  resolvingPowerLabel,
+} from './massFormat.ts';
+export type { MassMetaRecord, MassMetaSource } from './massMeta.ts';
+export { buildMassMeta, metaRecord, recordText } from './massMeta.ts';
+export type { MassAction, SpectrumVisibility } from './massReducer.ts';
+export { massReducer } from './massReducer.ts';
+export type {
+  MassResolution,
+  MassResolutionBasis,
+  MassResolutionKind,
+  WidthPeak,
+} from './massResolution.ts';
+export {
+  HIGH_RESOLVING_POWER,
+  MEASURED_PEAKS,
+  MZ_DECIMALS,
+  measuredResolution,
+  statedResolution,
+} from './massResolution.ts';
+export type { MassPanelId, MassSidePanelId } from './massSidePanels.ts';
+export { massSidePanels } from './massSidePanels.ts';
+export type {
+  MassDomain,
+  MassFormat,
+  MassMeta,
+  MassMetaField,
+  MassOrigin,
+  MassPeaks,
+  MassSpectrum,
+  MassTrace,
+} from './massSpectrum.ts';
+export { isSpectrumDrawn } from './massSpectrum.ts';
+export type {
+  CreateMassStateOptions,
+  MassData,
+  MassSettings,
+  MassState,
+  MassTool,
+  MassView,
+  PartialMassState,
+} from './massState.ts';
+export {
+  DEFAULT_LABEL_LIMIT,
+  DEFAULT_SETTINGS,
+  DEFAULT_SIDE_PANEL,
+  DEFAULT_SIDE_PANELS,
+  MAXIMUM_LABEL_LIMIT,
+  createMassState,
+  isMassWindow,
+  mergeMassSettings,
+} from './massState.ts';
+export type { SpectrumSubtitleOptions } from './massSummary.ts';
+export {
+  spectrumFileFields,
+  spectrumMetaRows,
+  spectrumResolutionRows,
+  spectrumSubtitle,
+} from './massSummary.ts';
+export type { MzDecimalsSetting } from './mzDecimalsSetting.ts';
+export {
+  MAXIMUM_MZ_DECIMALS,
+  mzDecimalsFor,
+  readMzDecimalsSetting,
+} from './mzDecimalsSetting.ts';
+export type { NearestPeak } from './nearestPeak.ts';
+export {
+  PEAK_HIT_RADIUS,
+  nearestPeakMz,
+  peakAtMz,
+  sameNearestPeak,
+} from './nearestPeak.ts';
+export type {
+  PeakLabelLine,
+  PeakLabelLineKind,
+  PeakLabelLinesOptions,
+} from './peakLabelLines.ts';
+export { peakKey, peakLabelLines } from './peakLabelLines.ts';
+export type { PeakLabelPlan, PlanPeakLabelsOptions } from './peakLabelPlan.ts';
+export { LABEL_SPACING, planPeakLabels } from './peakLabelPlan.ts';
+export type { PeakTableOptions } from './peakTable.ts';
+export {
+  PEAK_TABLE_LIMIT,
+  PEAK_TABLE_THRESHOLD,
+  peakTableRows,
+  peakTableToTsv,
+} from './peakTable.ts';
+export type { DecideResolutionOptions } from './resolutionOf.ts';
+export {
+  decideResolution,
+  mzDecimalsOf,
+  resolutionOf,
+} from './resolutionOf.ts';
+export { parseScanFilter } from './scanFilter.ts';
+export type {
+  MassTraceKind,
+  TraceIconClick,
+  TraceIconState,
+} from './traceIcon.ts';
+export { nextTraceIconClick, traceIconState } from './traceIcon.ts';
+export {
+  JCAMP_EXTENSION,
+  JCAMP_MIME_TYPE,
+  massSpectraToJcamp,
+  massSpectrumToJcamp,
+} from './spectrumJcamp.ts';
+export type { ToMassSpectrumOptions } from './toMassSpectrum.ts';
+export { toMassSpectra, toMassSpectrum } from './toMassSpectrum.ts';
+export {
+  MAXIMUM_WRITTEN_DECIMALS,
+  writtenDecimals,
+  writtenResolution,
+} from './writtenResolution.ts';

package/src/mass/core/jcampTechnique.ts

@@ -0,0 +1,87 @@
+/**
+ * Which blocks of a JCAMP a mass viewer has any business reading.
+ *
+ * JCAMP-DX is a container for whatever an instrument wanted to export, and the
+ * file says nothing about which viewer opened it: a file of five infrared
+ * spectra, one of UV/VIS ones and a gas-chromatography export writing a whole
+ * chromatogram under `##XUNITS= TIME` are all valid JCAMPs. Read as mass
+ * spectra they draw a wavenumber, a wavelength or a minute on an m/z axis, and
+ * every mass read off them afterwards is a mass of something never measured.
+ *
+ * So the technique the file states is believed, and only a block that states
+ * another one is refused. A block that states none is kept: plenty of
+ * instruments write no `##DATA TYPE` at all, and the file was handed to a mass
+ * viewer, so mass spectrometry is the right assumption where the file is silent.
+ */
+
+import { recordText } from './massMeta.ts';
+
+/** What `jcampconverter` says about one block, as far as this is concerned. */
+export interface JcampBlockHeader {
+  /**
+   * The `##DATA TYPE=` record.
+   * @default undefined
+   */
+  dataType?: string;
+  /** The standard records, where `##XUNITS=` is. */
+  info: Record<string, unknown>;
+}
+
+/**
+ * What a block says it is, when what it says is not mass spectrometry.
+ *
+ * Both halves of the answer are read: the technique names it, and the axis unit
+ * is what a chemist looking at a refusal can check against the file in front of
+ * them — `INFRARED SPECTRUM in 1/CM` is a sentence they can act on where
+ * `unsupported data type` is not.
+ * @param entry - The block, as `jcampconverter` read it.
+ * @returns The phrase naming it, or `null` when the block may be read as a mass
+ * spectrum.
+ */
+export function otherTechnique(entry: JcampBlockHeader): string | null {
+  const dataType = (entry.dataType ?? '').toUpperCase();
+  const units = recordText(entry.info.XUNITS).toUpperCase();
+
+  if (MASS_SPECTROMETRY.test(dataType)) return null;
+  if (OTHER_TECHNIQUE.test(dataType)) {
+    return units === '' ? dataType : `${dataType} in ${units}`;
+  }
+  // A block naming no technique is still refused when it names an axis no mass
+  // spectrum has: `##XUNITS= 1/CM` is a wavenumber whoever wrote the file was
+  // measuring, whatever the header left out.
+  if (OTHER_AXIS.test(units)) {
+    return dataType === '' ? `an axis in ${units}` : `${dataType} in ${units}`;
+  }
+  return null;
+}
+
+/**
+ * The techniques that are a mass spectrum however the file spells them.
+ *
+ * Read before the refusals below, so that `GC-MS` and `LC-MS` — both of which
+ * name a separation this reader would otherwise refuse — are kept: what came
+ * off the column is still measured by mass.
+ */
+const MASS_SPECTROMETRY = /\bMASS\b|\bMS\b/;
+
+/**
+ * The techniques that are certainly not a mass spectrum.
+ *
+ * Named rather than matching `MASS SPECTRUM` positively, so that a file typed
+ * `CONTINUOUS MASS SPECTRUM`, `GC-MS` or nothing at all is read without this
+ * list having to anticipate every spelling an exporter might choose.
+ */
+const OTHER_TECHNIQUE =
+  /\b(?:RAMAN|NMR|INFRARED|FTIR|IR|UV|VIS|VISIBLE|FLUORESCENCE|XRD|EPR|ESR|CHROMATOGRAM|CHROMATOGRAPH)\b/;
+
+/**
+ * The axis units that are certainly not an m/z.
+ *
+ * A wavenumber, a wavelength, a frequency, a chemical shift and a retention
+ * time each name an axis some other instrument sweeps; `ARBITRARY`, `M/Z`,
+ * `MASS UNITS` and `DALTONS` are all left out, since a mass spectrum is written
+ * with every one of them. The unit is looked for as a word inside the record,
+ * because a file that states no technique spells it as `Wavenumber (1/cm)`.
+ */
+const OTHER_AXIS =
+  /\b(?:1\/CM|CM-1|WAVENUMBERS?|NM|NANOMETERS?|MICROMETERS?|MICRONS?|HZ|PPM|SECONDS?|MINUTES?|TIME)\b/;

package/src/mass/core/labelStackBox.ts

@@ -0,0 +1,75 @@
+/**
+ * The room a stack of labels over a peak takes, and the peak a pointer resting
+ * on it reports.
+ *
+ * The numbers of a stack take no pointer event of their own: the room they
+ * occupy does, as one rectangle per stack, so a stack can be interrogated —
+ * resting on it opens whatever a host shows about that peak — without the
+ * glyphs becoming a control or stopping the crosshair underneath.
+ */
+
+import { PEAK_LABEL } from '../../chart/core/chartTheme.ts';
+
+/** A rectangle in the pixels of the SVG. */
+export interface StackBox {
+  /** Its left edge. */
+  x: number;
+  /** Its top edge. */
+  y: number;
+  /** How wide it is. */
+  width: number;
+  /** How tall. */
+  height: number;
+}
+
+/** The peak the pointer is resting on, as the labels report it. */
+export interface HoveredPeak {
+  /** `${spectrumId}:${index}`, which is how anything said about it is found. */
+  key: string;
+  /** The m/z measured for it. */
+  mz: number;
+  /** Its intensity, in the units its spectrum was drawn in. */
+  intensity: number;
+  /** The charge established for it, `0` when none was. */
+  charge: number;
+  /** Where a card about it is anchored, in pixels across the SVG. */
+  x: number;
+  /** The edge of the label stack it hangs off, in pixels down the SVG. */
+  y: number;
+}
+
+/**
+ * The room a stack of labels takes, which is what answers the pointer.
+ *
+ * A baseline is where the glyphs of a line *sit*, so the box starts a line
+ * height above the topmost one and stops just under the lowest. How wide it is
+ * cannot be measured from here — an SVG knows nothing of the host's font until
+ * it is on screen — so it is the width the theme says a label claims, which is
+ * the same number the stacks are spaced by.
+ * @param x - Where the stack is centred, in pixels.
+ * @param baselines - Where each of its lines is written, in any order.
+ * @returns The box, of no size at all when the stack has no lines.
+ */
+export function labelStackBox(
+  x: number,
+  baselines: readonly number[] | Float64Array,
+): StackBox {
+  const { lineHeight, hoverHalfWidth } = PEAK_LABEL;
+  let highest = Number.POSITIVE_INFINITY;
+  let lowest = Number.NEGATIVE_INFINITY;
+  for (const baseline of baselines) {
+    if (baseline < highest) highest = baseline;
+    if (baseline > lowest) lowest = baseline;
+  }
+  if (!Number.isFinite(highest)) return { x, y: 0, width: 0, height: 0 };
+
+  return {
+    x: x - hoverHalfWidth,
+    y: highest - lineHeight,
+    width: hoverHalfWidth * 2,
+    height: lowest - highest + lineHeight + DESCENDER,
+  };
+}
+
+/** How far a glyph reaches below its baseline, near enough for a hit area. */
+const DESCENDER = 3;

package/src/mass/core/labelledPeaks.ts

@@ -0,0 +1,135 @@
+/**
+ * Which peaks of a spectrum are worth writing a label beside.
+ *
+ * A centroid holds tens of thousands of peaks and a chart has room for a dozen
+ * labels, so something has to choose — and the choice is `ms-spectrum`'s slot
+ * mechanism rather than anything invented here. The window is cut into ten
+ * slots, the tallest peak of each is taken, and a peak falling in a slot that is
+ * already spoken for comes back marked `close`. **Dropping the marked ones is
+ * the whole of the selection**; what then still collides on a narrow chart is
+ * settled by `planPeakLabels`, which gives the room to the taller peak.
+ *
+ * The slots are cut from the *window* and not from the spectrum, which is what
+ * makes the choice follow the zoom: a survey scan has room to name its base peak
+ * and a handful of others, and the same spectrum zoomed onto one isotopologue
+ * cluster has room to name every line of it.
+ */
+
+import { xFindClosestIndex } from 'ml-spectra-processing';
+import { getBestPeaks } from 'ms-spectrum';
+
+import type { MassPeakObject } from './centroidPeaks.ts';
+import { centroidPeakObjects } from './centroidPeaks.ts';
+import type { MassSpectrum } from './massSpectrum.ts';
+import { DEFAULT_LABEL_LIMIT } from './massState.ts';
+
+/**
+ * How many slots the window is cut into.
+ *
+ * Ten is `ms-spectrum`'s own default and is kept rather than exposed: it is the
+ * number of labels a chart of any usual width can carry across it without one
+ * sitting on the next.
+ */
+export const LABEL_SLOTS = 10;
+
+/** How faint a peak may be, against the tallest one in the window, and still be labelled. */
+export const LABEL_THRESHOLD = 0.01;
+
+/** One peak that has earned a label, and where it sits in its centroid. */
+export interface LabelledPeak extends MassPeakObject {
+  /** Its index in the centroid, which is how anything else about it is found. */
+  index: number;
+}
+
+/** The window the labels are chosen for, and how many there is room for. */
+export interface SelectLabelledPeaksOptions {
+  /**
+   * Lowest m/z on screen.
+   * @default the m/z of the first peak
+   */
+  from?: number;
+  /**
+   * Highest m/z on screen.
+   * @default the m/z of the last peak
+   */
+  to?: number;
+  /**
+   * The tallest intensity the window shows. A peak above it has its tip off the
+   * top of the plot, so a label placed there would name a stick whose height
+   * cannot be read anyway — and leaving it out is also what puts the threshold
+   * back on the tallest peak that *is* on screen, which is the whole point of
+   * zooming into a baseline.
+   * @default Number.POSITIVE_INFINITY
+   */
+  maxValue?: number;
+  /**
+   * How many peaks are labelled at most, the most intense first.
+   * @default DEFAULT_LABEL_LIMIT
+   */
+  limit?: number;
+  /**
+   * How faint a peak may be against the tallest one in the window.
+   * @default LABEL_THRESHOLD
+   */
+  threshold?: number;
+}
+
+/**
+ * The peaks of a window that have earned a label.
+ *
+ * The peak objects are read off the centroid's cache rather than rebuilt, so a
+ * zoom costs the selection alone and not a fresh object per peak of the
+ * spectrum. What comes back is a copy each time — `getBestPeaks` clones what it
+ * keeps, since it writes its `close` verdict onto the peak — so nothing here can
+ * scribble on the cache every other reader shares.
+ * @param spectrum - The spectrum whose peaks are being labelled.
+ * @param options - The window, and how many labels there is room for.
+ * @returns The chosen peaks, in increasing m/z, with the crowded ones dropped.
+ */
+export function selectLabelledPeaks(
+  spectrum: MassSpectrum,
+  options: SelectLabelledPeaksOptions = {},
+): LabelledPeak[] {
+  const {
+    from,
+    to,
+    maxValue,
+    limit = DEFAULT_LABEL_LIMIT,
+    threshold = LABEL_THRESHOLD,
+  } = options;
+
+  const { centroid } = spectrum;
+  const peaks = centroidPeakObjects(centroid);
+  // `getBestPeaks` reads the window it was given no bounds for off the first and
+  // last peak, which it cannot do when there are none.
+  if (peaks.length === 0 || limit <= 0) return [];
+
+  const best = getBestPeaks(peaks, {
+    from,
+    to,
+    maxValue,
+    limit,
+    threshold,
+    numberSlots: LABEL_SLOTS,
+  }) as SlottedPeak[];
+
+  const labelled: LabelledPeak[] = [];
+  for (const peak of best) {
+    // A peak the slots called close stands within a slot of one already
+    // labelled, so labelling it too writes one label over the other.
+    if (peak.close) continue;
+    labelled.push({
+      x: peak.x,
+      y: peak.y,
+      charge: peak.charge,
+      index: xFindClosestIndex(centroid.x, peak.x),
+    });
+  }
+  return labelled;
+}
+
+/** A peak as the slots hand it back: itself, and whether it is crowded. */
+interface SlottedPeak extends MassPeakObject {
+  /** Whether another kept peak stands within one slot of it. */
+  close: boolean;
+}

package/src/mass/core/loadMassSpectra.ts

@@ -0,0 +1,86 @@
+/**
+ * One entry point for whatever was dropped, opened or pasted.
+ *
+ * The format is decided from the bytes and the right reader is called, so a
+ * caller hands over a file and gets spectra back without knowing what it turned
+ * out to be. Each reader is imported only once the bytes turn out to need it, so
+ * a page that never opens a JCAMP never downloads its converter.
+ */
+
+import { describeSource } from '../../error/core/index.ts';
+
+import { detectMassFormat } from './detectMassFormat.ts';
+import type { LoadedMassSpectrum } from './loadedMassSpectrum.ts';
+
+/**
+ * How many spectra one file is read for at most.
+ *
+ * A JCAMP of a GC/MS run writes a page per scan, thousands of them, and a list
+ * of thousands of rows is a list nobody can find anything in. A hundred keeps
+ * every file somebody exported deliberately and stops a whole run at its start,
+ * where saying so is better than hanging the page.
+ */
+export const DEFAULT_MAX_SPECTRA = 100;
+
+/** How a file is read. */
+export interface LoadMassSpectraOptions {
+  /**
+   * The file's name, which decides the reader when the content is silent and is
+   * carried onto every spectrum read out of it.
+   * @default undefined
+   */
+  fileName?: string;
+  /**
+   * At most how many spectra are read out of the file.
+   * @default DEFAULT_MAX_SPECTRA
+   */
+  maxSpectra?: number;
+}
+
+/** What a file turned out to hold. */
+export interface LoadMassSpectraResult {
+  /** The spectra it held, in the order the file wrote them. */
+  spectra: LoadedMassSpectrum[];
+  /** What it turned out to be. */
+  format: 'jcamp' | 'text';
+  /**
+   * How many spectra `maxSpectra` left unread, `0` when none. Reported rather
+   * than passed over in silence: a run truncated without a word looks exactly
+   * like a run that only held a hundred scans.
+   */
+  dropped: number;
+}
+
+/**
+ * Read every mass spectrum a file holds.
+ * @param data - The file, as bytes, or the pasted text.
+ * @param options - The file's name, and how many spectra to read at most.
+ * @returns The spectra, the format they were read from and how many were left
+ * unread.
+ * @throws {Error} When nothing in the file names a format this can read, or when
+ * the reader for that format gave up on it — always with a sentence naming the
+ * file.
+ */
+export async function loadMassSpectra(
+  data: Uint8Array | ArrayBuffer | string,
+  options: LoadMassSpectraOptions = {},
+): Promise<LoadMassSpectraResult> {
+  const { fileName, maxSpectra = DEFAULT_MAX_SPECTRA } = options;
+  const content = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
+  const format = detectMassFormat(content, fileName);
+  const named = fileName === undefined ? {} : { fileName };
+
+  if (format === 'jcamp') {
+    const { fromJcamp } = await import('./fromJcamp.ts');
+    return { ...fromJcamp(content, { ...named, maxSpectra }), format };
+  }
+
+  if (format === 'text') {
+    const { fromText } = await import('./fromText.ts');
+    return { spectra: fromText(content, named), format, dropped: 0 };
+  }
+
+  throw new Error(
+    `${describeSource(fileName)} is not a spectrum this viewer can read — JCAMP-DX files (.jdx, .dx) and two columns of m/z and intensity (.txt, .csv, .xy) are understood.`,
+  );
+}

package/src/mass/core/loadedMassSpectrum.ts

@@ -0,0 +1,43 @@
+/**
+ * What a reader hands back, before the peaks are picked.
+ *
+ * A JCAMP holds a title and twenty instrument records, a pasted peak table two
+ * columns and nothing else — and both end up here, so `toMassSpectrum` has one
+ * shape to turn into a `MassSpectrum`. A reader does not pick peaks, choose a
+ * colour or mint an identity, because those are decisions about the session
+ * rather than about the file.
+ *
+ * One spectrum is one acquisition. A file holding twelve gives twelve and never
+ * a merged one — an averaged spectrum is something the chemist asks for, not
+ * something a reader quietly does on the way in.
+ */
+
+import type { MassMeta, MassOrigin, MassTrace } from './massSpectrum.ts';
+
+/** One acquisition, as the file gave it up. */
+export interface LoadedMassSpectrum {
+  /**
+   * The points, m/z ascending, the intensities as the file wrote them — counts
+   * on one instrument and relative abundance on the next. They are put on one
+   * scale when the peaks are picked.
+   */
+  trace: MassTrace;
+  /** What the file said about the acquisition, `null` when it said nothing. */
+  meta: MassMeta | null;
+  /** Where it came from. */
+  origin: MassOrigin;
+  /**
+   * What the file calls it, absent when the file names nothing, so the caller
+   * can fall back to the file name without having to recognise a placeholder
+   * it invented itself.
+   * @default undefined
+   */
+  name?: string;
+  /**
+   * Whether the file said outright that this is a continuous profile rather
+   * than a peak table, absent when it did not — which is what the spacing of
+   * the points is then asked.
+   * @default undefined
+   */
+  continuous?: boolean;
+}