react-cheminfo 0.28.0 → 0.30.0

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',
+  },
+];

package/src/ir/core/bandLabelPlan.ts

@@ -0,0 +1,194 @@
+/**
+ * Where every band's mark and label go, worked out before anything is drawn.
+ *
+ * Kept apart from the component because it is the part worth testing: which
+ * bands get a label, which way their lines stack, how far a crowded label may
+ * slide from the band it names, and which are dropped rather than drawn
+ * somewhere misleading. All of that is arithmetic over numbers, and none of it
+ * needs a DOM.
+ */
+
+import { layoutAnnotationBoxes } from '../../chart/core/boxLayout.ts';
+import type { PlotRect } from '../../chart/core/chartGeometry.ts';
+import type { ChartScale } from '../../chart/core/chartScale.ts';
+import { chartPixel } from '../../chart/core/chartScale.ts';
+import { PEAK_LABEL } from '../../chart/core/chartTheme.ts';
+import { labelStackBaselines } from '../../chart/core/labelStack.ts';
+
+import type { AssignedBand } from './assignBands.ts';
+import { bandLabel } from './assignBands.ts';
+import type { IrBand } from './irBand.ts';
+import { formatWavenumber } from './irFormat.ts';
+import { bandsPointDown } from './irMode.ts';
+import type { IrMode } from './irSpectrum.ts';
+
+/** One band, and where everything about it is drawn. */
+export interface BandLabelPlan {
+  /** The band itself. */
+  band: IrBand;
+  /** Where its tip sits horizontally, in user units of the SVG. */
+  tipX: number;
+  /** Where its tip sits vertically. */
+  tipY: number;
+  /**
+   * Where its label is centred, `NaN` when the label was dropped for having
+   * been slid too far from the band to belong to it.
+   */
+  labelX: number;
+  /** The baseline of each line of the label, in the order the lines are given. */
+  baselines: Float64Array;
+  /** What the label says, farthest line from the band first. */
+  lines: string[];
+}
+
+/** What the plan is worked out from. */
+export interface BandLabelPlanOptions {
+  /** The bands to name, with whatever the table said about them. */
+  assigned: readonly AssignedBand[];
+  /** Where the plot sits inside the SVG. */
+  plot: PlotRect;
+  /** The wavenumber axis as it is currently zoomed. */
+  xScale: ChartScale;
+  /** The value axis as it is currently zoomed. */
+  yScale: ChartScale;
+  /** Which value axis is being drawn, which decides which way labels stack. */
+  mode: IrMode;
+  /**
+   * Whether each label names the assignment as well as the wavenumber.
+   *
+   * The assignment is the longer line by far — `carboxylic acid C=O stretch`
+   * against `1710` — so a chart showing a dozen bands is legible with the
+   * wavenumbers alone and unreadable with both.
+   * @default false
+   */
+  showAssignments?: boolean;
+  /**
+   * At most how many bands to name.
+   *
+   * Marks are drawn on every band regardless; this only bounds the labels, since
+   * a mark costs three pixels and a two-line label costs sixty.
+   * @default 12
+   */
+  limit?: number;
+}
+
+/**
+ * Work out where every band's label goes.
+ *
+ * Only the bands inside the window are considered, so a zoom into one region
+ * gives its bands the whole width to be named in rather than sharing it with the
+ * hundred outside the plot.
+ *
+ * The strongest bands win the labels when there are more than `limit`, because a
+ * strong band is the one a reader is looking for; but they come back in ascending
+ * wavenumber — the order `pickBands` returns and the order a band table lists —
+ * rather than in the order they were chosen. Which is right to left on screen,
+ * since the axis is drawn backwards; nothing depends on it, because the declutter
+ * sweep sorts by pixel itself.
+ * @param options - The bands, the axes and how much to say.
+ * @returns One plan per band that is inside the window, in axis order.
+ */
+export function planBandLabels(options: BandLabelPlanOptions): BandLabelPlan[] {
+  const {
+    assigned,
+    plot,
+    xScale,
+    yScale,
+    mode,
+    showAssignments = false,
+    limit = 12,
+  } = options;
+
+  const inside: AssignedBand[] = [];
+  for (const entry of assigned) {
+    const pixelX = chartPixel(xScale, entry.band.wavenumber);
+    if (!Number.isFinite(pixelX)) continue;
+    if (pixelX < plot.left || pixelX > plot.right) continue;
+    inside.push(entry);
+  }
+
+  const named =
+    inside.length <= limit
+      ? inside
+      : inside
+          .toSorted(
+            (first, second) => second.band.absorbance - first.band.absorbance,
+          )
+          .slice(0, limit)
+          .toSorted(
+            (first, second) => first.band.wavenumber - second.band.wavenumber,
+          );
+
+  const centres = new Float64Array(named.length);
+  for (let index = 0; index < named.length; index++) {
+    centres[index] = chartPixel(
+      xScale,
+      (named[index] as AssignedBand).band.wavenumber,
+    );
+  }
+  const placed = layoutAnnotationBoxes(
+    centres,
+    [plot.left, plot.right],
+    LABEL_WIDTH,
+    LABEL_GAP,
+  );
+
+  const down = bandsPointDown(mode);
+  const plans: BandLabelPlan[] = new Array<BandLabelPlan>(named.length);
+  for (let index = 0; index < named.length; index++) {
+    const entry = named[index] as AssignedBand;
+    const lines = labelLines(entry, showAssignments);
+    const tipY = chartPixel(
+      yScale,
+      mode === 'absorbance' ? entry.band.absorbance : entry.band.transmittance,
+    );
+    plans[index] = {
+      band: entry.band,
+      tipX: centres[index] as number,
+      tipY,
+      labelX: placed[index] as number,
+      // The stack hangs away from the baseline: below the tip of a transmittance
+      // band, which dips downwards, and above the tip of an absorbance one.
+      baselines: labelStackBaselines(
+        tipY,
+        lines.length,
+        [plot.top, plot.bottom],
+        down,
+      ),
+      lines,
+    };
+  }
+  return plans;
+}
+
+/**
+ * How wide a label is taken to be while it is being spaced out.
+ *
+ * A wavenumber is four digits and an assignment is far wider, but the width used
+ * for spacing is the wavenumber's: spacing on the longer line would push every
+ * label so far apart that only three fit, and an assignment is only ever shown
+ * when a handful of bands are named.
+ */
+export const LABEL_WIDTH = 34;
+
+/** The clear space kept between two neighbouring labels. */
+export const LABEL_GAP = 6;
+
+/** How far the mark reaches from the tip of a band, in pixels. */
+export const BAND_MARK = PEAK_LABEL.topMark;
+
+/**
+ * What one band's label says.
+ * @param entry - The band and whatever the table said about it.
+ * @param showAssignments - Whether to name the assignment as well.
+ * @returns The lines, farthest from the band first, never empty.
+ */
+function labelLines(entry: AssignedBand, showAssignments: boolean): string[] {
+  const lines = [formatWavenumber(entry.band.wavenumber)];
+  if (!showAssignments) return lines;
+  const label = bandLabel(entry);
+  // The assignment goes nearest the band, under the wavenumber, so the eye
+  // travels from the mark to what it is claimed to be.
+  if (label !== null) lines.push(label);
+  return lines;
+}

