react-cheminfo 0.69.0 → 0.71.0

package/src/mass/core/massSpectrum.ts

@@ -0,0 +1,220 @@
+/**
+ * What a mass spectrum is once it has been read, whatever it was read from.
+ *
+ * A file gives one or more acquisitions; each becomes one `MassSpectrum` with
+ * two traces of the same measurement — the continuous `profile` as the
+ * instrument recorded it, and the `centroid` the peak picking reduced it to.
+ * Both are kept because they answer different questions: the profile is what a
+ * chemist recognises as a spectrum, and the centroid is what every number
+ * downstream is computed from. A centroided file has no profile, and that is
+ * the normal case for a peak table pasted out of an instrument report.
+ *
+ * The arrays are `Float64Array` throughout and are never converted to
+ * `number[]`: a profile scan runs to hundreds of thousands of points, a plain
+ * array costs two to three times the memory, and any structural freeze or
+ * spread walks it element by element while treating a typed array as atomic.
+ * They are replaced on a change, never written into, since every consumer holds
+ * the same object by reference.
+ *
+ * The shape is the one the glycan site's mass viewer holds, field for field
+ * where the two overlap, so a spectrum that viewer built can be handed to
+ * anything here: whatever it carries beyond these fields is simply not read.
+ */
+
+import type { DataXY } from 'cheminfo-types';
+
+import type { ChartDomain } from '../../chart/core/chartDomain.ts';
+
+import type { MassResolution } from './massResolution.ts';
+
+/**
+ * One trace of a measurement: m/z against intensity, x strictly increasing.
+ *
+ * `DataXY` is the shape every package in this pipeline speaks — `xy-parser`,
+ * `ms-spectrum` and `ml-spectra-processing` all take and return it — so
+ * declaring a parallel type of our own would buy nothing and cost an adapter at
+ * each boundary.
+ */
+export type MassTrace = DataXY<Float64Array>;
+
+/**
+ * The picked peaks of a spectrum, with the charge of each.
+ *
+ * `charge` is a dense column rather than an array of optional numbers so it
+ * costs two bytes a peak and needs no per-peak object: `0` means no charge was
+ * established, which is an answer rather than a missing value — a peak belongs
+ * to no isotopologue cluster and to no charge ladder. A charge is never read
+ * off a single peak, only off the series it belongs to.
+ */
+export interface MassPeaks extends MassTrace {
+  /** Charge of each peak, `0` where none was established. Signed. */
+  charge: Int16Array;
+}
+
+/**
+ * The formats a spectrum can have been read from.
+ *
+ * The two this package reads, and `calculated` for a trace nobody measured. Any
+ * other name is accepted as well, because a host that read an mzML with a
+ * reader of its own hands the spectrum over still knowing what it was read
+ * from, and the acquisition table should say so rather than call it text.
+ */
+export type MassFormat =
+  'jcamp' | 'text' | 'calculated' | (string & Record<never, never>);
+
+/**
+ * Where a spectrum came from, and what the file said about the acquisition.
+ *
+ * Kept apart from `meta` because these are the facts other code branches on —
+ * a calculated trace is never reduced for drawing, an MS2 scan carries a
+ * precursor worth showing beside its name — while `meta` is a table to read.
+ * The readers of this package leave the acquisition facts out; a host whose
+ * reader states them, an mzML's, hands them over here.
+ */
+export interface MassOrigin {
+  /** The format it was read from. */
+  format: MassFormat;
+  /**
+   * Name of the file it came from, absent for a paste.
+   * @default undefined
+   */
+  fileName?: string;
+  /**
+   * Which acquisition of that file, counted from zero — the block of a JCAMP,
+   * or the page of a GC/MS one — absent when the file held only one.
+   * @default undefined
+   */
+  scanIndex?: number;
+  /**
+   * MS level: 1 for a survey scan, 2 for a fragmentation scan.
+   * @default undefined
+   */
+  msLevel?: number;
+  /**
+   * Polarity the scan was acquired in.
+   * @default undefined
+   */
+  polarity?: 'positive' | 'negative';
+  /**
+   * The m/z that was isolated and fragmented, on an MS2 scan.
+   * @default undefined
+   */
+  precursorMz?: number;
+  /**
+   * The monoisotopic m/z the instrument named for that precursor, where it
+   * named one.
+   *
+   * Carried beside the precursor rather than instead of it because the two are
+   * the same number on nearly every scan that has both, and a different one on
+   * a scan whose method offset its isolation window: the precursor is then the
+   * centre of the window, since that is what the quadrupole transmitted, and
+   * this is the molecule the method was after.
+   * @default undefined
+   */
+  precursorMonoisotopicMz?: number;
+  /**
+   * Retention time in minutes, on a scan out of a chromatographic run.
+   * @default undefined
+   */
+  retentionTime?: number;
+}
+
+/** One row of the acquisition table. */
+export interface MassMetaField {
+  /** How the row is named, in the display order the table fixes. */
+  label: string;
+  /** The value as the file states it. */
+  value: string;
+}
+
+/**
+ * What the file says about how the spectrum was acquired.
+ *
+ * Only ever what it actually says: a field the file leaves blank is left out
+ * rather than shown empty, so the table is short and every line in it is a
+ * fact. A plain two-column paste carries none of this, which is most pastes,
+ * and the panel then shows the file name alone.
+ */
+export interface MassMeta {
+  /** The title record, `null` when the file carries none. */
+  title: string | null;
+  /** The molecular formula the file claims, `null` when it claims none. */
+  molecularFormula: string | null;
+  /** The fields that are populated, in display order. */
+  fields: MassMetaField[];
+  /**
+   * The instrument's own scan description, kept verbatim. Real instruments
+   * leave the structured records empty and put the answer only here, so it is
+   * both the fallback the fields are mined from and worth showing as written.
+   */
+  conditions: string | null;
+}
+
+/** One spectrum as the viewer holds it. */
+export interface MassSpectrum {
+  /** Identity, stable across edits so a selection survives a rename. */
+  id: string;
+  /** What the list calls it; editable, and never used as identity. */
+  name: string;
+  /** The colour both its traces are drawn in. */
+  color: string;
+  /** The continuous trace, `null` when the file was already centroided. */
+  profile: MassTrace | null;
+  /** The picked peaks, which every number downstream is computed from. */
+  centroid: MassPeaks;
+  /** What the file said about the acquisition, `null` when it said nothing. */
+  meta: MassMeta | null;
+  /** Where it came from. */
+  origin: MassOrigin;
+  /**
+   * Whether the profile is drawn. The viewer draws one trace or the other and
+   * never both; `isSpectrumDrawn` is the question to ask about the pair.
+   */
+  showProfile: boolean;
+  /** Whether the centroid sticks are drawn, under the same rule. */
+  showCentroid: boolean;
+  /**
+   * Whether the trace is left out of the automatic domain. A predicted
+   * distribution previewed under the pointer must not move the axes, or hovering
+   * a candidate would throw away the zoom the user set.
+   * @default false
+   */
+  excludeFromDomain?: boolean;
+  /**
+   * How finely the spectrum resolves masses, as it was decided when it was read.
+   *
+   * Left out by a host that built the spectrum itself, and then worked out from
+   * the masses as written — see `resolutionOf`.
+   * @default undefined
+   */
+  resolution?: MassResolution;
+}
+
+/**
+ * The window the chart is showing, in data units.
+ *
+ * `ChartDomain` itself, not a type of our own: the arithmetic that moves a
+ * window is the shared chart's and speaks that type, and an alias here that
+ * merely renamed it would need converting at every call. `x` is in m/z and `y`
+ * in intensity.
+ */
+export type MassDomain = ChartDomain;
+
+/**
+ * Whether a spectrum is on the chart at all, by whichever of its traces.
+ *
+ * A spectrum is drawn as its profile *or* as its sticks and never as both — a
+ * centroid standing inside the peak shapes it was picked from reads as a second
+ * spectrum laid over the first — so whether it is on screen is a question about
+ * the pair and not about either one.
+ *
+ * This is what everything that *uses* the picked peaks asks: pointing at a peak,
+ * labelling one, listing them. All of them read the centroid whether or not the
+ * sticks are the trace being drawn, so asking `showCentroid` there would make a
+ * spectrum shown as its profile quietly stop answering anything.
+ * @param spectrum - The spectrum.
+ * @returns Whether either of its traces is drawn.
+ */
+export function isSpectrumDrawn(spectrum: MassSpectrum): boolean {
+  return spectrum.showProfile || spectrum.showCentroid;
+}

