react-cheminfo 0.27.0 → 0.29.0

package/src/ir/core/analysisSpectra.ts

@@ -0,0 +1,231 @@
+/**
+ * The step every reader shares: an `ir-spectrum` `Analysis` becomes spectra.
+ *
+ * All three readers hand back the same `Analysis`, and `ir-spectrum` has already
+ * done the part that needs to know what the file's y axis meant — it puts an `a`
+ * and a `t` variable on every spectrum whichever of the two was written. So what
+ * is left here is bookkeeping: order the points, type the arrays, read the
+ * records, and say which axis the file itself carried.
+ */
+
+import type { DoubleArray, MeasurementXY } from 'cheminfo-types';
+import type { Analysis } from 'ir-spectrum';
+import { xySortX } from 'ml-spectra-processing';
+
+import type { IrMeta, IrMode, IrOrigin } from './irSpectrum.ts';
+
+/** One spectrum as a reader produced it, before it is named and coloured. */
+export interface LoadedIrSpectrum {
+  /** The wavenumbers, ascending. */
+  wavenumber: Float64Array;
+  /** Absorbance at each. */
+  absorbance: Float64Array;
+  /** Percent transmittance at each. */
+  transmittance: Float64Array;
+  /** What the file said about the acquisition, `null` when it said nothing. */
+  meta: IrMeta | null;
+  /** Where it came from. */
+  origin: IrOrigin;
+  /**
+   * What the file called it, absent when it carried no title.
+   * @default undefined
+   */
+  name?: string;
+}
+
+/**
+ * Turn every spectrum an analysis holds into one loaded spectrum.
+ *
+ * All of them, never the first: a JCAMP is a container, and an instrument
+ * exporting a background beside a sample writes both as blocks of one file.
+ * Taking only the first would quietly drop what the chemist exported the file
+ * for, and would do it without an error.
+ *
+ * A block carrying fewer than two points is skipped rather than kept as a
+ * degenerate trace — a JCAMP link block, or a header block an instrument wrote
+ * with no data under it, is not a spectrum.
+ * @param analysis - What the reader built.
+ * @param origin - Where it came from: the format and the file.
+ * @returns One entry per readable block, in the order the file wrote them.
+ */
+export function analysisSpectra(
+  analysis: Analysis,
+  origin: IrOrigin,
+): LoadedIrSpectrum[] {
+  const blocks = analysis.spectra;
+  const spectra: LoadedIrSpectrum[] = [];
+
+  for (let index = 0; index < blocks.length; index++) {
+    const block = blocks[index];
+    if (block === undefined) continue;
+    if (!isInfrared(block)) continue;
+    const wavenumbers = block.variables.x?.data;
+    const absorbances = block.variables.a?.data;
+    const transmittances = block.variables.t?.data;
+    if (
+      wavenumbers === undefined ||
+      absorbances === undefined ||
+      transmittances === undefined ||
+      wavenumbers.length < 2
+    ) {
+      continue;
+    }
+
+    const blockOrigin: IrOrigin = { ...origin };
+    // A file holding one spectrum has no index worth showing; calling it block 0
+    // in the list would suggest there is a block 1 somewhere.
+    if (blocks.length > 1) blockOrigin.blockIndex = index;
+    const recorded = recordedMode(block);
+    if (recorded !== undefined) blockOrigin.recorded = recorded;
+
+    const spectrum: LoadedIrSpectrum = {
+      // Sorted once, on the axis both value arrays are indexed by, and the same
+      // permutation applied to each — sorting them independently would pair an
+      // absorbance with another wavenumber's transmittance.
+      ...sortedByWavenumber(wavenumbers, absorbances, transmittances),
+      meta: blockMeta(block),
+      origin: blockOrigin,
+    };
+    const title = blockTitle(block);
+    // An absent name is an absent key, never a key holding `undefined`: the two
+    // read the same in a debugger and differently in every structural comparison.
+    if (title) spectrum.name = title;
+    spectra.push(spectrum);
+  }
+
+  return spectra;
+}
+
+/** The three arrays of one spectrum, in ascending wavenumber. */
+type SortedTraces = Pick<
+  LoadedIrSpectrum,
+  'wavenumber' | 'absorbance' | 'transmittance'
+>;
+
+/**
+ * Put the points in ascending wavenumber, carrying both value axes along.
+ *
+ * `xySortX` is asked twice with the same x, which sorts it twice — but it is the
+ * one sort in the ecosystem that both orders and types an `xy` pair, and an
+ * infrared spectrum is a few thousand points. Writing a bespoke permutation to
+ * save one pass over four thousand numbers would be a second sort to keep
+ * correct for no measurable gain.
+ * @param wavenumbers - The wavenumbers, in whatever order the file wrote them.
+ * @param absorbances - Absorbance at each.
+ * @param transmittances - Percent transmittance at each.
+ * @returns The three arrays, ascending and typed.
+ */
+function sortedByWavenumber(
+  wavenumbers: DoubleArray,
+  absorbances: DoubleArray,
+  transmittances: DoubleArray,
+): SortedTraces {
+  const byAbsorbance = xySortX({ x: wavenumbers, y: absorbances });
+  const byTransmittance = xySortX({ x: wavenumbers, y: transmittances });
+  return {
+    wavenumber: Float64Array.from(byAbsorbance.x),
+    absorbance: Float64Array.from(byAbsorbance.y),
+    transmittance: Float64Array.from(byTransmittance.y),
+  };
+}
+
+/**
+ * What the block calls itself, with the file's own commentary taken off.
+ *
+ * `$$` opens a comment that runs to the end of the line in JCAMP, and a real
+ * `##TITLE` often carries one: the JSpecView collection is full of
+ * `urea $$ Begin of the data block`. Left in, the comment becomes the name of
+ * the spectrum in the list and the heading of its metadata panel.
+ * @param block - One spectrum of the analysis.
+ * @returns The title, or `undefined` when the block carries none worth showing.
+ */
+function blockTitle(block: MeasurementXY): string | undefined {
+  const written = block.title?.split('$$', 1)[0]?.trim();
+  return written === undefined || written === '' ? undefined : written;
+}
+
+/**
+ * Whether a block is an infrared spectrum rather than something else entirely.
+ *
+ * A JCAMP `LINK` block is a container, and the real ones in the wild put a Raman
+ * spectrum of the same sample in beside the infrared — `DCE.jdx` from the
+ * JSpecView collection holds two of each. A Raman shift is not a wavenumber
+ * absorbed, so loading one as infrared would draw a spectrum whose axis means
+ * something else and offer functional groups for its bands.
+ *
+ * Read off the block's own data type, and a block that states none is **kept**:
+ * plenty of instruments write no `##DATA TYPE` at all, and the file was opened
+ * by an infrared reader, so infrared is the right assumption where the file is
+ * silent. What is dropped is only a block that says it is something else.
+ * @param block - One spectrum of the analysis.
+ * @returns Whether to read it as infrared.
+ */
+function isInfrared(block: MeasurementXY): boolean {
+  const dataType = block.dataType?.toUpperCase();
+  if (dataType === undefined || dataType === '') return true;
+  if (dataType.includes('LINK')) return true;
+  for (const other of NOT_INFRARED) {
+    if (dataType.includes(other)) return false;
+  }
+  return true;
+}
+
+/**
+ * The data types that are certainly not an infrared spectrum.
+ *
+ * Named rather than matching `INFRARED` positively, so a file typed
+ * `IR SPECTRUM`, `FTIR` or `INFRARED SPECTRUM` — all three occur — is read
+ * without the list having to anticipate every spelling.
+ */
+const NOT_INFRARED = [
+  'RAMAN',
+  'NMR',
+  'MASS',
+  'UV',
+  'VISIBLE',
+  'CHROMATOGRAM',
+  'XRD',
+  'FLUORESCENCE',
+];
+
+/**
+ * Which value axis the file itself carried.
+ *
+ * Read off the original `y` variable's label rather than off `a` or `t`, which
+ * `ir-spectrum` adds to every spectrum and so say nothing about the source. A
+ * file whose label names neither is left unanswered rather than guessed at.
+ * @param block - One spectrum of the analysis.
+ * @returns The mode the file was written in, or `undefined` when it is unclear.
+ */
+function recordedMode(block: MeasurementXY): IrMode | undefined {
+  const label = `${block.variables.y?.label ?? ''} ${
+    block.variables.y?.units ?? ''
+  }`.toLowerCase();
+  if (label.includes('transmit')) return 'transmittance';
+  if (label.includes('absorb')) return 'absorbance';
+  return undefined;
+}
+
+/**
+ * The acquisition table, as the file's own records state it.
+ * @param block - One spectrum of the analysis.
+ * @returns The table, `null` when the file carried neither a title nor a record.
+ */
+function blockMeta(block: MeasurementXY): IrMeta | null {
+  const title = blockTitle(block);
+  const fields: IrMetaField[] = [];
+
+  for (const [label, value] of Object.entries(block.meta ?? {})) {
+    const written = typeof value === 'string' ? value.trim() : String(value);
+    if (written !== '') fields.push({ label, value: written });
+  }
+  if (block.dataType) {
+    fields.unshift({ label: 'Technique', value: block.dataType });
+  }
+
+  if (fields.length === 0 && !title) return null;
+  return { title: title ?? null, fields };
+}
+
+/** One row of the acquisition table, as `IrMeta` spells it. */
+type IrMetaField = IrMeta['fields'][number];

