react-cheminfo 0.69.0 → 0.71.0

package/src/mass/core/massMeta.ts

@@ -0,0 +1,239 @@
+/**
+ * What the file says about how the spectrum was acquired, made displayable.
+ *
+ * A JCAMP written by a Thermo instrument carries the answer to every question a
+ * chemist asks of a spectrum — which analyser, which polarity, which collision
+ * energy — but carries it in whichever of two record bags the exporting
+ * software felt like using, and leaves half of them blank. A JCAMP of the older
+ * MS dialect states the same facts under standard records of its own,
+ * `##.SPECTROMETER TYPE=` and `##.IONIZATION MODE=`. So each field names the
+ * records it may live in, in the order they are worth trying, and anything
+ * still blank falls back to the instrument's own scan description.
+ *
+ * A field that is absent or empty is left out entirely rather than shown as a
+ * dash, which is what keeps the table short enough to read at a glance: every
+ * line in it is a fact the file actually stated.
+ */
+
+import type { MassMeta, MassMetaField } from './massSpectrum.ts';
+import { parseScanFilter } from './scanFilter.ts';
+
+/**
+ * The two record bags a JCAMP reader offers.
+ *
+ * `jcampconverter` splits the records in two — `##ORIGIN=` and the other
+ * standard labels into `info`, keyed without their spaces, and the
+ * `$`-prefixed user-defined ones into `meta` with the `$` stripped — and a
+ * record belongs to one bag or the other, never both.
+ */
+export interface MassMetaSource {
+  /**
+   * The standard records, keyed without their `##` and without spaces.
+   * @default undefined
+   */
+  info?: Record<string, unknown>;
+  /**
+   * The `$`-prefixed user-defined records, keyed without their `##$`.
+   * @default undefined
+   */
+  meta?: Record<string, unknown>;
+  /**
+   * The title, when the reader kept it apart from the records.
+   * @default undefined
+   */
+  title?: string;
+}
+
+/** One record a row of the table can be read from, and written back to. */
+export interface MassMetaRecord {
+  /** The record's label as the reader keys it, without its `##` or its `$`. */
+  key: string;
+  /** Whether it is a standard record rather than a `$`-prefixed one. */
+  info: boolean;
+}
+
+/**
+ * Read the acquisition metadata a file carries.
+ *
+ * Returns `null` rather than an empty table when the file said nothing at all,
+ * so the panel can leave the section out instead of drawing a heading over
+ * nothing — the normal outcome for a pasted peak list.
+ * @param source - The record bags the reader recovered.
+ * @returns The metadata, or `null` when the file carries none.
+ */
+export function buildMassMeta(source: MassMetaSource): MassMeta | null {
+  const bags: Bags = { info: source.info ?? {}, meta: source.meta ?? {} };
+  const conditions = recordText(bags.meta.CONDITIONS);
+  const derived = parseScanFilter(conditions);
+
+  const fields: MassMetaField[] = [];
+  for (const field of FIELDS) {
+    const value =
+      firstValue(bags, field.records) || (derived[field.label] ?? '');
+    if (value) fields.push({ label: field.label, value });
+  }
+
+  const title = recordText(source.title) || recordText(bags.info.TITLE) || null;
+  const molecularFormula = firstValue(bags, MOLECULAR_FORMULA_RECORDS) || null;
+  if (fields.length === 0 && !title && !conditions && !molecularFormula) {
+    return null;
+  }
+  return { title, molecularFormula, fields, conditions: conditions || null };
+}
+
+/**
+ * The record a row of the table is written back to.
+ *
+ * The inverse of the table below, and it lives beside it for that reason: a
+ * writer holding a second list of record names is a writer whose `MSLEVEL`
+ * becomes `MS_LEVEL` the day a spelling is added here, and the round trip then
+ * loses the field without anything going wrong loudly. Only the first of each
+ * row's records is offered — the others exist to read what other exporters
+ * wrote, and writing our own file is not the place to imitate them.
+ * @param label - The row's label, as the table displays it.
+ * @returns The record, or `null` when the label is not one of the table's rows.
+ */
+export function metaRecord(label: string): MassMetaRecord | null {
+  for (const field of FIELDS) {
+    if (field.label === label) return field.records[0] ?? null;
+  }
+  return null;
+}
+
+/** Both bags, as the reader handed them over. */
+interface Bags {
+  /** The standard records. */
+  info: Record<string, unknown>;
+  /** The `$`-prefixed ones. */
+  meta: Record<string, unknown>;
+}
+
+/** One row of the table: how it is named, and where its value may live. */
+interface FieldSpec {
+  /** The label, which is also the key `parseScanFilter` derives it under. */
+  label: string;
+  /** The records to try, in the order they are worth trying. */
+  records: readonly MassMetaRecord[];
+}
+
+/**
+ * A standard record.
+ * @param key - Its label without spaces.
+ * @returns The record.
+ */
+function standard(key: string): MassMetaRecord {
+  return { key, info: true };
+}
+
+/**
+ * A `$`-prefixed record.
+ * @param key - Its label without the `$`.
+ * @returns The record.
+ */
+function custom(key: string): MassMetaRecord {
+  return { key, info: false };
+}
+
+/**
+ * Every row the table can show, in the order it shows them.
+ *
+ * The order runs from what the sample was measured on down to who measured it,
+ * because that is the order a chemist reads a method in. The alternatives on
+ * each row are the records real exporters were observed to write: `IONISATION`
+ * and `IONIZATION` are the same field spelled by two vendors.
+ *
+ * `EXPERIMENT` is deliberately not a fallback for the collision energy, however
+ * tempting the name is: on real Orbitrap exports it holds what kind of run this
+ * was — `MS/MS`, `Accurate mass` — while the energy is in `REPORT` or in the
+ * instrument's own scan filter.
+ */
+const FIELDS: readonly FieldSpec[] = [
+  { label: 'Source', records: [standard('ORIGIN')] },
+  {
+    label: 'Instrument',
+    records: [custom('INSTRUMENT'), standard('SPECTROMETER/DATASYSTEM')],
+  },
+  {
+    label: 'Analyser',
+    records: [
+      custom('ANALYZER'),
+      custom('ANALYSER'),
+      standard('.SPECTROMETERTYPE'),
+    ],
+  },
+  {
+    label: 'Instrument parameters',
+    records: [standard('.INSTRUMENTPARAMETERS')],
+  },
+  {
+    label: 'Ionization',
+    records: [
+      custom('IONISATION'),
+      custom('IONIZATION'),
+      standard('.IONIZATIONMODE'),
+    ],
+  },
+  { label: 'Inlet', records: [custom('INJECTION'), standard('.INLET')] },
+  { label: 'Polarity', records: [custom('MODE'), custom('POLARITY')] },
+  { label: 'Experiment', records: [custom('EXPERIMENT')] },
+  { label: 'MS level', records: [custom('MSLEVEL')] },
+  { label: 'Isolation m/z', records: [custom('ISOLATION')] },
+  {
+    label: 'Collision energy',
+    records: [custom('COLLISIONENERGY'), custom('REPORT')],
+  },
+  { label: 'Scan range', records: [custom('SCANRANGE')] },
+  { label: 'Retention time', records: [custom('RETENTIONTIME')] },
+  { label: 'Scans', records: [custom('SCANS')] },
+  { label: 'Averaged scans', records: [custom('AVERAGEDSCANS')] },
+  { label: 'Raw file', records: [custom('RAWFILE')] },
+  {
+    label: 'Operator',
+    records: [custom('USER'), custom('OWNER'), standard('OWNER')],
+  },
+  { label: 'Note', records: [custom('NOTE')] },
+];
+
+/**
+ * Where the formula the file was measured for may be stated: the standard
+ * record first, then the one an accurate-mass tool writes its answer into.
+ */
+const MOLECULAR_FORMULA_RECORDS: readonly MassMetaRecord[] = [
+  standard('MOLFORM'),
+  standard('MOLFORMULA'),
+  custom('ACCURATE_MF'),
+];
+
+/**
+ * The first record that holds anything.
+ * @param bags - The records to look in.
+ * @param records - The records to try, in order.
+ * @returns The value as the file states it, or `''` when none is populated.
+ */
+function firstValue(bags: Bags, records: readonly MassMetaRecord[]): string {
+  for (const record of records) {
+    const value = recordText((record.info ? bags.info : bags.meta)[record.key]);
+    if (value) return value;
+  }
+  return '';
+}
+
+/**
+ * A record's value as a trimmed string, whatever dynamic typing made of it.
+ *
+ * `jcampconverter` reads `##$SCANS=1` as the number `1` and a record written
+ * twice as an array of both values, so a row that is only ever shown has to
+ * accept all three shapes. A repeated record shows its first occurrence, which
+ * is the one the exporter wrote for the acquisition rather than for a later
+ * reprocessing of it.
+ * @param value - The record, as dynamic typing left it.
+ * @returns The value as text, `''` when there is none.
+ */
+export function recordText(value: unknown): string {
+  if (typeof value === 'string') return value.trim();
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  if (Array.isArray(value)) return recordText(value[0]);
+  return '';
+}

