react-cheminfo 0.28.0 → 0.29.0

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());
+}

package/src/ir/core/downloadSpectra.ts

@@ -0,0 +1,57 @@
+/**
+ * Handing spectra over as a file, from the list they are drawn from.
+ *
+ * Kept apart from `spectrumJcamp.ts` so that what a file holds can be tested
+ * without a DOM, and so that a page wanting the text for something other than a
+ * download — a POST to an ELN, a zip of a whole session — reaches for the writer
+ * and not for this.
+ */
+
+import { downloadText } from '../../download/core/downloadText.ts';
+import { sanitizeFileName } from '../../download/core/sanitizeFileName.ts';
+
+import type { IrMode, IrSpectrum } from './irSpectrum.ts';
+import {
+  JCAMP_EXTENSION,
+  JCAMP_MIME_TYPE,
+  irSpectraToJcamp,
+  irSpectrumToJcamp,
+} from './spectrumJcamp.ts';
+
+/**
+ * Download one spectrum, named after what the list calls it.
+ * @param spectrum - The spectrum.
+ * @param mode - The axis being read, used when the file named none.
+ */
+export function downloadIrSpectrum(spectrum: IrSpectrum, mode: IrMode): void {
+  downloadText(
+    irSpectrumToJcamp(spectrum, mode),
+    `${sanitizeFileName(spectrum.name, 'spectrum')}${JCAMP_EXTENSION}`,
+    JCAMP_MIME_TYPE,
+  );
+}
+
+/**
+ * Download the whole list as one file.
+ *
+ * A list of one is saved under that spectrum's own name, since the file is that
+ * spectrum: a chemist who has one spectrum open and asks the panel for it should
+ * not have to work out which of their downloads `spectra.jdx` was.
+ * @param spectra - The spectra, in the order the list holds them.
+ * @param mode - The axis being read, used for a spectrum whose file named none.
+ */
+export function downloadIrSpectra(
+  spectra: readonly IrSpectrum[],
+  mode: IrMode,
+): void {
+  const only = spectra.length === 1 ? spectra[0] : undefined;
+  if (only !== undefined) {
+    downloadIrSpectrum(only, mode);
+    return;
+  }
+  downloadText(
+    irSpectraToJcamp(spectra, mode),
+    `spectra${JCAMP_EXTENSION}`,
+    JCAMP_MIME_TYPE,
+  );
+}

package/src/ir/core/fromJcamp.ts