package/src/mass/core/massState.ts

@@ -0,0 +1,206 @@
+/**
+ * Everything the viewer knows, in the three buckets NMRium splits its own into
+ * — the same three the infrared viewer holds, under the same names.
+ *
+ * The split is the persistence boundary as much as anything: `data` is the
+ * document, `view` is where you are in it and lasts as long as the session, and
+ * `settings` is the workspace, which is how every spectrum is drawn whichever
+ * ones happen to be open.
+ *
+ * The peaks are in `data`, each spectrum carrying its own centroid: picked once,
+ * when the spectrum was read, so nothing about drawing it ever picks again.
+ */
+
+import type { MassPanelId, MassSidePanelId } from './massSidePanels.ts';
+import type { MassDomain, MassSpectrum } from './massSpectrum.ts';
+import type { MzDecimalsSetting } from './mzDecimalsSetting.ts';
+import { readMzDecimalsSetting } from './mzDecimalsSetting.ts';
+
+/** The document: what the files held. */
+export interface MassData {
+  /** The spectra, in the order they were loaded. */
+  spectra: MassSpectrum[];
+}
+
+/** What a drag across the chart is for while it is chosen. */
+export type MassTool = 'read' | 'box';
+
+/** Where you are in the viewer. */
+export interface MassView {
+  /** Identity of the spectrum the panels act on, `null` for none. */
+  selectedId: string | null;
+  /**
+   * The window being shown, `null` while the chart is showing what fits.
+   *
+   * Held here so that a toolbar button and a row of the peak table can zoom —
+   * the chart is told a window and reports every window it arrives at, and this
+   * is where the answer lives between the two.
+   */
+  domain: MassDomain | null;
+  /** Which tool a drag across the chart is running. */
+  tool: MassTool;
+  /**
+   * The side panels that are open: the viewer's own and any a host added. An id
+   * no panel on offer answers to opens nothing.
+   */
+  openPanelIds: MassPanelId[];
+  /** Why the last action was refused, `null` as soon as one succeeds. */
+  error: string | null;
+}
+
+/** The workspace: how every spectrum is drawn, whichever ones are open. */
+export interface MassSettings {
+  /** Whether the peaks of the selected spectrum are labelled on the chart. */
+  showLabels: boolean;
+  /** At most how many peaks are labelled at once. */
+  labelLimit: number;
+  /** Whether a label writes the charge of a peak whose charge was established. */
+  showCharges: boolean;
+  /**
+   * How many decimals the masses on screen are written with: `'auto'` for what
+   * the spectra resolve — high-resolution masses or nominal ones — or the
+   * number the reader chose.
+   */
+  mzDecimals: MzDecimalsSetting;
+}
+
+/** Everything the viewer knows. */
+export interface MassState {
+  /** The spectra that are open. */
+  data: MassData;
+  /** Where you are in the viewer. */
+  view: MassView;
+  /** How spectra are drawn. */
+  settings: MassSettings;
+}
+
+/** Part of a state, as a host restoring one supplies it. */
+export interface PartialMassState {
+  /** The spectra that were open. */
+  data?: MassData;
+  /** Where the viewer was left. */
+  view?: Partial<MassView>;
+  /** The workspace they were drawn in. */
+  settings?: Partial<MassSettings>;
+}
+
+/** The panel the splitter brings back when it is dragged open on nothing. */
+export const DEFAULT_SIDE_PANEL: MassSidePanelId = 'spectra';
+
+/**
+ * The panels a fresh viewer opens with: the list, and the peaks of whichever
+ * spectrum is selected in it, because a spectrum is read through its peaks.
+ */
+export const DEFAULT_SIDE_PANELS: MassSidePanelId[] = ['spectra', 'peaks'];
+
+/** How many peaks are labelled to begin with. */
+export const DEFAULT_LABEL_LIMIT = 20;
+
+/** At most how many peaks a setting may ask to have labelled. */
+export const MAXIMUM_LABEL_LIMIT = 500;
+
+/** The workspace a fresh viewer starts from. */
+export const DEFAULT_SETTINGS: MassSettings = {
+  showLabels: true,
+  labelLimit: DEFAULT_LABEL_LIMIT,
+  showCharges: true,
+  mzDecimals: 'auto',
+};
+
+/** What a viewer opens on. */
+export interface CreateMassStateOptions {
+  /**
+   * The spectra to open on.
+   * @default []
+   */
+  spectra?: MassSpectrum[];
+  /**
+   * The workspace to open in.
+   * @default DEFAULT_SETTINGS
+   */
+  settings?: Partial<MassSettings>;
+  /**
+   * The panels open to begin with, the viewer's own or a host's.
+   * @default DEFAULT_SIDE_PANELS
+   */
+  panelIds?: readonly MassPanelId[];
+}
+
+/**
+ * The state a viewer opens with.
+ *
+ * The panel list is spread rather than stored by reference: a caller's array is
+ * the caller's to mutate, and a viewer holding it would find its open panels
+ * changing under it.
+ * @param options - What it opens on.
+ * @returns The state.
+ */
+export function createMassState(
+  options: CreateMassStateOptions = {},
+): MassState {
+  const { spectra = [], settings, panelIds } = options;
+  return {
+    data: { spectra: [...spectra] },
+    view: {
+      selectedId: spectra[0]?.id ?? null,
+      domain: null,
+      tool: 'read',
+      openPanelIds: [...(panelIds ?? DEFAULT_SIDE_PANELS)],
+      error: null,
+    },
+    settings: mergeMassSettings(DEFAULT_SETTINGS, settings),
+  };
+}
+
+/**
+ * Fold a change into the workspace, refusing what no chart survives.
+ *
+ * A number typed into a field arrives here as `NaN` for every keystroke that is
+ * not yet a number — a lone minus sign, an empty box — and a limit of `NaN`
+ * silently stops every label being drawn. So the limit is checked, and the
+ * current value kept where the new one is unusable rather than the field being
+ * fought with while it is being typed in. The decimals are read back the same
+ * way, through `readMzDecimalsSetting`, since a stored workspace is no more to
+ * be trusted than a half-typed field.
+ * @param current - The workspace in force.
+ * @param change - What to change about it.
+ * @returns The new workspace.
+ */
+export function mergeMassSettings(
+  current: MassSettings,
+  change: Partial<MassSettings> = {},
+): MassSettings {
+  const asked = change.labelLimit ?? current.labelLimit;
+  return {
+    ...current,
+    ...change,
+    labelLimit: Number.isFinite(asked)
+      ? Math.min(MAXIMUM_LABEL_LIMIT, Math.max(0, Math.round(asked)))
+      : current.labelLimit,
+    mzDecimals: readMzDecimalsSetting(change.mzDecimals) ?? current.mzDecimals,
+  };
+}
+
+/**
+ * Whether a window is one a chart can be built on.
+ *
+ * Both ends finite and the low one below the high one. A window failing either
+ * makes every scale built from it infinite, which the DOM refuses outright — so
+ * a handle told to frame a peak it worked out wrongly leaves the chart alone
+ * instead of blanking it.
+ * @param domain - The window to check.
+ * @returns Whether it can be shown.
+ */
+export function isMassWindow(domain: MassDomain): boolean {
+  return isWindow(domain.x) && isWindow(domain.y);
+}
+
+/**
+ * Whether one axis of a window runs from somewhere to somewhere else.
+ * @param bounds - `[from, to]` on that axis.
+ * @returns Whether it is usable.
+ */
+function isWindow(bounds: readonly [number, number]): boolean {
+  const [from, to] = bounds;
+  return Number.isFinite(from) && Number.isFinite(to) && from < to;
+}