package/src/mass/core/massReducer.ts

@@ -0,0 +1,232 @@
+/**
+ * Every change the viewer can undergo, as one function over one object.
+ *
+ * A reducer rather than a graph of signals: a published component must not
+ * impose a state library on the page that mounts it, and two viewers on one
+ * page must not share a module-level singleton. The state is a plain object, so
+ * a host can save it, restore it and compare it.
+ *
+ * Every case returns the state **itself** when it has nothing to do, so a render
+ * memoised on the state is not defeated by an action that changed nothing —
+ * selecting the spectrum already selected, closing an error already closed.
+ */
+
+import type { MassPanelId } from './massSidePanels.ts';
+import type { MassDomain, MassSpectrum } from './massSpectrum.ts';
+import type {
+  MassSettings,
+  MassState,
+  MassTool,
+  PartialMassState,
+} from './massState.ts';
+import { isMassWindow, mergeMassSettings } from './massState.ts';
+import {
+  arriving,
+  mapSpectrum,
+  restoreState,
+  withError,
+} from './massStateEdits.ts';
+
+/**
+ * Which of a spectrum's two traces are drawn. Both are named every time,
+ * because they are an either/or: drawing one is also the gesture that puts the
+ * other away.
+ */
+export interface SpectrumVisibility {
+  /** Whether the continuous trace is drawn. */
+  showProfile: boolean;
+  /** Whether the centroid sticks are drawn. */
+  showCentroid: boolean;
+}
+
+/** Everything that can be asked of the viewer. */
+export type MassAction =
+  | { type: 'addSpectra'; spectra: MassSpectrum[] }
+  | { type: 'setSpectra'; spectra: MassSpectrum[] }
+  | { type: 'removeSpectrum'; id: string }
+  | { type: 'renameSpectrum'; id: string; name: string }
+  | { type: 'setSpectrumColor'; id: string; color: string }
+  | {
+      type: 'setSpectrumVisibility';
+      id: string;
+      visibility: SpectrumVisibility;
+    }
+  | { type: 'selectSpectrum'; id: string | null }
+  | { type: 'setDomain'; domain: MassDomain }
+  | { type: 'resetDomain' }
+  | { type: 'setTool'; tool: MassTool }
+  | { type: 'togglePanel'; panelId: MassPanelId }
+  | { type: 'setError'; error: string | null }
+  | { type: 'setSettings'; settings: Partial<MassSettings> }
+  | { type: 'loadState'; state: PartialMassState }
+  | { type: 'clear' };
+
+/**
+ * Fold one action into the state.
+ * @param state - The state in force.
+ * @param action - What is being asked.
+ * @returns The new state, or the old one when nothing changed.
+ */
+export function massReducer(state: MassState, action: MassAction): MassState {
+  switch (action.type) {
+    case 'addSpectra': {
+      const added = arriving(state, action.spectra);
+      if (added.length === 0) return state;
+      return {
+        ...state,
+        data: { spectra: [...state.data.spectra, ...added] },
+        view: {
+          ...state.view,
+          // Whatever arrived is what somebody wants to look at, so it takes the
+          // selection — but only when nothing was selected, since a spectrum
+          // added for comparison must not steal the panels from the one being
+          // read.
+          selectedId: state.view.selectedId ?? added[0]?.id ?? null,
+          error: null,
+        },
+      };
+    }
+
+    case 'setSpectra': {
+      const spectra = arriving(
+        { ...state, data: { spectra: [] } },
+        action.spectra,
+      );
+      return {
+        ...state,
+        data: { spectra },
+        view: {
+          ...state.view,
+          selectedId: spectra[0]?.id ?? null,
+          // Replacing what is drawn is the one change that throws the window
+          // away: a window over one spectrum's masses means nothing over
+          // another's, and the chart refits when it is handed `null`.
+          domain: null,
+          error: null,
+        },
+      };
+    }
+
+    case 'removeSpectrum': {
+      const spectra = state.data.spectra.filter(
+        (spectrum) => spectrum.id !== action.id,
+      );
+      if (spectra.length === state.data.spectra.length) return state;
+      return {
+        ...state,
+        data: { spectra },
+        view: {
+          ...state.view,
+          selectedId:
+            state.view.selectedId === action.id
+              ? (spectra[0]?.id ?? null)
+              : state.view.selectedId,
+        },
+      };
+    }
+
+    case 'renameSpectrum': {
+      const name = action.name.trim();
+      if (name === '') {
+        return withError(state, 'A spectrum needs a name to be called by.');
+      }
+      return mapSpectrum(state, action.id, (spectrum) =>
+        spectrum.name === name ? spectrum : { ...spectrum, name },
+      );
+    }
+
+    case 'setSpectrumColor': {
+      return mapSpectrum(state, action.id, (spectrum) =>
+        spectrum.color === action.color
+          ? spectrum
+          : { ...spectrum, color: action.color },
+      );
+    }
+
+    case 'setSpectrumVisibility': {
+      return mapSpectrum(state, action.id, (spectrum) => {
+        // A spectrum read from a peak table has no profile to draw, and asking
+        // for one must not leave it drawn as nothing at all.
+        const showProfile =
+          action.visibility.showProfile && spectrum.profile !== null;
+        const { showCentroid } = action.visibility;
+        return spectrum.showProfile === showProfile &&
+          spectrum.showCentroid === showCentroid
+          ? spectrum
+          : { ...spectrum, showProfile, showCentroid };
+      });
+    }
+
+    case 'selectSpectrum': {
+      if (state.view.selectedId === action.id) return state;
+      return { ...state, view: { ...state.view, selectedId: action.id } };
+    }
+
+    case 'setDomain': {
+      if (!isMassWindow(action.domain)) return state;
+      return { ...state, view: { ...state.view, domain: action.domain } };
+    }
+
+    case 'resetDomain': {
+      if (state.view.domain === null) return state;
+      return { ...state, view: { ...state.view, domain: null } };
+    }
+
+    case 'setTool': {
+      if (state.view.tool === action.tool) return state;
+      return { ...state, view: { ...state.view, tool: action.tool } };
+    }
+
+    case 'togglePanel': {
+      const { openPanelIds } = state.view;
+      const open = openPanelIds.includes(action.panelId);
+      return {
+        ...state,
+        view: {
+          ...state.view,
+          openPanelIds: open
+            ? openPanelIds.filter((id) => id !== action.panelId)
+            : [...openPanelIds, action.panelId],
+        },
+      };
+    }
+
+    case 'setError': {
+      if (state.view.error === action.error) return state;
+      return { ...state, view: { ...state.view, error: action.error } };
+    }
+
+    case 'setSettings': {
+      const settings = mergeMassSettings(state.settings, action.settings);
+      const { showLabels, labelLimit, showCharges, mzDecimals } =
+        state.settings;
+      if (
+        settings.showLabels === showLabels &&
+        settings.labelLimit === labelLimit &&
+        settings.showCharges === showCharges &&
+        settings.mzDecimals === mzDecimals
+      ) {
+        return state;
+      }
+      return { ...state, settings };
+    }
+
+    case 'loadState': {
+      return restoreState(state, action.state);
+    }
+
+    case 'clear': {
+      if (state.data.spectra.length === 0 && state.view.error === null) {
+        return state;
+      }
+      return {
+        ...state,
+        data: { spectra: [] },
+        view: { ...state.view, selectedId: null, domain: null, error: null },
+      };
+    }
+    /* Every action is handled above, and TypeScript is what keeps that true
+       when one is added — so there is nothing for a fallback to do. */
+    // no default
+  }
+}

