react-cheminfo 0.28.0 → 0.30.0

package/src/ir/core/irSpectrum.ts

@@ -0,0 +1,155 @@
+/**
+ * What an infrared spectrum is once it has been read, whatever it was read from.
+ *
+ * One acquisition becomes one `IrSpectrum` carrying **both** value axes —
+ * absorbance and percent transmittance — over one shared array of wavenumbers.
+ * Both are held rather than one being derived on demand because `ir-spectrum`
+ * already produces both when it reads a file: it adds an `a` and a `t` variable
+ * to every spectrum whichever of the two the instrument wrote, so the conversion
+ * happens once, in the one place that knows what the file's y axis meant. Holding
+ * the answer means switching what is drawn costs nothing, and means the two
+ * axes can never drift apart through a round trip.
+ *
+ * The arrays are `Float64Array` and are replaced on a change, never written
+ * into, since every consumer holds the same object by reference. An infrared
+ * spectrum is a few thousand points rather than a mass spectrum's few hundred
+ * thousand, so holding two value axes costs nothing worth counting.
+ */
+
+import type { DataXY } from 'cheminfo-types';
+
+import type { ChartDomain } from '../../chart/core/chartDomain.ts';
+
+/**
+ * One trace of a measurement: wavenumber against whichever value axis is drawn.
+ *
+ * `DataXY` is the shape every package in this pipeline speaks — `ir-spectrum`,
+ * `common-spectrum`, `xy-parser` 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 IrTrace = DataXY<Float64Array>;
+
+/** The formats a spectrum can have been read from. */
+export type IrFormat = 'jcamp' | 'spc' | 'text' | 'calculated';
+
+/**
+ * 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,
+ * while `meta` is a table to read.
+ */
+export interface IrOrigin {
+  /** The format it was read from. */
+  format: IrFormat;
+  /**
+   * Name of the file it came from, absent for a paste.
+   * @default undefined
+   */
+  fileName?: string;
+  /**
+   * Which block of that file, absent when the file held only one.
+   * @default undefined
+   */
+  blockIndex?: number;
+  /**
+   * Which value axis the file itself carried, absent when it said nothing.
+   *
+   * Worth keeping even though both axes are held: a spectrum exported as
+   * transmittance and one exported as absorbance are the same measurement, but
+   * only one of the two is what the instrument actually recorded, and the other
+   * carries whatever the conversion did to its noise.
+   * @default undefined
+   */
+  recorded?: IrMode;
+}
+
+/** One row of the acquisition table. */
+export interface IrMetaField {
+  /** 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, and the panel then shows the
+ * file name alone.
+ */
+export interface IrMeta {
+  /** The title record, `null` when the file carries none. */
+  title: string | null;
+  /** The fields that are populated, in display order. */
+  fields: IrMetaField[];
+}
+
+/** Which value axis is being drawn and read. */
+export type IrMode = 'absorbance' | 'transmittance';
+
+/** One spectrum as the viewer holds it. */
+export interface IrSpectrum {
+  /** 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 it is drawn in. */
+  color: string;
+  /**
+   * The wavenumbers in cm⁻¹, **ascending**.
+   *
+   * Ascending even though the axis is read from 4000 down to 400: which way the
+   * numbers run on screen is the chart's business, and every binary search and
+   * every extent taken off index zero downstream wants them in order. Reversing
+   * the data instead would make the drawing simpler once and everything else
+   * wrong.
+   */
+  wavenumber: Float64Array;
+  /** Absorbance at each wavenumber, as `ir-spectrum` supplied it. */
+  absorbance: Float64Array;
+  /** Percent transmittance at each wavenumber, likewise. */
+  transmittance: Float64Array;
+  /** What the file said about the acquisition, `null` when it said nothing. */
+  meta: IrMeta | null;
+  /** Where it came from. */
+  origin: IrOrigin;
+  /** Whether it is drawn. */
+  visible: boolean;
+  /**
+   * Whether the trace is left out of the automatic domain. A reference held
+   * under the pointer for comparison must not move the axes, or hovering one
+   * would throw away the zoom the user set.
+   * @default false
+   */
+  excludeFromDomain?: boolean;
+}
+
+/**
+ * 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
+ * wavenumbers and runs low to high, whichever way round the axis is drawn.
+ */
+export type IrDomain = ChartDomain;
+
+/**
+ * The trace to draw for a spectrum, in whichever value axis is being read.
+ *
+ * The arrays are handed back by reference rather than copied: nothing downstream
+ * writes into a trace, and a profile of a few thousand points copied on every
+ * render of every spectrum is a copy per frame for no gain.
+ * @param spectrum - The spectrum.
+ * @param mode - Which value axis is being drawn.
+ * @returns The trace, sharing the spectrum's own arrays.
+ */
+export function traceOf(spectrum: IrSpectrum, mode: IrMode): IrTrace {
+  return {
+    x: spectrum.wavenumber,
+    y: mode === 'absorbance' ? spectrum.absorbance : spectrum.transmittance,
+  };
+}

package/src/ir/core/irState.ts

@@ -0,0 +1,173 @@
+/**
+ * Everything the viewer knows, in the three buckets NMRium splits its own into
+ * — the same three the mass 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 bands are **not** in here. They are derived from the spectra and the
+ * picking settings, so holding them would mean holding an answer that has to be
+ * kept in step with its own inputs — `useIrEditor` recomputes them instead, and
+ * a stale band is then impossible rather than merely unlikely.
+ */
+
+import type { IrSidePanelId } from './irSidePanels.ts';
+import type { IrDomain, IrMode, IrSpectrum } from './irSpectrum.ts';
+import type { PickBandsOptions } from './pickBands.ts';
+
+/** The document: what a file holds. */
+export interface IrData {
+  /** The spectra, in the order they were loaded. */
+  spectra: IrSpectrum[];
+}
+
+/** What a drag across the chart is for while it is chosen. */
+export type IrTool = 'read' | 'box';
+
+/** Where you are in the viewer. */
+export interface IrView {
+  /** 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 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: IrDomain | null;
+  /** Which tool a drag across the chart is running. */
+  tool: IrTool;
+  /** The side panels that are open, in the order their icons are stacked. */
+  openPanelIds: IrSidePanelId[];
+  /** 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 IrSettings {
+  /** Which value axis the spectra are read in. */
+  mode: IrMode;
+  /** Whether the bands are picked at all. */
+  pickBands: boolean;
+  /** How the bands are picked when they are. */
+  picking: PickBandsOptions;
+  /** Whether a band's label names its assignment as well as its wavenumber. */
+  showAssignments: boolean;
+  /** At most how many bands are labelled on the chart. */
+  labelLimit: number;
+  /** How far outside a table range a band may fall and still be offered it. */
+  assignmentTolerance: number;
+}
+
+/** Everything the viewer knows. */
+export interface IrState {
+  /** The spectra that are open. */
+  data: IrData;
+  /** Where you are in the viewer. */
+  view: IrView;
+  /** How spectra are drawn and read. */
+  settings: IrSettings;
+}
+
+/** Part of a state, as a host restoring one supplies it. */
+export interface PartialIrState {
+  /** The spectra that were open. */
+  data?: IrData;
+  /** Where the viewer was left. */
+  view?: Partial<IrView>;
+  /** The workspace they were drawn in. */
+  settings?: Partial<IrSettings>;
+}
+
+/** The panel the splitter brings back when it is dragged open on nothing. */
+export const DEFAULT_SIDE_PANEL: IrSidePanelId = 'spectra';
+
+/**
+ * The panels a fresh viewer opens with.
+ *
+ * The band table, because it is the reason to open an infrared spectrum at all
+ * — a trace on its own can be looked at, and it is the table beside it that lets
+ * it be read.
+ */
+export const DEFAULT_SIDE_PANELS: IrSidePanelId[] = ['spectra', 'bands'];
+
+/** At most how many bands a gesture may ask to have labelled. */
+export const MAXIMUM_LABEL_LIMIT = 200;
+
+/** How many are labelled to begin with. */
+export const DEFAULT_LABEL_LIMIT = 12;
+
+/** How the bands are picked before anybody adjusts it. */
+export const DEFAULT_PICKING: PickBandsOptions = {
+  minRelativeHeight: 0.02,
+  minPeakWidth: 4,
+};
+
+/** The workspace a fresh viewer starts from. */
+export const DEFAULT_SETTINGS: IrSettings = {
+  mode: 'transmittance',
+  pickBands: true,
+  picking: DEFAULT_PICKING,
+  showAssignments: false,
+  labelLimit: DEFAULT_LABEL_LIMIT,
+  assignmentTolerance: 5,
+};
+
+/**
+ * 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 each is checked, and the current
+ * value is kept where the new one is unusable rather than the field being
+ * fought with while it is being typed in.
+ * @param current - The workspace in force.
+ * @param change - What to change about it.
+ * @returns The new workspace.
+ */
+export function mergeIrSettings(
+  current: IrSettings,
+  change: Partial<IrSettings> = {},
+): IrSettings {
+  const asked = change.labelLimit ?? current.labelLimit;
+  const tolerance = change.assignmentTolerance ?? current.assignmentTolerance;
+  return {
+    ...current,
+    ...change,
+    picking: { ...current.picking, ...change.picking },
+    labelLimit: Number.isFinite(asked)
+      ? Math.min(MAXIMUM_LABEL_LIMIT, Math.max(0, Math.round(asked)))
+      : current.labelLimit,
+    assignmentTolerance:
+      Number.isFinite(tolerance) && tolerance >= 0
+        ? tolerance
+        : current.assignmentTolerance,
+  };
+}
+
+/**
+ * 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 band 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 isIrWindow(domain: IrDomain): 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: [number, number]): boolean {
+  const [from, to] = bounds;
+  return Number.isFinite(from) && Number.isFinite(to) && from < to;
+}

package/src/ir/core/loadIrSpectra.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 an SPC never downloads its parser.
+ */
+
+import { describeSource } from '../../error/core/index.ts';
+
+import type { LoadedIrSpectrum } from './analysisSpectra.ts';
+import { detectIrFormat } from './detectIrFormat.ts';
+import type { IrOrigin } from './irSpectrum.ts';
+
+/** How a file is read. */
+export interface LoadIrSpectraOptions {
+  /**
+   * 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;
+}
+
+/** What a file turned out to hold. */
+export interface LoadIrSpectraResult {
+  /** The spectra it held, in the order the file wrote them. */
+  spectra: LoadedIrSpectrum[];
+  /** What it turned out to be. */
+  format: IrOrigin['format'];
+}
+
+/**
+ * Read every infrared spectrum a file holds.
+ * @param data - The file, as bytes, or the pasted text.
+ * @param options - The file's name.
+ * @returns The spectra, and the format they were read from.
+ * @throws {Error} When nothing in the file names a format this can read, or when
+ * the reader for that format gave up on it.
+ */
+export async function loadIrSpectra(
+  data: Uint8Array | string,
+  options: LoadIrSpectraOptions = {},
+): Promise<LoadIrSpectraResult> {
+  const { fileName } = options;
+  const format = detectIrFormat(data, fileName);
+
+  if (format === 'jcamp') {
+    const { fromJcamp } = await import('./fromJcamp.ts');
+    return { spectra: fromJcamp(data, options), format };
+  }
+
+  if (format === 'spc') {
+    if (typeof data === 'string') {
+      throw new Error(
+        `${describeSource(fileName)} looks like an SPC file but arrived as text — SPC is binary, and reading it as text loses bytes it cannot get back.`,
+      );
+    }
+    const { fromSpc } = await import('./fromSpc.ts');
+    return { spectra: fromSpc(data, options), format };
+  }
+
+  if (format === 'text') {
+    // Deliberately refused rather than half-read. `ir-spectrum` adds the
+    // absorbance and transmittance pair to everything `fromJcamp` and `fromSPC`
+    // produce, but not to `fromText`, so a two-column file arrives carrying only
+    // the axis it was written in. Deriving the other one here would put a second
+    // implementation of that conversion in this package, which is exactly what
+    // depending on `ir-spectrum` is meant to avoid.
+    throw new Error(
+      `${describeSource(fileName)} is two columns of numbers, which this viewer cannot read yet: ir-spectrum derives the absorbance and transmittance pair for JCAMP-DX and SPC but not for plain text, and this package deliberately does not do that conversion itself. Export the spectrum as JCAMP-DX (.jdx) instead.`,
+    );
+  }
+
+  throw new Error(
+    `${describeSource(fileName)} is not a spectrum this viewer can read — JCAMP-DX (.jdx, .dx) and Thermo Galactic SPC (.spc) are understood.`,
+  );
+}

package/src/ir/core/nearestBand.ts

@@ -0,0 +1,57 @@
+/**
+ * Which band the pointer is asking about.
+ *
+ * Found in pixels rather than in wavenumbers, because what a user means by
+ * "that band" is what is under the pointer on screen: at a full-scan zoom two
+ * bands thirty wavenumbers apart are three pixels apart and either will do,
+ * while at a deep zoom the same thirty wavenumbers is half the plot and only one
+ * of them is being pointed at.
+ */
+
+import type { ChartScale } from '../../chart/core/chartScale.ts';
+import { chartPixel } from '../../chart/core/chartScale.ts';
+
+import type { IrBand } from './irBand.ts';
+
+/**
+ * How close the pointer has to be to a band, in pixels.
+ *
+ * Eight is about a fingertip's worth of aim on a trackpad. Wider and the readout
+ * claims a band while the pointer is plainly on the baseline beside it; narrower
+ * and a band has to be hit exactly, which on a dense fingerprint region is not
+ * a gesture anyone can make.
+ */
+export const BAND_HIT_RADIUS = 8;
+
+/**
+ * The band nearest a place on the axis, when one is within reach.
+ *
+ * A plain scan rather than a binary search: a spectrum is picked down to a few
+ * dozen bands, so the whole list is shorter than the setup a search would need,
+ * and it stays correct if the bands ever arrive in another order.
+ * @param bands - The bands of every spectrum currently drawn.
+ * @param xScale - The wavenumber axis as it is currently zoomed, which may run
+ * either way round.
+ * @param pixelX - Where the pointer is, in user units of the SVG.
+ * @param radius - How close it has to be. Defaults to `BAND_HIT_RADIUS`.
+ * @returns The band, or `null` when none is within reach.
+ */
+export function nearestBandAt(
+  bands: readonly IrBand[],
+  xScale: ChartScale,
+  pixelX: number,
+  radius = BAND_HIT_RADIUS,
+): IrBand | null {
+  let found: IrBand | null = null;
+  let bestDistance = radius;
+  for (const band of bands) {
+    const distance = Math.abs(chartPixel(xScale, band.wavenumber) - pixelX);
+    // Strictly nearer, so the first of two bands at one wavenumber wins and the
+    // answer does not flicker between them as the pointer rests still.
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      found = band;
+    }
+  }
+  return found;
+}

package/src/ir/core/pickBands.ts

@@ -0,0 +1,181 @@
+/**
+ * Finding the bands in a spectrum, which `ir-spectrum` does.
+ *
+ * Everything here is the two things that call needs and does not have: a
+ * `MeasurementXY` built out of the arrays the viewer holds, and the decision to
+ * pick on **absorbance** rather than on transmittance. That second one is the
+ * only judgement in the file and it is not a preference — peak picking finds
+ * maxima, and a band is a maximum in absorbance but a *minimum* in transmittance,
+ * so picking on transmittance would return the flat baseline between the bands
+ * and miss every band there is.
+ */
+
+import type { MeasurementXY } from 'cheminfo-types';
+import { autoPeakPicking } from 'ir-spectrum';
+import { xMaxValue, xMinValue } from 'ml-spectra-processing';
+
+import type { IrBand, IrBandStrength } from './irBand.ts';
+import type { IrSpectrum } from './irSpectrum.ts';
+
+/** How the bands are picked. */
+export interface PickBandsOptions {
+  /**
+   * Lowest wavenumber to pick in, in cm⁻¹.
+   * @default the start of the spectrum
+   */
+  from?: number;
+  /**
+   * Highest wavenumber to pick in, in cm⁻¹.
+   * @default the end of the spectrum
+   */
+  to?: number;
+  /**
+   * How tall a band must be against the tallest one to count, as a fraction.
+   *
+   * Two percent by default, which on a real ATR spectrum is a little above the
+   * noise and a long way below any band worth naming. Lowered, the fingerprint
+   * region fills with shoulders that have no assignment; raised past about a
+   * tenth, weak but diagnostic bands — a nitrile, an alkyne — stop being found.
+   * @default 0.02
+   */
+  minRelativeHeight?: number;
+  /**
+   * Narrowest band to keep, in cm⁻¹.
+   *
+   * A spike one point wide is a detector glitch rather than a vibration: real
+   * infrared bands are several wavenumbers across even at their sharpest.
+   * @default 4
+   */
+  minPeakWidth?: number;
+  /**
+   * At most how many bands to keep, the strongest first.
+   * @default every band found
+   */
+  limit?: number;
+}
+
+/**
+ * Pick the bands of one spectrum.
+ *
+ * The bands come back in ascending wavenumber, which is the order a spectrum is
+ * read in rather than the order they were found — `limit` cuts by height, and
+ * then what survives is put back in axis order, so a table of them reads like
+ * the chart.
+ *
+ * **A band centre is a sampled point, not an interpolated one.** `ir-spectrum`
+ * reports each picked band at the wavenumber of the sample it peaked on, so on a
+ * bench instrument's 4 cm⁻¹ grid a carbonyl centred at 1710 is reported at 1708
+ * or 1712. That is within the tolerance the assignment table is matched with, and
+ * refining it here would mean re-deriving a peak position this package has
+ * deliberately delegated — but it is why a band should never be quoted as though
+ * it were measured to the wavenumber.
+ * @param spectrum - The spectrum to pick from.
+ * @param options - Where to pick, and what to keep.
+ * @returns The bands, ascending by wavenumber.
+ */
+export function pickBands(
+  spectrum: IrSpectrum,
+  options: PickBandsOptions = {},
+): IrBand[] {
+  const {
+    from,
+    to,
+    minRelativeHeight = 0.02,
+    minPeakWidth = 4,
+    limit,
+  } = options;
+  if (spectrum.wavenumber.length < 2) return [];
+
+  const picked = autoPeakPicking(measurementOf(spectrum), {
+    // Absorbance, because a band is a maximum there and a minimum in the other.
+    yVariable: 'a',
+    minMaxRatio: minRelativeHeight,
+    minPeakWidth,
+    ...(from === undefined ? {} : { from }),
+    ...(to === undefined ? {} : { to }),
+  });
+
+  const bands: IrBand[] = [];
+  for (const peak of picked) {
+    if (!Number.isFinite(peak.wavenumber)) continue;
+    bands.push({
+      spectrumId: spectrum.id,
+      wavenumber: peak.wavenumber,
+      absorbance: peak.absorbance,
+      // `ConvertedPeak.transmittance` is a fraction where the spectrum's own
+      // transmittance is a percentage; brought onto the one scale here so that
+      // nothing downstream has to remember which of the two it is holding.
+      transmittance: peak.transmittance * 100,
+      strength: peak.kind as IrBandStrength,
+    });
+  }
+
+  const kept =
+    limit === undefined || bands.length <= limit
+      ? bands
+      : bands.toSorted(byDescendingAbsorbance).slice(0, limit);
+  return kept.toSorted(byAscendingWavenumber);
+}
+
+/**
+ * The spectrum as `ir-spectrum` wants it.
+ *
+ * The `t` variable is given its extremes, because that is what the strength
+ * letter is worked out from: without them the conversion assumes a spectrum
+ * running the full 0 to 100 percent, and every band of a shallow ATR trace that
+ * never leaves the eighties comes back weak.
+ * @param spectrum - The spectrum the viewer holds.
+ * @returns A measurement carrying all three variables.
+ */
+function measurementOf(spectrum: IrSpectrum): MeasurementXY {
+  const transmittance = {
+    label: 'Transmittance (%)',
+    units: '%',
+    symbol: 't' as const,
+    data: spectrum.transmittance,
+    min: xMinValue(spectrum.transmittance),
+    max: xMaxValue(spectrum.transmittance),
+  };
+  return {
+    variables: {
+      x: {
+        label: 'Wavenumber',
+        units: '1/cm',
+        symbol: 'x',
+        data: spectrum.wavenumber,
+      },
+      // `y` is required of every measurement, and stands for whichever axis was
+      // recorded. Nothing here reads it — the picking is told to use `a` and the
+      // strength letter is read off `t` — so it carries the transmittance rather
+      // than a third copy of anything.
+      y: transmittance,
+      a: {
+        label: 'Absorbance',
+        units: '',
+        symbol: 'a',
+        data: spectrum.absorbance,
+      },
+      t: transmittance,
+    },
+  };
+}
+
+/**
+ * Order two bands by height, tallest first.
+ * @param first - One band.
+ * @param second - The other.
+ * @returns The comparison.
+ */
+function byDescendingAbsorbance(first: IrBand, second: IrBand): number {
+  return second.absorbance - first.absorbance;
+}
+
+/**
+ * Order two bands along the axis, lowest wavenumber first.
+ * @param first - One band.
+ * @param second - The other.
+ * @returns The comparison.
+ */
+function byAscendingWavenumber(first: IrBand, second: IrBand): number {
+  return first.wavenumber - second.wavenumber;
+}