package/src/mass/core/massStateEdits.ts

@@ -0,0 +1,104 @@
+/**
+ * The edits the reducer makes in more than one place, kept apart from it so
+ * the reducer reads as the list of what can be asked of the viewer.
+ */
+
+import type { MassSpectrum } from './massSpectrum.ts';
+import type { MassState, PartialMassState } from './massState.ts';
+import { isMassWindow, mergeMassSettings } from './massState.ts';
+
+/**
+ * Change one spectrum, leaving the state itself when nothing changed.
+ *
+ * The edit returns the very spectrum it was handed when it has nothing to do,
+ * and that is passed on: a rename to the name already held must not rebuild
+ * the list, or every memo keyed on it is defeated by a keystroke that did
+ * nothing.
+ * @param state - The state in force.
+ * @param id - Identity of the spectrum to change.
+ * @param edit - What to do to it.
+ * @returns The new state, or the old one when the spectrum is absent or the
+ * edit changed nothing.
+ */
+export function mapSpectrum(
+  state: MassState,
+  id: string,
+  edit: (spectrum: MassSpectrum) => MassSpectrum,
+): MassState {
+  let changed = false;
+  const spectra = state.data.spectra.map((spectrum) => {
+    if (spectrum.id !== id) return spectrum;
+    const edited = edit(spectrum);
+    if (edited !== spectrum) changed = true;
+    return edited;
+  });
+  return changed ? { ...state, data: { spectra } } : state;
+}
+
+/**
+ * The spectra of an arrival that are not open already.
+ *
+ * Identity is what every row, every trace and the selection are keyed on, so a
+ * second spectrum under an identity already taken would be two rows React
+ * cannot tell apart and one trace drawn twice. A host handing the same spectra
+ * over again is asking for nothing new.
+ * @param state - The state in force.
+ * @param spectra - What is arriving.
+ * @returns What is new, in the order it arrived.
+ */
+export function arriving(
+  state: MassState,
+  spectra: readonly MassSpectrum[],
+): MassSpectrum[] {
+  const taken = new Set<string>();
+  for (const spectrum of state.data.spectra) taken.add(spectrum.id);
+  const fresh: MassSpectrum[] = [];
+  for (const spectrum of spectra) {
+    if (taken.has(spectrum.id)) continue;
+    taken.add(spectrum.id);
+    fresh.push(spectrum);
+  }
+  return fresh;
+}
+
+/**
+ * Take a whole state, as a host restoring one supplies it.
+ *
+ * What is restored is checked against what it is restored with: a selection
+ * naming a spectrum that is not among the restored ones selects the first
+ * instead, and a window no chart can be drawn on is dropped for the fit.
+ * @param state - The state in force.
+ * @param partial - What the host supplies.
+ * @returns The restored state.
+ */
+export function restoreState(
+  state: MassState,
+  partial: PartialMassState,
+): MassState {
+  const spectra = partial.data?.spectra ?? state.data.spectra;
+  const view = { ...state.view, ...partial.view };
+  const selectable =
+    view.selectedId !== null &&
+    spectra.some((spectrum) => spectrum.id === view.selectedId);
+  return {
+    data: { spectra },
+    view: {
+      ...view,
+      selectedId: selectable ? view.selectedId : (spectra[0]?.id ?? null),
+      domain:
+        view.domain !== null && isMassWindow(view.domain) ? view.domain : null,
+      openPanelIds: [...view.openPanelIds],
+    },
+    settings: mergeMassSettings(state.settings, partial.settings),
+  };
+}
+
+/**
+ * Refuse an action, saying why.
+ * @param state - The state in force.
+ * @param error - The sentence to show whoever asked.
+ * @returns The state carrying the refusal.
+ */
+export function withError(state: MassState, error: string): MassState {
+  return { ...state, view: { ...state.view, error } };
+}