react-cheminfo 0.65.0 → 0.66.0

package/src/ir/core/analysisSpectra.ts

@@ -14,14 +14,31 @@ 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. */
+/**
+ * One spectrum as a reader produced it, before it is named and coloured.
+ *
+ * The readers of this package produce infrared spectra, which carry absorbance
+ * and transmittance; a host reading a Raman file builds one carrying its
+ * intensity instead.
+ */
 export interface LoadedIrSpectrum {
-  /** The wavenumbers, ascending. */
+  /** The wavenumbers — or, for a Raman spectrum, the Raman shifts — ascending. */
   wavenumber: Float64Array;
-  /** Absorbance at each. */
-  absorbance: Float64Array;
-  /** Percent transmittance at each. */
-  transmittance: Float64Array;
+  /**
+   * Absorbance at each, for an infrared spectrum.
+   * @default undefined
+   */
+  absorbance?: Float64Array;
+  /**
+   * Percent transmittance at each, for an infrared spectrum.
+   * @default undefined
+   */
+  transmittance?: Float64Array;
+  /**
+   * Intensity at each, for a Raman spectrum.
+   * @default undefined
+   */
+  intensity?: Float64Array;
   /** What the file said about the acquisition, `null` when it said nothing. */
   meta: IrMeta | null;
   /** Where it came from. */
@@ -96,10 +113,9 @@ export function analysisSpectra(
   return spectra;
 }
 
-/** The three arrays of one spectrum, in ascending wavenumber. */
-type SortedTraces = Pick<
-  LoadedIrSpectrum,
-  'wavenumber' | 'absorbance' | 'transmittance'
+/** The three arrays of one infrared spectrum, in ascending wavenumber. */
+type SortedTraces = Required<
+  Pick<LoadedIrSpectrum, 'wavenumber' | 'absorbance' | 'transmittance'>
 >;
 
 /**

package/src/ir/core/bandLabelPlan.ts

@@ -18,6 +18,7 @@ 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 { bandHeight, bandValue } from './irBand.ts';
 import { formatWavenumber } from './irFormat.ts';
 import { bandsPointDown } from './irMode.ts';
 import type { IrMode } from './irSpectrum.ts';
@@ -99,12 +100,15 @@ export function planBandLabels(options: BandLabelPlanOptions): BandLabelPlan[] {
     limit = 12,
   } = options;
 
-  const inside: AssignedBand[] = [];
+  const inside: NamedBand[] = [];
   for (const entry of assigned) {
+    // A band with no value on the axis being read has no tip to hang from.
+    const value = bandValue(entry.band, mode);
+    if (value === undefined) continue;
     const pixelX = chartPixel(xScale, entry.band.wavenumber);
     if (!Number.isFinite(pixelX)) continue;
     if (pixelX < plot.left || pixelX > plot.right) continue;
-    inside.push(entry);
+    inside.push({ entry, value });
   }
 
   const named =
@@ -112,18 +116,20 @@ export function planBandLabels(options: BandLabelPlanOptions): BandLabelPlan[] {
       ? inside
       : inside
           .toSorted(
-            (first, second) => second.band.absorbance - first.band.absorbance,
+            (first, second) =>
+              bandHeight(second.entry.band) - bandHeight(first.entry.band),
           )
           .slice(0, limit)
           .toSorted(
-            (first, second) => first.band.wavenumber - second.band.wavenumber,
+            (first, second) =>
+              first.entry.band.wavenumber - second.entry.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,
+      (named[index] as NamedBand).entry.band.wavenumber,
     );
   }
   const placed = layoutAnnotationBoxes(
@@ -136,12 +142,9 @@ export function planBandLabels(options: BandLabelPlanOptions): BandLabelPlan[] {
   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 { entry, value } = named[index] as NamedBand;
     const lines = labelLines(entry, showAssignments);
-    const tipY = chartPixel(
-      yScale,
-      mode === 'absorbance' ? entry.band.absorbance : entry.band.transmittance,
-    );
+    const tipY = chartPixel(yScale, value);
     plans[index] = {
       band: entry.band,
       tipX: centres[index] as number,
@@ -161,6 +164,14 @@ export function planBandLabels(options: BandLabelPlanOptions): BandLabelPlan[] {
   return plans;
 }
 
+/** A band inside the window, with its value on the axis being read. */
+interface NamedBand {
+  /** The band and whatever the table said about it. */
+  entry: AssignedBand;
+  /** Where its tip is, on the value axis. */
+  value: number;
+}
+
 /**
  * How wide a label is taken to be while it is being spaced out.
  *

package/src/ir/core/index.ts

@@ -10,7 +10,8 @@
  * 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.
+ * put in the beam. A Raman spectrum is the one other technique held, and what
+ * differs for it is in `IR_TECHNIQUE_RULES`.
  */
 
 export type { LoadedIrSpectrum } from './analysisSpectra.ts';
@@ -26,16 +27,22 @@ 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 { bandHeight, bandValue, sameIrBand } from './irBand.ts';
 export type {
   IrCommand,
   IrCommandHandlers,
   IrCommandId,
+  IrCommandTable,
   IrGesture,
   IrShortcut,
   RunIrCommand,
 } from './irCommands.ts';
-export { irCommandLabel, irCommands } from './irCommands.ts';
+export {
+  irCommandEntryLabel,
+  irCommandLabel,
+  irCommands,
+} from './irCommands.ts';
+export { irCommandOffered, irCommandsFor } from './irTechniqueCommands.ts';
 export {
   LABEL_HEADROOM,
   X_DOMAIN_PADDING,
@@ -46,9 +53,11 @@ export {
 export type { IrEditorHandle, ZoomToBandOptions } from './irEditorApi.ts';
 export {
   ABSORBANCE_DECIMALS,
+  INTENSITY_DIGITS,
   TRANSMITTANCE_DECIMALS,
   formatIrValue,
   formatWavenumber,
+  formatWavenumberRange,
   shortModeLabel,
 } from './irFormat.ts';
 export {
@@ -61,8 +70,8 @@ export {
   yAxisTitle,
   zoomGestures,
 } from './irMode.ts';
-export type { CreateIrStateOptions, IrAction } from './irReducer.ts';
-export { createIrState, irReducer } from './irReducer.ts';
+export type { IrAction } from './irReducer.ts';
+export { irReducer } from './irReducer.ts';
 export type {
   IrDomain,
   IrFormat,
@@ -75,6 +84,7 @@ export type {
 } from './irSpectrum.ts';
 export { traceOf } from './irSpectrum.ts';
 export type {
+  CreateIrStateOptions,
   IrData,
   IrSettings,
   IrState,
@@ -89,9 +99,19 @@ export {
   DEFAULT_SIDE_PANEL,
   DEFAULT_SIDE_PANELS,
   MAXIMUM_LABEL_LIMIT,
+  createIrState,
   isIrWindow,
   mergeIrSettings,
 } from './irState.ts';
+export type { IrTechnique, IrTechniqueRules } from './irTechnique.ts';
+export {
+  IR_TECHNIQUES,
+  IR_TECHNIQUE_RULES,
+  defaultIrMode,
+  irModeFor,
+  irModeTechnique,
+  offersIrMode,
+} from './irTechnique.ts';
 export type {
   LoadIrSpectraOptions,
   LoadIrSpectraResult,

package/src/ir/core/irBand.ts

@@ -1,21 +1,24 @@
 /**
  * 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.
+ * A band is the vibrational analogue of a mass spectrum's peak: the thing a
+ * chemist points at, names, and reads a functional group off. An infrared band
+ * carries both value axes for the same reason its 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. A Raman band carries its intensity.
  */
 
+import type { IrMode } from './irSpectrum.ts';
+
 /**
  * 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.
+ * `w` weak, `m` medium, `S` strong — decided 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 value. That is what a printed table means by
+ * them too. `ir-spectrum` decides it for an infrared band from its
+ * transmittance, and the same rule is applied to a Raman band's intensity.
  */
 export type IrBandStrength = 'w' | 'm' | 'S';
 
@@ -25,10 +28,21 @@ export interface IrBand {
   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;
+  /**
+   * Its absorbance, which an infrared band is picked as a maximum of.
+   * @default undefined
+   */
+  absorbance?: number;
+  /**
+   * Its percent transmittance, the same infrared band read the other way up.
+   * @default undefined
+   */
+  transmittance?: number;
+  /**
+   * Its intensity, which a Raman band is picked as a maximum of.
+   * @default undefined
+   */
+  intensity?: number;
   /** How strong it is, relative to the spectrum it came from. */
   strength: IrBandStrength;
 }
@@ -55,3 +69,27 @@ export function sameIrBand(
     current.wavenumber === next.wavenumber
   );
 }
+
+/**
+ * A band's value on the axis being read.
+ * @param band - The band.
+ * @param mode - Which value axis is being read.
+ * @returns The value, or `undefined` when its spectrum carries no such axis.
+ */
+export function bandValue(band: IrBand, mode: IrMode): number | undefined {
+  return band[mode];
+}
+
+/**
+ * How tall a band stands, which is what a cut to the strongest bands ranks by.
+ *
+ * The value it was picked as a maximum of: its absorbance for an infrared band,
+ * its intensity for a Raman one. Never its transmittance, in which a stronger
+ * band is a smaller number.
+ * @param band - The band.
+ * @returns The height, or negative infinity for a band carrying neither, so it
+ * ranks last.
+ */
+export function bandHeight(band: IrBand): number {
+  return band.absorbance ?? band.intensity ?? Number.NEGATIVE_INFINITY;
+}

package/src/ir/core/irCommands.ts

@@ -10,6 +10,9 @@
  * this one, because a module that exports a component and a constant together
  * cannot be hot reloaded — `react-refresh/only-export-components` is the rule
  * that says so, and the split is the fix rather than the exception.
+ *
+ * This is the infrared table; `irTechniqueCommands.ts` derives the Raman one
+ * from it.
  */
 
 /** The key a command answers to. */
@@ -134,6 +137,9 @@ export const irCommands = {
 /** Identity of one of the commands the viewer offers. */
 export type IrCommandId = keyof typeof irCommands;
 
+/** The commands a viewer offers, in the order they are reached for. */
+export type IrCommandTable = Readonly<Partial<Record<IrCommandId, IrCommand>>>;
+
 /** What to do when each command is run, as the shell wires them. */
 export type IrCommandHandlers = Partial<
   Record<IrCommandId, (() => void) | undefined>
@@ -148,7 +154,15 @@ export type RunIrCommand = (id: IrCommandId) => void;
  * @returns The title, and the key in parentheses when it has one.
  */
 export function irCommandLabel(id: IrCommandId): string {
-  const entry = irCommands[id] as IrCommand;
+  return irCommandEntryLabel(irCommands[id]);
+}
+
+/**
+ * A command's title, with its key in parentheses when it has one.
+ * @param entry - The command, as a table words it.
+ * @returns The label.
+ */
+export function irCommandEntryLabel(entry: IrCommand): string {
   const key = entry.shortcut?.label?.[0] ?? entry.shortcut?.keys[0];
   return key === undefined ? entry.title : `${entry.title} (${key})`;
 }

package/src/ir/core/irDomain.ts

@@ -5,9 +5,10 @@
  * something usable when it is handed nothing at all — a chart with no data is
  * still mounted, still measured, and still builds its scales.
  *
- * The x window is in ascending wavenumbers even though the axis is drawn from
- * 4000 down to 400: which way round it is read is the chart's business, and
- * every piece of arithmetic that moves a window expects its ends in order.
+ * The x window is in ascending wavenumbers even though the infrared axis is
+ * drawn from 4000 down to 400: which way round it is read is the chart's
+ * business, and every piece of arithmetic that moves a window expects its ends
+ * in order.
  */
 
 import { xMaxValue, xMinValue } from 'ml-spectra-processing';
@@ -57,9 +58,8 @@ export function fullDomain(
   const extent =
     traceExtent(spectra, mode, false) ?? traceExtent(spectra, mode, true);
   if (extent === null) {
-    return mode === 'absorbance'
-      ? { x: [400, 4000], y: [0, 1] }
-      : { x: [400, 4000], y: [0, 100] };
+    // A percentage runs to 100; absorbance and intensity are open at the top.
+    return { x: [400, 4000], y: mode === 'transmittance' ? [0, 100] : [0, 1] };
   }
 
   const { xMinimum, xMaximum, yMinimum, yMaximum } = extent;
@@ -135,7 +135,9 @@ function traceExtent(
   for (const spectrum of spectra) {
     if (!spectrum.visible) continue;
     if (!includeExcluded && spectrum.excludeFromDomain) continue;
-    const { x, y } = traceOf(spectrum, mode);
+    const trace = traceOf(spectrum, mode);
+    if (trace === undefined) continue;
+    const { x, y } = trace;
     if (x.length === 0 || y.length === 0) continue;
     // The wavenumber ends are read off the first and last sample rather than
     // searched for: the array is ascending by construction, so a scan would walk

package/src/ir/core/irFormat.ts

@@ -6,6 +6,8 @@
  * row that calls it 1714.6 read as two bands.
  */
 
+import { formatTrimmed } from '../../format/core/numbers.ts';
+
 import type { IrMode } from './irSpectrum.ts';
 
 /** How many decimals an absorbance is written to. */
@@ -14,6 +16,9 @@ export const ABSORBANCE_DECIMALS = 3;
 /** How many a percent transmittance is written to. */
 export const TRANSMITTANCE_DECIMALS = 1;
 
+/** How many significant digits an intensity is written to. */
+export const INTENSITY_DIGITS = 4;
+
 /**
  * Write a wavenumber the way a chemist quotes one.
  *
@@ -35,23 +40,51 @@ export function formatWavenumber(wavenumber: number): string {
  * Three decimals for an absorbance and one for a percent transmittance, which is
  * roughly the same precision expressed two ways — an absorbance of 0.001 and a
  * transmittance of 0.2 percent are both about where a real spectrum's noise
- * sits.
+ * sits. An intensity is counts from one instrument and a fraction of the
+ * strongest band from another, so no count of decimals suits it: it keeps
+ * `INTENSITY_DIGITS` significant digits instead.
  * @param value - The value.
  * @param mode - Which axis it is in.
  * @returns The number as a string, without its unit.
  */
 export function formatIrValue(value: number, mode: IrMode): string {
   if (!Number.isFinite(value)) return '';
-  return value.toFixed(
-    mode === 'absorbance' ? ABSORBANCE_DECIMALS : TRANSMITTANCE_DECIMALS,
-  );
+  const { decimals } = VALUE_FORMATS[mode];
+  return decimals === undefined
+    ? formatTrimmed(value, { significant: INTENSITY_DIGITS })
+    : value.toFixed(decimals);
 }
 
 /**
  * What the value axis is called where there is room for one word.
  * @param mode - Which axis is being drawn.
- * @returns `A` or `%T`, as a spectrum is annotated by hand.
+ * @returns `A`, `%T` or `I`, as a spectrum is annotated by hand.
  */
 export function shortModeLabel(mode: IrMode): string {
-  return mode === 'absorbance' ? 'A' : '%T';
+  return VALUE_FORMATS[mode].symbol;
 }
+
+/**
+ * The range a spectrum covers, written in the order its axis is read.
+ * @param wavenumbers - Its wavenumbers, ascending.
+ * @param reversed - Whether the axis runs from high to low, as infrared's does.
+ * @returns `4000–400 cm⁻¹` on a reversed axis, `100–3200 cm⁻¹` on one that is
+ * not, and an empty string for a spectrum with no point.
+ */
+export function formatWavenumberRange(
+  wavenumbers: Float64Array,
+  reversed: boolean,
+): string {
+  const lowest = wavenumbers[0];
+  const highest = wavenumbers.at(-1);
+  if (lowest === undefined || highest === undefined) return '';
+  const [first, last] = reversed ? [highest, lowest] : [lowest, highest];
+  return `${formatWavenumber(first)}–${formatWavenumber(last)} cm⁻¹`;
+}
+
+/** How each value axis is written: its symbol, and its count of decimals. */
+const VALUE_FORMATS: Record<IrMode, { symbol: string; decimals?: number }> = {
+  transmittance: { symbol: '%T', decimals: TRANSMITTANCE_DECIMALS },
+  absorbance: { symbol: 'A', decimals: ABSORBANCE_DECIMALS },
+  intensity: { symbol: 'I' },
+};

package/src/ir/core/irMode.ts

@@ -1,14 +1,14 @@
 /**
- * Everything that differs between reading a spectrum as absorbance and reading
- * it as percent transmittance.
+ * Everything that differs between reading a spectrum as absorbance, as percent
+ * transmittance, or — for a Raman spectrum — as intensity.
  *
- * The two are the same measurement drawn upside down, and nearly every
+ * The first two are the same measurement drawn upside down, and nearly every
  * difference between them is one of a handful of facts: what the axis is called,
  * where its baseline is, whether that baseline is held in the window, which way
  * a band points, and which zoom gestures are worth answering. Gathering them
  * here is what keeps the switch from being an `if (mode === …)` in the chart,
  * the tracker, the band marks, the zoom and the fitting separately, where they
- * would eventually disagree.
+ * would eventually disagree. Intensity is one more entry of the same facts.
  *
  * **No conversion happens here, or anywhere in this package.** `ir-spectrum`
  * adds both an absorbance and a transmittance variable to every spectrum it
@@ -24,9 +24,14 @@ import type {
 } from '../../chart/core/chartDomain.ts';
 
 import type { IrMode } from './irSpectrum.ts';
+import type { IrTechnique } from './irTechnique.ts';
+import { IR_TECHNIQUE_RULES, irModeTechnique } from './irTechnique.ts';
 
-/** The two ways a spectrum is read, in the order a control offers them. */
-export const IR_MODES: readonly IrMode[] = ['transmittance', 'absorbance'];
+/**
+ * The two ways an infrared spectrum is read, in the order a control offers
+ * them.
+ */
+export const IR_MODES: readonly IrMode[] = IR_TECHNIQUE_RULES.infrared.modes;
 
 /**
  * How each mode behaves, every fact in one place.
@@ -115,6 +120,22 @@ export const IR_MODE_RULES = {
      */
     wheelZoom: true,
   },
+  intensity: {
+    title: 'intensity',
+    /** No light scattered is a real floor, as no light absorbed is. */
+    baseline: 0,
+    /** Not held in a dragged window, for the reason absorbance gives. */
+    keepBaseline: false,
+    /** A Raman band stands up out of the baseline under it. */
+    bandsPointDown: false,
+    /**
+     * Both drags are worth having: intensity is open at the top and its weak
+     * bands lie against zero, as absorbance's do.
+     */
+    boxZoomOnly: false,
+    /** The wheel scales the axis about zero, bringing a weak band up. */
+    wheelZoom: true,
+  },
 } as const satisfies Record<
   IrMode,
   {
@@ -199,10 +220,21 @@ export function bandsPointDown(mode: IrMode): boolean {
 }
 
 /**
- * The other mode, for a control that toggles between the two.
+ * The next mode, for a control that toggles between them.
+ *
+ * It never leaves the technique: an infrared viewer goes back and forth
+ * between its two axes, and a Raman one, reading intensity alone, stays where
+ * it is.
  * @param mode - The mode in force.
- * @returns The one to switch to.
+ * @param technique - The technique whose modes are toggled through. Defaults to
+ * the one that reads `mode`.
+ * @returns The one to switch to: the technique's first when `mode` is not one
+ * of its own.
  */
-export function otherIrMode(mode: IrMode): IrMode {
-  return mode === 'absorbance' ? 'transmittance' : 'absorbance';
+export function otherIrMode(
+  mode: IrMode,
+  technique: IrTechnique = irModeTechnique(mode),
+): IrMode {
+  const modes: readonly IrMode[] = IR_TECHNIQUE_RULES[technique].modes;
+  return modes[(modes.indexOf(mode) + 1) % modes.length] ?? mode;
 }

package/src/ir/core/irReducer.ts

@@ -16,12 +16,7 @@
 import type { IrSidePanelId } from './irSidePanels.ts';
 import type { IrDomain, IrSpectrum } from './irSpectrum.ts';
 import type { IrSettings, IrState, IrTool, PartialIrState } from './irState.ts';
-import {
-  DEFAULT_SETTINGS,
-  DEFAULT_SIDE_PANELS,
-  isIrWindow,
-  mergeIrSettings,
-} from './irState.ts';
+import { isIrWindow, mergeIrSettings } from './irState.ts';
 
 /** Everything that can be asked of the viewer. */
 export type IrAction =
@@ -41,49 +36,6 @@ export type IrAction =
   | { type: 'loadState'; state: PartialIrState }
   | { type: 'clear' };
 
-/** What a viewer opens on. */
-export interface CreateIrStateOptions {
-  /**
-   * The spectra to open on.
-   * @default []
-   */
-  spectra?: IrSpectrum[];
-  /**
-   * The workspace to open in.
-   * @default DEFAULT_SETTINGS
-   */
-  settings?: Partial<IrSettings>;
-  /**
-   * The panels open to begin with.
-   * @default DEFAULT_SIDE_PANELS
-   */
-  panelIds?: IrSidePanelId[];
-}
-
-/**
- * The state a viewer opens with.
- *
- * The panel list is spread rather than stored by reference: a caller's array is
- * the caller's to mutate, and a viewer holding it would find its open panels
- * changing under it.
- * @param options - What it opens on.
- * @returns The state.
- */
-export function createIrState(options: CreateIrStateOptions = {}): IrState {
-  const { spectra = [], settings, panelIds } = options;
-  return {
-    data: { spectra: [...spectra] },
-    view: {
-      selectedId: spectra[0]?.id ?? null,
-      domain: null,
-      tool: 'read',
-      openPanelIds: [...(panelIds ?? DEFAULT_SIDE_PANELS)],
-      error: null,
-    },
-    settings: mergeIrSettings(DEFAULT_SETTINGS, settings),
-  };
-}
-
 /**
  * Fold one action into the state.
  * @param state - The state in force.