@@ -0,0 +1,70 @@
+/**
+ * Read a JCAMP-DX file into infrared spectra.
+ *
+ * `ir-spectrum` does the reading, which matters for one reason worth stating: it
+ * adds an absorbance and a percent transmittance variable to every spectrum it
+ * builds, whichever of the two the instrument wrote. So a file exported as
+ * transmittance and one exported as absorbance arrive carrying both axes, and
+ * nothing downstream has to know which it was — or to do the conversion itself.
+ */
+
+import type { TextData } from 'cheminfo-types';
+import { fromJcamp as irAnalysis } from 'ir-spectrum';
+
+import { describeSource, errorMessage } from '../../error/core/index.ts';
+
+import type { LoadedIrSpectrum } from './analysisSpectra.ts';
+import { analysisSpectra } from './analysisSpectra.ts';
+
+/** How a JCAMP is read. */
+export interface IrJcampReadOptions {
+  /**
+   * The file's name, carried onto every spectrum it produced.
+   * @default undefined
+   */
+  fileName?: string;
+}
+
+/**
+ * Read every infrared spectrum a JCAMP-DX file holds.
+ *
+ * All of them, never the first: a JCAMP is a container, and an instrument
+ * exporting a sample beside its background writes both as blocks of one file.
+ * Taking only the first would quietly drop the block the chemist exported the
+ * file for, and would do it without an error, which is the worst way to lose
+ * data.
+ * @param data - The file, as bytes or as text.
+ * @param options - The file's name.
+ * @returns One entry per block, in the order the file wrote them.
+ * @throws {Error} When the file holds no readable spectrum, or when the
+ * converter gave up on it.
+ */
+export function fromJcamp(
+  data: TextData,
+  options: IrJcampReadOptions = {},
+): LoadedIrSpectrum[] {
+  const { fileName } = options;
+
+  let spectra: LoadedIrSpectrum[];
+  try {
+    const origin: LoadedIrSpectrum['origin'] = { format: 'jcamp' };
+    if (fileName !== undefined) origin.fileName = fileName;
+    spectra = analysisSpectra(irAnalysis(data), origin);
+  } catch (error) {
+    // The converter's own words are kept because they name the record it
+    // stopped on, which is more than anything written here could say — but they
+    // are said about nothing, and a chemist who has just dropped eleven files
+    // needs to know which of them this is.
+    throw new Error(
+      `${describeSource(fileName)} could not be read as JCAMP-DX — the converter stopped on it with: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  }
+
+  if (spectra.length === 0) {
+    throw new Error(
+      `${describeSource(fileName)} was read as JCAMP-DX but holds no infrared spectrum — no block in it carries an XY data record with at least two points.`,
+    );
+  }
+  return spectra;
+}

package/src/ir/core/fromSpc.ts

@@ -0,0 +1,61 @@
+/**
+ * Read a Thermo Galactic SPC file into infrared spectra.
+ *
+ * `ir-spectrum` does the reading, through `spc-parser`, and adds both value axes
+ * exactly as it does for a JCAMP — so an SPC and a JCAMP of the same measurement
+ * reach the viewer indistinguishable but for their `origin`.
+ */
+
+import { fromSPC as irAnalysis } from 'ir-spectrum';
+
+import { describeSource, errorMessage } from '../../error/core/index.ts';
+
+import type { LoadedIrSpectrum } from './analysisSpectra.ts';
+import { analysisSpectra } from './analysisSpectra.ts';
+
+/** How an SPC file is read. */
+export interface IrSpcReadOptions {
+  /**
+   * The file's name, carried onto every spectrum it produced.
+   * @default undefined
+   */
+  fileName?: string;
+}
+
+/**
+ * Read every infrared spectrum an SPC file holds.
+ *
+ * SPC is a multi-file format in its own right — one file can carry a whole
+ * kinetic series — so every subfile becomes a spectrum, for the same reason
+ * every JCAMP block does.
+ * @param data - The file, as bytes.
+ * @param options - The file's name.
+ * @returns One entry per subfile, in the order the file wrote them.
+ * @throws {Error} When the file holds no readable spectrum, or when the parser
+ * gave up on it.
+ */
+export function fromSpc(
+  data: ArrayBuffer | Uint8Array,
+  options: IrSpcReadOptions = {},
+): LoadedIrSpectrum[] {
+  const { fileName } = options;
+
+  let spectra: LoadedIrSpectrum[];
+  try {
+    const origin: LoadedIrSpectrum['origin'] = { format: 'spc' };
+    if (fileName !== undefined) origin.fileName = fileName;
+    spectra = analysisSpectra(irAnalysis(data), origin);
+  } catch (error) {
+    throw new Error(
+      `${describeSource(fileName)} could not be read as SPC — the parser stopped on it with: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  }
+
+  if (spectra.length === 0) {
+    throw new Error(
+      `${describeSource(fileName)} was read as SPC but holds no infrared spectrum — no subfile in it carries at least two points.`,
+    );
+  }
+  return spectra;
+}

package/src/ir/core/index.ts

@@ -0,0 +1,113 @@
+/**
+ * What an infrared spectrum is, and everything true of one that draws nothing.
+ *
+ * Reading a file, picking the bands, saying what each band might be, writing
+ * the spectra back out as JCAMP — none of it needs React, so a script that
+ * assigns a directory of spectra loads none.
+ *
+ * What is here is only what is true of infrared: that the axis runs from 4000
+ * down to 400, that a spectrum is read either as absorbance or as percent
+ * transmittance and a band points the other way in each, and that a wavenumber
+ * maps to a range of vibrations rather than to one. Nothing here knows what a
+ * glycan is, and nothing should: an infrared spectrum answers for whatever was
+ * put in the beam.
+ */
+
+export type { LoadedIrSpectrum } from './analysisSpectra.ts';
+export { analysisSpectra } from './analysisSpectra.ts';
+export type { AssignBandsOptions, AssignedBand } from './assignBands.ts';
+export { assignBands, bandLabel, countAssigned } from './assignBands.ts';
+export type { BandAssignment } from './bandAssignments.ts';
+export { BAND_ASSIGNMENTS } from './bandAssignments.ts';
+export type { BandLabelPlan, BandLabelPlanOptions } from './bandLabelPlan.ts';
+export { planBandLabels } from './bandLabelPlan.ts';
+export { detectIrFormat } from './detectIrFormat.ts';
+export { downloadIrSpectra, downloadIrSpectrum } from './downloadSpectra.ts';
+export type { IrJcampReadOptions } from './fromJcamp.ts';
+export type { IrSpcReadOptions } from './fromSpc.ts';
+export type { IrBand, IrBandStrength } from './irBand.ts';
+export { sameIrBand } from './irBand.ts';
+export type {
+  IrCommand,
+  IrCommandHandlers,
+  IrCommandId,
+  IrGesture,
+  IrShortcut,
+  RunIrCommand,
+} from './irCommands.ts';
+export { irCommandLabel, irCommands } from './irCommands.ts';
+export {
+  LABEL_HEADROOM,
+  X_DOMAIN_PADDING,
+  Y_DOMAIN_PADDING,
+  fittedTo,
+  fullDomain,
+} from './irDomain.ts';
+export type { IrEditorHandle, ZoomToBandOptions } from './irEditorApi.ts';
+export {
+  ABSORBANCE_DECIMALS,
+  TRANSMITTANCE_DECIMALS,
+  formatIrValue,
+  formatWavenumber,
+  shortModeLabel,
+} from './irFormat.ts';
+export {
+  IR_MODES,
+  IR_MODE_RULES,
+  bandsPointDown,
+  boxZoomOnly,
+  otherIrMode,
+  yAxisRules,
+  yAxisTitle,
+  zoomGestures,
+} from './irMode.ts';
+export type { CreateIrStateOptions, IrAction } from './irReducer.ts';
+export { createIrState, irReducer } from './irReducer.ts';
+export type {
+  IrDomain,
+  IrFormat,
+  IrMeta,
+  IrMetaField,
+  IrMode,
+  IrOrigin,
+  IrSpectrum,
+  IrTrace,
+} from './irSpectrum.ts';
+export { traceOf } from './irSpectrum.ts';
+export type {
+  IrData,
+  IrSettings,
+  IrState,
+  IrTool,
+  IrView,
+  PartialIrState,
+} from './irState.ts';
+export {
+  DEFAULT_LABEL_LIMIT,
+  DEFAULT_PICKING,
+  DEFAULT_SETTINGS,
+  DEFAULT_SIDE_PANEL,
+  DEFAULT_SIDE_PANELS,
+  MAXIMUM_LABEL_LIMIT,
+  isIrWindow,
+  mergeIrSettings,
+} from './irState.ts';
+export type {
+  LoadIrSpectraOptions,
+  LoadIrSpectraResult,
+} from './loadIrSpectra.ts';
+export { loadIrSpectra } from './loadIrSpectra.ts';
+export { BAND_HIT_RADIUS, nearestBandAt } from './nearestBand.ts';
+export type { PickBandsOptions } from './pickBands.ts';
+export { pickBands } from './pickBands.ts';
+export {
+  DEFAULT_DATA_TYPE,
+  JCAMP_EXTENSION,
+  JCAMP_MIME_TYPE,
+  irSpectraToJcamp,
+  irSpectrumToJcamp,
+} from './spectrumJcamp.ts';
+export type { ToIrSpectrumOptions } from './toIrSpectrum.ts';
+export { toIrSpectra, toIrSpectrum } from './toIrSpectrum.ts';
+export type { IrSidePanelId } from './irSidePanels.ts';
+export { irSidePanels } from './irSidePanels.ts';

package/src/ir/core/irBand.ts

@@ -0,0 +1,57 @@
+/**
+ * One band picked out of a spectrum.
+ *
+ * A band is the infrared analogue of a mass spectrum's peak: the thing a chemist
+ * points at, names, and reads a functional group off. It carries both value axes
+ * for the same reason the spectrum does — the band a reader sees at 30 percent
+ * transmittance and the one a table calls strongly absorbing are one band, and
+ * making the caller convert to find out would be the conversion this package
+ * does not do.
+ */
+
+/**
+ * How strong a band is, in the letters a correlation table uses.
+ *
+ * `w` weak, `m` medium, `S` strong — `ir-spectrum` decides which from where the
+ * band sits between the spectrum's own extremes, so the letters are relative to
+ * the spectrum in hand rather than to an absolute absorbance. That is what a
+ * printed table means by them too.
+ */
+export type IrBandStrength = 'w' | 'm' | 'S';
+
+/** One band picked out of one spectrum. */
+export interface IrBand {
+  /** Identity of the spectrum it was picked from. */
+  spectrumId: string;
+  /** Where it sits, in cm⁻¹. */
+  wavenumber: number;
+  /** Its absorbance, which is what it was picked as a maximum of. */
+  absorbance: number;
+  /** Its percent transmittance, the same band read the other way up. */
+  transmittance: number;
+  /** How strong it is, relative to the spectrum it came from. */
+  strength: IrBandStrength;
+}
+
+/**
+ * Whether two bands are the same band.
+ *
+ * The wavenumber is compared exactly, and that is not an oversight: both numbers
+ * were read out of the same picked band, so either they are the very same
+ * measurement or they are two different bands. A tolerance here would declare a
+ * carbonyl pair thirty wavenumbers apart to be one band.
+ * @param current - What was last reported.
+ * @param next - What would be reported now.
+ * @returns Whether the report can be skipped.
+ */
+export function sameIrBand(
+  current: IrBand | null,
+  next: IrBand | null,
+): boolean {
+  if (current === next) return true;
+  if (current === null || next === null) return false;
+  return (
+    current.spectrumId === next.spectrumId &&
+    current.wavenumber === next.wavenumber
+  );
+}