package/src/mass/core/massResolution.ts

@@ -0,0 +1,169 @@
+/**
+ * Whether a spectrum resolves masses finely enough for their decimals to mean
+ * anything.
+ *
+ * A peak table typed out of a low-resolution instrument report holds whole
+ * numbers — `163`, `325`, `487` — and writing them as `163.0000` claims four
+ * digits of accuracy nobody measured. A high-resolution measurement is the
+ * opposite case: `325.1129` and `325.1503` are different ions, and rounding them
+ * together loses the whole point of having measured them. Nothing about a single
+ * number says which of the two it is, so the answer is read off the spectrum.
+ *
+ * Three kinds of evidence are read, and the strongest one present decides —
+ * `decideResolution` is where they are weighed:
+ *
+ * 1. **The peaks themselves.** A profile carries the width of every peak, and
+ *    the resolving power `m / Δm` at half height is what "high resolution" is
+ *    defined by. This is a measurement, so it is believed over anything a file
+ *    says about itself.
+ * 2. **What the file says the instrument was.** A Thermo scan filter starting
+ *    `FTMS` is an Orbitrap, one starting `ITMS` an ion trap, and a JCAMP of the
+ *    old MS dialect writes `##.INSTRUMENT PARAMETERS= LOW RESOLUTION` outright.
+ * 3. **How many decimals the masses were written with**, which is all a bare
+ *    peak table has to say — `writtenResolution.ts`.
+ */
+
+import { gaussianWidthToFWHM } from 'ml-peak-shape-generator';
+import { xMedian } from 'ml-spectra-processing';
+
+import type { MassMeta } from './massSpectrum.ts';
+
+/** How finely a spectrum resolves masses. */
+export type MassResolutionKind = 'high' | 'low' | 'nominal';
+
+/** Which evidence the verdict was read from, the strongest first. */
+export type MassResolutionBasis = 'peakWidth' | 'instrument' | 'decimals';
+
+/** The verdict on one spectrum, and what it rests on. */
+export interface MassResolution {
+  /** Whether the masses are resolved, resolved coarsely, or written whole. */
+  kind: MassResolutionKind;
+  /**
+   * The resolving power `m / Δm` at half height, the median over the tallest
+   * peaks — `null` unless it was measured, which needs a profile.
+   */
+  resolvingPower: number | null;
+  /** What the verdict was read from. */
+  basis: MassResolutionBasis;
+  /** How many decimals an m/z of this spectrum is written with. */
+  decimals: number;
+}
+
+/** A picked peak with the width the peak picking measured for it. */
+export interface WidthPeak {
+  /** Where it sits, in m/z. */
+  x: number;
+  /** How tall it is. */
+  y: number;
+  /** Its width between inflection points, in m/z, as `ml-gsd` reports it. */
+  width: number;
+}
+
+/**
+ * The resolving power from which a spectrum counts as high resolution.
+ *
+ * Ten thousand at half height is the conventional threshold, and it falls in
+ * the gap between the two families of instrument rather than inside either:
+ * quadrupoles, ion traps and linear time-of-flights work at a few thousand at
+ * most, while reflectron time-of-flights, Orbitraps and FT-ICRs start above it.
+ */
+export const HIGH_RESOLVING_POWER = 10_000;
+
+/** How many of the tallest peaks the resolving power is the median of. */
+export const MEASURED_PEAKS = 20;
+
+/** How many decimals an m/z is written with, for each kind of spectrum. */
+export const MZ_DECIMALS: Readonly<Record<MassResolutionKind, number>> = {
+  high: 4,
+  low: 1,
+  nominal: 0,
+};
+
+/**
+ * The resolving power measured on the peaks of a profile.
+ *
+ * The median over the tallest peaks rather than over all of them, because a
+ * peak a few counts above the noise has a width the noise decided, and rather
+ * than the base peak alone, because one peak sitting on an unresolved shoulder
+ * would decide the whole spectrum. The width `ml-gsd` reports is the distance
+ * between the inflection points, which is converted to the width at half height
+ * as a gaussian's is: what a resolving power is quoted against.
+ * @param peaks - The peaks the profile was picked into, each with its width.
+ * @returns The verdict, `null` when no peak carries a usable width.
+ */
+export function measuredResolution(
+  peaks: readonly WidthPeak[],
+): MassResolution | null {
+  const usable: WidthPeak[] = [];
+  for (const peak of peaks) {
+    if (peak.x > 0 && peak.width > 0 && Number.isFinite(peak.width)) {
+      usable.push(peak);
+    }
+  }
+  if (usable.length === 0) return null;
+
+  const tallest = usable
+    .toSorted((first, second) => second.y - first.y)
+    .slice(0, MEASURED_PEAKS);
+  const powers = new Float64Array(tallest.length);
+  for (let index = 0; index < tallest.length; index++) {
+    const peak = tallest[index] as WidthPeak;
+    powers[index] = peak.x / gaussianWidthToFWHM(peak.width);
+  }
+  const resolvingPower = xMedian(powers);
+  const kind = resolvingPower >= HIGH_RESOLVING_POWER ? 'high' : 'low';
+  return {
+    kind,
+    resolvingPower,
+    basis: 'peakWidth',
+    decimals: MZ_DECIMALS[kind],
+  };
+}
+
+/**
+ * The resolution the file says the instrument worked at, when it says so.
+ *
+ * Only the rows that name an instrument are read, and a high verdict is looked
+ * for first: an `LTQ-Orbitrap` names an ion trap and an Orbitrap, and the
+ * spectrum came out of the Orbitrap. A time-of-flight is deliberately left
+ * undecided — a reflectron one is high resolution and a linear one is not, and
+ * the name is the same.
+ * @param meta - What the file said about the acquisition.
+ * @returns The verdict, `null` when the file names no instrument it can be
+ * read off.
+ */
+export function statedResolution(meta: MassMeta | null): MassResolution | null {
+  if (meta === null) return null;
+  for (const field of meta.fields) {
+    if (!INSTRUMENT_FIELDS.has(field.label)) continue;
+    const kind = HIGH_INSTRUMENT.test(field.value)
+      ? 'high'
+      : LOW_INSTRUMENT.test(field.value)
+        ? 'low'
+        : null;
+    if (kind !== null) {
+      return {
+        kind,
+        resolvingPower: null,
+        basis: 'instrument',
+        decimals: MZ_DECIMALS[kind],
+      };
+    }
+  }
+  return null;
+}
+
+/** The acquisition rows that name the instrument, and so its resolution. */
+const INSTRUMENT_FIELDS = new Set([
+  'Analyser',
+  'Instrument',
+  'Instrument parameters',
+]);
+
+/** The instruments, and the words, that say high resolution. */
+const HIGH_INSTRUMENT =
+  /\bHIGH[\s-]RESOLUTION\b|\bHRMS\b|\bFTMS\b|ORBITRAP|\bFT-?ICR\b|\bEXACTIVE\b|\bEXPLORIS\b/i;
+
+/** The instruments, and the words, that say a unit-resolution measurement. */
+const LOW_INSTRUMENT =
+  /\bLOW[\s-]RESOLUTION\b|\bITMS\b|\bION[\s-]TRAP\b|\bTRAP\b|QUADRUPOLE/i;

package/src/mass/core/massSidePanels.ts

@@ -0,0 +1,27 @@
+import type { ActivityBarItemProps } from 'react-science/ui';
+
+/**
+ * The panels the side of the viewer can hold, in the order their icons stack.
+ *
+ * One frozen list read by both the activity bar and the panel stack, so a panel
+ * switched off and on again comes back where it was rather than at the end.
+ */
+export const massSidePanels = [
+  { id: 'spectra', title: 'Spectra', icon: 'timeline-line-chart' },
+  { id: 'peaks', title: 'Peaks', icon: 'th-list' },
+  { id: 'metadata', title: 'Acquisition', icon: 'properties' },
+] as const satisfies ReadonlyArray<{
+  id: string;
+  title: string;
+  icon: ActivityBarItemProps['icon'];
+}>;
+
+/** Identity of one of the panels the viewer offers of its own. */
+export type MassSidePanelId = (typeof massSidePanels)[number]['id'];
+
+/**
+ * Identity of any panel the side can hold: one of the viewer's own, or one a
+ * host added to them. Still a union with the viewer's own ids, so those keep
+ * autocompleting where a plain `string` would swallow them.
+ */
+export type MassPanelId = MassSidePanelId | (string & Record<never, never>);