package/src/ir/core/detectIrFormat.ts

@@ -0,0 +1,139 @@
+/**
+ * Which reader a dropped infrared file belongs to, decided from the file itself.
+ *
+ * The extension is the least reliable thing about a spectrum file: instruments
+ * export JCAMP as `.txt`, LIMS systems rename everything to `.dat`, and a user
+ * pasting into a text box has no extension at all. So the content decides and
+ * the name is consulted only when the content stayed silent.
+ */
+
+import type { IrFormat } from './irSpectrum.ts';
+
+/**
+ * How much of the file the decision is taken on.
+ *
+ * Every marker looked for here sits in the header — the SPC flag pair in the
+ * first two bytes, `##TITLE=` at the very top of a JCAMP. Reading further would
+ * only cost a decode of the whole file.
+ */
+const HEADER_BYTES = 4096;
+
+/**
+ * Extensions that name a format outright, once the content has said nothing.
+ *
+ * A `Map` rather than an object, because the key comes off a file name the user
+ * chose: `spectrum.constructor` read out of an object literal answers with a
+ * function inherited from `Object.prototype`, which is neither a format nor
+ * `undefined` and so passes every check made of it.
+ */
+const EXTENSIONS = new Map<string, IrFormat>([
+  ['jdx', 'jcamp'],
+  ['dx', 'jcamp'],
+  ['jcamp', 'jcamp'],
+  ['spc', 'spc'],
+  ['txt', 'text'],
+  ['csv', 'text'],
+  ['tsv', 'text'],
+  ['xy', 'text'],
+  ['dpt', 'text'],
+]);
+
+/**
+ * The one decoder the header is read through, kept because a drop of fifty
+ * files would otherwise build a hundred of them for four kilobytes each.
+ */
+const DECODER = new TextDecoder();
+
+/**
+ * Decide what a dropped file is, from its first bytes and only then its name.
+ *
+ * Returns `'unknown'` rather than guessing `'text'` for the two cases the
+ * readers cannot survive: nothing at all, and bytes that are plainly not text.
+ * Handing either to the text reader produces an empty spectrum and a message
+ * about missing columns, which sends whoever dropped the file looking in the
+ * wrong place.
+ * @param data - The file, or the pasted text.
+ * @param fileName - Its name, when it has one.
+ * @returns The format, or `'unknown'` when nothing in the file names one.
+ */
+export function detectIrFormat(
+  data: Uint8Array | string,
+  fileName?: string,
+): IrFormat | 'unknown' {
+  if (isSpc(data)) return 'spc';
+
+  const header = stripByteOrderMark(readHeader(data)).trimStart();
+  if (header.startsWith('##')) return 'jcamp';
+
+  const named = formatFromExtension(fileName);
+  if (named !== undefined) return named;
+  if (header.length === 0) return 'unknown';
+  // A binary file the SPC check did not claim decodes to replacement characters;
+  // a `.dpt` export of two columns decodes to digits. Telling them apart on the
+  // decode is what stops a stray binary from reaching the text reader.
+  if (header.includes('\uFFFD') || header.includes('\0')) return 'unknown';
+  return 'text';
+}
+
+/**
+ * Whether the first bytes are an SPC file header.
+ *
+ * The second byte is the format version, and Thermo Galactic only ever wrote
+ * three: `0x4B` for the new LSB-first format, `0x4C` for MSB-first, and `0x4D`
+ * for the old format. Checked before anything is decoded, because putting a
+ * binary file through a UTF-8 decode turns its header into replacement
+ * characters that happen to match nothing — a right answer reached by luck.
+ * @param data - The file, or the pasted text.
+ * @returns Whether it looks like SPC.
+ */
+function isSpc(data: Uint8Array | string): boolean {
+  // A pasted string is never SPC: the bytes would not have survived the decode.
+  if (typeof data === 'string' || data.length < 2) return false;
+  return SPC_VERSIONS.has(data[1] as number);
+}
+
+/**
+ * The format versions Thermo Galactic ever wrote, as the second byte states it.
+ *
+ * `0x4B` is the current LSB-first format, `0x4C` the MSB-first one, and `0x4D`
+ * the old format still exported by instruments of a certain age.
+ */
+const SPC_VERSIONS = new Set([0x4b, 0x4c, 0x4d]);
+
+/**
+ * The first bytes of the file, as text.
+ * @param data - The file, or the pasted text.
+ * @param length - How many bytes to read, defaulting to the whole header.
+ * @returns The decoded prefix; a byte sequence cut in half at the end decodes
+ * to a replacement character, which no marker looked for here contains.
+ */
+function readHeader(data: Uint8Array | string, length = HEADER_BYTES): string {
+  if (typeof data === 'string') return data.slice(0, length);
+  return DECODER.decode(data.subarray(0, length));
+}
+
+/**
+ * Drop a leading UTF-8 byte order mark.
+ *
+ * This is the whole reason the header is normalised before it is tested: a
+ * `U+FEFF` in front of `##TITLE=` makes a plain `startsWith('##')` fail, and a
+ * BOM-prefixed JCAMP then goes silently to the text reader, which reads its
+ * records as unparsable lines and reports two columns of nothing.
+ * @param header - The decoded prefix.
+ * @returns The prefix without its mark.
+ */
+function stripByteOrderMark(header: string): string {
+  return header.startsWith('\uFEFF') ? header.slice(1) : header;
+}
+
+/**
+ * The format a file name claims, used only once the content has said nothing.
+ * @param fileName - The name, when the file has one.
+ * @returns The format, or `undefined` when the extension names none.
+ */
+function formatFromExtension(fileName?: string): IrFormat | undefined {
+  if (fileName === undefined) return undefined;
+  const extension = fileName.split('.').pop();
+  if (extension === undefined || extension === fileName) return undefined;
+  return EXTENSIONS.get(extension.toLowerCase());
+}