package/src/ir/core/assignBands.ts

@@ -0,0 +1,144 @@
+/**
+ * Matching picked bands against the correlation table.
+ *
+ * Every assignment whose range contains the band is kept, and that is the whole
+ * design: infrared assignment is not a lookup with one answer, and a viewer that
+ * showed only the best-fitting vibration would be asserting a structure the
+ * spectrum does not determine. A band at 1715 cm⁻¹ comes back as four
+ * candidates, ordered so the most specific claim reads first, and choosing
+ * between them is the chemist's job — which is what the `note` on each is for.
+ */
+
+import type { BandAssignment } from './bandAssignments.ts';
+import { BAND_ASSIGNMENTS } from './bandAssignments.ts';
+import type { IrBand } from './irBand.ts';
+
+/** One band, with everything it might be. */
+export interface AssignedBand {
+  /** The band that was picked. */
+  band: IrBand;
+  /**
+   * Every vibration whose range contains it, narrowest range first.
+   *
+   * Narrowest first because a narrow range is a more specific claim: at
+   * 1745 cm⁻¹ the ester's fifteen-wavenumber window says more than the
+   * anhydride's ninety, so it is the one worth reading first. Empty for a band
+   * in a region the table says nothing about, which is most of the fingerprint.
+   */
+  candidates: BandAssignment[];
+}
+
+/** How bands are assigned. */
+export interface AssignBandsOptions {
+  /**
+   * The table to match against.
+   * @default BAND_ASSIGNMENTS
+   */
+  assignments?: readonly BandAssignment[];
+  /**
+   * How far outside a range a band may still fall, in cm⁻¹.
+   *
+   * The ranges are conventional values rounded to tens, and a real band sits a
+   * few wavenumbers either side of where a table puts it — a ketone at 1703 is
+   * a ketone. Widening every range by a little is honest about that, where
+   * matching exactly would leave the strongest band in the spectrum unassigned
+   * for being two wavenumbers low.
+   * @default 5
+   */
+  tolerance?: number;
+  /**
+   * Whether a band whose strength disagrees with the table is still offered.
+   *
+   * It is, by default. A weak band where the table expects a strong one is
+   * evidence about concentration or about the assignment being wrong, and either
+   * way it is evidence the reader should see rather than have filtered away.
+   * @default true
+   */
+  keepStrengthMismatch?: boolean;
+}
+
+/**
+ * Assign every band, keeping every candidate.
+ * @param bands - The bands that were picked.
+ * @param options - The table, and how tightly to match it.
+ * @returns One entry per band, in the order the bands were given.
+ */
+export function assignBands(
+  bands: readonly IrBand[],
+  options: AssignBandsOptions = {},
+): AssignedBand[] {
+  const {
+    assignments = BAND_ASSIGNMENTS,
+    tolerance = 5,
+    keepStrengthMismatch = true,
+  } = options;
+
+  const assigned: AssignedBand[] = new Array<AssignedBand>(bands.length);
+  for (let index = 0; index < bands.length; index++) {
+    const band = bands[index] as IrBand;
+    const candidates: BandAssignment[] = [];
+    for (const assignment of assignments) {
+      if (
+        band.wavenumber < assignment.from - tolerance ||
+        band.wavenumber > assignment.to + tolerance
+      ) {
+        continue;
+      }
+      if (!keepStrengthMismatch && assignment.strength !== band.strength) {
+        continue;
+      }
+      candidates.push(assignment);
+    }
+    assigned[index] = {
+      band,
+      candidates: candidates.toSorted(byNarrowestRange),
+    };
+  }
+  return assigned;
+}
+
+/**
+ * How many of the bands the table had something to say about.
+ *
+ * Reported as a count rather than a fraction, because the denominator is the
+ * number of bands picked and that follows the picking threshold — a coverage
+ * percentage would move when somebody adjusted a slider, and read as the
+ * assignment having improved.
+ * @param assigned - The assigned bands.
+ * @returns How many carry at least one candidate.
+ */
+export function countAssigned(assigned: readonly AssignedBand[]): number {
+  let count = 0;
+  for (const entry of assigned) {
+    if (entry.candidates.length > 0) count++;
+  }
+  return count;
+}
+
+/**
+ * The name to write on a band, when there is room for one line.
+ *
+ * The narrowest candidate's group and vibration, which is the first of the
+ * ranked list — the same order the panel shows, so the chart and the table never
+ * disagree about which claim leads.
+ * @param entry - One assigned band.
+ * @returns The label, or `null` when nothing was assigned.
+ */
+export function bandLabel(entry: AssignedBand): string | null {
+  const best = entry.candidates[0];
+  if (best === undefined) return null;
+  return `${best.group} ${best.vibration}`;
+}
+
+/**
+ * Order two assignments by how specific they are, narrowest range first.
+ * @param first - One assignment.
+ * @param second - The other.
+ * @returns The comparison; equal widths keep the table's own order.
+ */
+function byNarrowestRange(
+  first: BandAssignment,
+  second: BandAssignment,
+): number {
+  return first.to - first.from - (second.to - second.from);
+}

package/src/ir/core/bandAssignments.ts

@@ -0,0 +1,329 @@
+/**
+ * The correlation table: which vibration a band at a given wavenumber may be.
+ *
+ * This is the infrared analogue of a fragment set — what a producer *claims*
+ * about a spectrum — with one difference that shapes the whole design: a mass
+ * fragment claims one m/z, while a vibration claims a **range**, and the ranges
+ * overlap heavily on purpose. A band at 1715 cm⁻¹ is an ester, an aldehyde, a
+ * ketone and a carboxylic acid until something else decides between them, and a
+ * table that returned one answer there would be inventing chemistry.
+ *
+ * The ranges are the conventional teaching values, rounded to the tens that a
+ * printed table uses. They are deliberately not narrowed to look precise: a
+ * conjugated ketone really does absorb below an unconjugated one, and a table
+ * that excluded it would read as ruling the ketone out.
+ */
+
+import type { IrBandStrength } from './irBand.ts';
+
+/** One vibration a band may be, as a correlation table states it. */
+export interface BandAssignment {
+  /** Identity, stable so a selection survives a re-pick. */
+  id: string;
+  /** The functional group it belongs to, as a chemist names it. */
+  group: string;
+  /** The motion itself: which bond, and how it moves. */
+  vibration: string;
+  /** Lowest wavenumber of the range, in cm⁻¹. */
+  from: number;
+  /** Highest wavenumber of the range, in cm⁻¹. */
+  to: number;
+  /** How strong the band usually is, in the table's own letters. */
+  strength: IrBandStrength;
+  /**
+   * What tells this assignment apart from the others it overlaps — the shape of
+   * the band, a partner band elsewhere, a region it must be absent from.
+   * @default undefined
+   */
+  note?: string;
+}
+
+/**
+ * The table, in ascending order of the low end of each range.
+ *
+ * Ordered so that a reader scanning it moves along the axis, and so that the
+ * fingerprint region below 1500 cm⁻¹ — where assignments are least decisive —
+ * sits together at the top rather than being interleaved with the diagnostic
+ * stretches above it.
+ */
+export const BAND_ASSIGNMENTS: readonly BandAssignment[] = [
+  {
+    id: 'c-br-stretch',
+    group: 'alkyl bromide',
+    vibration: 'C–Br stretch',
+    from: 500,
+    to: 600,
+    strength: 'S',
+  },
+  {
+    id: 'c-cl-stretch',
+    group: 'alkyl chloride',
+    vibration: 'C–Cl stretch',
+    from: 600,
+    to: 800,
+    strength: 'S',
+  },
+  {
+    id: 'aromatic-ch-oop',
+    group: 'arene',
+    vibration: 'C–H out-of-plane bend',
+    from: 690,
+    to: 900,
+    strength: 'S',
+    note: 'How many bands, and where, is what tells a substitution pattern apart',
+  },
+  {
+    id: 'alkene-ch-oop',
+    group: 'alkene',
+    vibration: '=C–H out-of-plane bend',
+    from: 890,
+    to: 990,
+    strength: 'S',
+    note: 'A terminal vinyl gives two, near 910 and 990',
+  },
+  {
+    id: 'c-o-stretch',
+    group: 'alcohol, ether, ester',
+    vibration: 'C–O stretch',
+    from: 1000,
+    to: 1300,
+    strength: 'S',
+    note: 'Strong and broad; an ester shows two, the higher one near 1200',
+  },
+  {
+    id: 'c-f-stretch',
+    group: 'alkyl fluoride',
+    vibration: 'C–F stretch',
+    from: 1000,
+    to: 1400,
+    strength: 'S',
+  },
+  {
+    id: 'c-n-stretch',
+    group: 'amine, amide',
+    vibration: 'C–N stretch',
+    from: 1080,
+    to: 1360,
+    strength: 'm',
+  },
+  {
+    id: 'nitro-symmetric',
+    group: 'nitro',
+    vibration: 'N–O symmetric stretch',
+    from: 1300,
+    to: 1390,
+    strength: 'S',
+    note: 'Never alone: the asymmetric partner sits near 1500–1560',
+  },
+  {
+    id: 'oh-bend',
+    group: 'alcohol',
+    vibration: 'O–H bend',
+    from: 1330,
+    to: 1430,
+    strength: 'm',
+  },
+  {
+    id: 'alkane-ch-bend',
+    group: 'alkane',
+    vibration: 'C–H bend',
+    from: 1370,
+    to: 1470,
+    strength: 'm',
+    note: 'A gem-dimethyl splits the 1380 band in two',
+  },
+  {
+    id: 'aromatic-cc-stretch',
+    group: 'arene',
+    vibration: 'C=C aromatic stretch',
+    from: 1450,
+    to: 1600,
+    strength: 'm',
+    note: 'Usually a pair, near 1500 and 1600',
+  },
+  {
+    id: 'nitro-asymmetric',
+    group: 'nitro',
+    vibration: 'N–O asymmetric stretch',
+    from: 1500,
+    to: 1560,
+    strength: 'S',
+  },
+  {
+    id: 'nh-bend',
+    group: 'amine, amide',
+    vibration: 'N–H bend',
+    from: 1550,
+    to: 1640,
+    strength: 'm',
+  },
+  {
+    id: 'alkene-cc-stretch',
+    group: 'alkene',
+    vibration: 'C=C stretch',
+    from: 1620,
+    to: 1680,
+    strength: 'w',
+    note: 'Weak, and absent altogether on a symmetric alkene',
+  },
+  {
+    id: 'amide-co-stretch',
+    group: 'amide',
+    vibration: 'C=O stretch',
+    from: 1630,
+    to: 1690,
+    strength: 'S',
+    note: 'The lowest carbonyl there is; look for N–H above 3300 to confirm',
+  },
+  {
+    id: 'acid-co-stretch',
+    group: 'carboxylic acid',
+    vibration: 'C=O stretch',
+    from: 1700,
+    to: 1725,
+    strength: 'S',
+    note: 'Confirmed by the very broad O–H between 2500 and 3300',
+  },
+  {
+    id: 'ketone-co-stretch',
+    group: 'ketone',
+    vibration: 'C=O stretch',
+    from: 1705,
+    to: 1725,
+    strength: 'S',
+    note: 'Conjugation drops it by about 30; a strained ring raises it',
+  },
+  {
+    id: 'aldehyde-co-stretch',
+    group: 'aldehyde',
+    vibration: 'C=O stretch',
+    from: 1720,
+    to: 1740,
+    strength: 'S',
+    note: 'Confirmed by the C–H pair near 2720 and 2820',
+  },
+  {
+    id: 'ester-co-stretch',
+    group: 'ester',
+    vibration: 'C=O stretch',
+    from: 1735,
+    to: 1750,
+    strength: 'S',
+    note: 'Confirmed by the strong C–O between 1000 and 1300',
+  },
+  {
+    id: 'acid-chloride-co-stretch',
+    group: 'acid chloride',
+    vibration: 'C=O stretch',
+    from: 1770,
+    to: 1815,
+    strength: 'S',
+  },
+  {
+    id: 'anhydride-co-stretch',
+    group: 'anhydride',
+    vibration: 'C=O stretch',
+    from: 1740,
+    to: 1830,
+    strength: 'S',
+    note: 'Two bands, about 60 apart, which is what names it',
+  },
+  {
+    id: 'nitrile-stretch',
+    group: 'nitrile',
+    vibration: 'C≡N stretch',
+    from: 2210,
+    to: 2260,
+    strength: 'm',
+    note: 'Sharp, and in a region almost nothing else occupies',
+  },
+  {
+    id: 'alkyne-cc-stretch',
+    group: 'alkyne',
+    vibration: 'C≡C stretch',
+    from: 2100,
+    to: 2260,
+    strength: 'w',
+    note: 'Weak, and absent on a symmetric internal alkyne',
+  },
+  {
+    id: 'aldehyde-ch-stretch',
+    group: 'aldehyde',
+    vibration: 'C–H stretch',
+    from: 2695,
+    to: 2830,
+    strength: 'm',
+    note: 'The diagnostic pair near 2720 and 2820',
+  },
+  {
+    id: 'acid-oh-stretch',
+    group: 'carboxylic acid',
+    vibration: 'O–H stretch',
+    from: 2500,
+    to: 3300,
+    strength: 'S',
+    note: 'Very broad — it runs under the C–H bands rather than beside them',
+  },
+  {
+    id: 'alkane-ch-stretch',
+    group: 'alkane',
+    vibration: 'C–H stretch',
+    from: 2850,
+    to: 3000,
+    strength: 'S',
+    note: 'Below 3000, which is what separates it from an alkene C–H',
+  },
+  {
+    id: 'alkene-ch-stretch',
+    group: 'alkene',
+    vibration: '=C–H stretch',
+    from: 3000,
+    to: 3100,
+    strength: 'm',
+    note: 'Above 3000, and never alone: the C=C sits near 1650',
+  },
+  {
+    id: 'aromatic-ch-stretch',
+    group: 'arene',
+    vibration: 'C–H stretch',
+    from: 3000,
+    to: 3100,
+    strength: 'm',
+  },
+  {
+    id: 'alkyne-ch-stretch',
+    group: 'alkyne',
+    vibration: '≡C–H stretch',
+    from: 3260,
+    to: 3330,
+    strength: 'S',
+    note: 'Sharp, where an O–H in the same place is broad',
+  },
+  {
+    id: 'alcohol-oh-stretch',
+    group: 'alcohol',
+    vibration: 'O–H stretch',
+    from: 3200,
+    to: 3600,
+    strength: 'S',
+    note: 'Broad when hydrogen bonded, which is nearly always',
+  },
+  {
+    id: 'nh-stretch',
+    group: 'amine, amide',
+    vibration: 'N–H stretch',
+    from: 3300,
+    to: 3500,
+    strength: 'm',
+    note: 'A primary amine gives two bands, a secondary one',
+  },
+  {
+    id: 'free-oh-stretch',
+    group: 'alcohol',
+    vibration: 'O–H stretch, not hydrogen bonded',
+    from: 3580,
+    to: 3650,
+    strength: 'm',
+    note: 'Sharp, and only in a dilute or gas-phase spectrum',
+  },
+];