react-cheminfo 0.65.0 → 0.66.0

package/src/ir/core/irSpectrum.ts

@@ -1,17 +1,22 @@
 /**
- * What an infrared spectrum is once it has been read, whatever it was read from.
+ * What a vibrational spectrum is once it has been read, whatever it was read
+ * from.
  *
- * One acquisition becomes one `IrSpectrum` carrying **both** value axes —
- * absorbance and percent transmittance — over one shared array of wavenumbers.
- * Both are held rather than one being derived on demand because `ir-spectrum`
- * already produces both when it reads a file: it adds an `a` and a `t` variable
- * to every spectrum whichever of the two the instrument wrote, so the conversion
- * happens once, in the one place that knows what the file's y axis meant. Holding
- * the answer means switching what is drawn costs nothing, and means the two
- * axes can never drift apart through a round trip.
+ * One infrared acquisition becomes one `IrSpectrum` carrying **both** value
+ * axes — absorbance and percent transmittance — over one shared array of
+ * wavenumbers. Both are held rather than one being derived on demand because
+ * `ir-spectrum` already produces both when it reads a file: it adds an `a` and
+ * a `t` variable to every spectrum whichever of the two the instrument wrote, so
+ * the conversion happens once, in the one place that knows what the file's y
+ * axis meant. Holding the answer means switching what is drawn costs nothing,
+ * and means the two axes can never drift apart through a round trip.
+ *
+ * A Raman acquisition carries its intensity instead, over its Raman shifts —
+ * also wavenumbers in cm⁻¹ — and neither infrared axis: there is no
+ * transmittance of scattered light to convert it to.
  *
  * The arrays are `Float64Array` and are replaced on a change, never written
- * into, since every consumer holds the same object by reference. An infrared
+ * into, since every consumer holds the same object by reference. A vibrational
  * spectrum is a few thousand points rather than a mass spectrum's few hundred
  * thousand, so holding two value axes costs nothing worth counting.
  */
@@ -30,8 +35,11 @@ import type { ChartDomain } from '../../chart/core/chartDomain.ts';
  */
 export type IrTrace = DataXY<Float64Array>;
 
-/** The formats a spectrum can have been read from. */
-export type IrFormat = 'jcamp' | 'spc' | 'text' | 'calculated';
+/**
+ * The formats a spectrum can have been read from. `wdf` is Renishaw's Raman
+ * format, which a host reads with its own parser and hands over.
+ */
+export type IrFormat = 'jcamp' | 'spc' | 'text' | 'wdf' | 'calculated';
 
 /**
  * Where a spectrum came from, and what the file said about the acquisition.
@@ -87,8 +95,11 @@ export interface IrMeta {
   fields: IrMetaField[];
 }
 
-/** Which value axis is being drawn and read. */
-export type IrMode = 'absorbance' | 'transmittance';
+/**
+ * Which value axis is being drawn and read: absorbance or percent
+ * transmittance for an infrared spectrum, intensity for a Raman one.
+ */
+export type IrMode = 'absorbance' | 'transmittance' | 'intensity';
 
 /** One spectrum as the viewer holds it. */
 export interface IrSpectrum {
@@ -99,19 +110,33 @@ export interface IrSpectrum {
   /** The colour it is drawn in. */
   color: string;
   /**
-   * The wavenumbers in cm⁻¹, **ascending**.
+   * The wavenumbers in cm⁻¹, **ascending** — of the light absorbed for an
+   * infrared spectrum, the Raman shift for a Raman one.
    *
-   * Ascending even though the axis is read from 4000 down to 400: which way the
-   * numbers run on screen is the chart's business, and every binary search and
-   * every extent taken off index zero downstream wants them in order. Reversing
-   * the data instead would make the drawing simpler once and everything else
-   * wrong.
+   * Ascending even though the infrared axis is read from 4000 down to 400:
+   * which way the numbers run on screen is the chart's business, and every
+   * binary search and every extent taken off index zero downstream wants them in
+   * order. Reversing the data instead would make the drawing simpler once and
+   * everything else wrong.
    */
   wavenumber: Float64Array;
-  /** Absorbance at each wavenumber, as `ir-spectrum` supplied it. */
-  absorbance: Float64Array;
-  /** Percent transmittance at each wavenumber, likewise. */
-  transmittance: Float64Array;
+  /**
+   * Absorbance at each wavenumber, as `ir-spectrum` supplied it. An infrared
+   * spectrum carries it beside `transmittance`.
+   * @default undefined
+   */
+  absorbance?: Float64Array;
+  /**
+   * Percent transmittance at each wavenumber, likewise.
+   * @default undefined
+   */
+  transmittance?: Float64Array;
+  /**
+   * Intensity at each Raman shift, which a Raman spectrum carries instead of
+   * the two infrared axes.
+   * @default undefined
+   */
+  intensity?: Float64Array;
   /** What the file said about the acquisition, `null` when it said nothing. */
   meta: IrMeta | null;
   /** Where it came from. */
@@ -145,11 +170,15 @@ export type IrDomain = ChartDomain;
  * render of every spectrum is a copy per frame for no gain.
  * @param spectrum - The spectrum.
  * @param mode - Which value axis is being drawn.
- * @returns The trace, sharing the spectrum's own arrays.
+ * @returns The trace, sharing the spectrum's own arrays, or `undefined` when the
+ * spectrum carries no such axis — a Raman spectrum has no absorbance.
  */
-export function traceOf(spectrum: IrSpectrum, mode: IrMode): IrTrace {
-  return {
-    x: spectrum.wavenumber,
-    y: mode === 'absorbance' ? spectrum.absorbance : spectrum.transmittance,
-  };
+export function traceOf(
+  spectrum: IrSpectrum,
+  mode: IrMode,
+): IrTrace | undefined {
+  const values = spectrum[mode];
+  return values === undefined
+    ? undefined
+    : { x: spectrum.wavenumber, y: values };
 }

package/src/ir/core/irState.ts

@@ -15,6 +15,8 @@
 
 import type { IrSidePanelId } from './irSidePanels.ts';
 import type { IrDomain, IrMode, IrSpectrum } from './irSpectrum.ts';
+import type { IrTechnique } from './irTechnique.ts';
+import { defaultIrMode, irModeFor, offersIrMode } from './irTechnique.ts';
 import type { PickBandsOptions } from './pickBands.ts';
 
 /** The document: what a file holds. */
@@ -48,7 +50,12 @@ export interface IrView {
 
 /** The workspace: how every spectrum is drawn, whichever ones are open. */
 export interface IrSettings {
-  /** Which value axis the spectra are read in. */
+  /**
+   * What the spectra were measured with. Chosen when the viewer opens and fixed
+   * from then on: a change asking for another is ignored.
+   */
+  technique: IrTechnique;
+  /** Which value axis the spectra are read in, always one the technique offers. */
   mode: IrMode;
   /** Whether the bands are picked at all. */
   pickBands: boolean;
@@ -108,6 +115,7 @@ export const DEFAULT_PICKING: PickBandsOptions = {
 
 /** The workspace a fresh viewer starts from. */
 export const DEFAULT_SETTINGS: IrSettings = {
+  technique: 'infrared',
   mode: 'transmittance',
   pickBands: true,
   picking: DEFAULT_PICKING,
@@ -116,6 +124,57 @@ export const DEFAULT_SETTINGS: IrSettings = {
   assignmentTolerance: 5,
 };
 
+/** What a viewer opens on. */
+export interface CreateIrStateOptions {
+  /**
+   * The spectra to open on.
+   * @default []
+   */
+  spectra?: IrSpectrum[];
+  /**
+   * The workspace to open in. Its `technique` is fixed for the life of the
+   * viewer, and its `mode` falls back to the technique's first when the
+   * technique does not offer it.
+   * @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;
+  const technique = settings?.technique ?? DEFAULT_SETTINGS.technique;
+  const opened: IrSettings = {
+    ...DEFAULT_SETTINGS,
+    technique,
+    mode: defaultIrMode(technique),
+  };
+  return {
+    data: { spectra: [...spectra] },
+    view: {
+      selectedId: spectra[0]?.id ?? null,
+      domain: null,
+      tool: 'read',
+      openPanelIds: [...(panelIds ?? DEFAULT_SIDE_PANELS)],
+      error: null,
+    },
+    settings: mergeIrSettings(opened, settings),
+  };
+}
+
 /**
  * Fold a change into the workspace, refusing what no chart survives.
  *
@@ -123,7 +182,9 @@ export const DEFAULT_SETTINGS: IrSettings = {
  * not yet a number — a lone minus sign, an empty box — and a limit of `NaN`
  * silently stops every label being drawn. So each is checked, and the current
  * value is kept where the new one is unusable rather than the field being
- * fought with while it is being typed in.
+ * fought with while it is being typed in. The technique is never changed, and a
+ * mode it does not offer is refused the same way: a Raman spectrum has no
+ * absorbance to draw.
  * @param current - The workspace in force.
  * @param change - What to change about it.
  * @returns The new workspace.
@@ -137,6 +198,10 @@ export function mergeIrSettings(
   return {
     ...current,
     ...change,
+    technique: current.technique,
+    mode: offersIrMode(current.technique, change.mode)
+      ? change.mode
+      : irModeFor(current.technique, current.mode),
     picking: { ...current.picking, ...change.picking },
     labelLimit: Number.isFinite(asked)
       ? Math.min(MAXIMUM_LABEL_LIMIT, Math.max(0, Math.round(asked)))

package/src/ir/core/irTechnique.ts

@@ -0,0 +1,115 @@
+/**
+ * Everything that differs between an infrared spectrum and a Raman one.
+ *
+ * Both are vibrational spectra over wavenumbers in cm⁻¹, and the viewer reads
+ * them the same way — one chart, one set of panels, one set of gestures — so
+ * what is left to differ is a handful of facts: which value axes a spectrum is
+ * read on, what the horizontal axis is called and which way it runs, whether the
+ * correlation table has anything to say about a band, and what a written file
+ * calls itself. They are gathered here for the reason `IR_MODE_RULES` gathers
+ * what differs between the value axes: a component that asked which technique
+ * it was drawing would be the first of many to ask, and they would come to
+ * disagree.
+ */
+
+import type { IrMode } from './irSpectrum.ts';
+
+/** What was measured: the light a sample absorbs, or the light it scatters. */
+export type IrTechnique = 'infrared' | 'raman';
+
+/** What is true of one technique. */
+export interface IrTechniqueRules {
+  /** How it is written inside a sentence; a sentence opening on it capitalises it. */
+  name: string;
+  /** The value axes a spectrum is read on, in the order a control offers them. */
+  modes: readonly IrMode[];
+  /** What the horizontal axis is called. */
+  xTitle: string;
+  /** Whether the horizontal axis runs from high at the left to low at the right. */
+  reverseX: boolean;
+  /** Whether the correlation table is asked what a band might be. */
+  assignments: boolean;
+  /** The `##DATA TYPE=` a written spectrum states when its file stated none. */
+  dataType: string;
+}
+
+/** The techniques, in the order a control would offer them. */
+export const IR_TECHNIQUES: readonly IrTechnique[] = ['infrared', 'raman'];
+
+/** How each technique behaves, every fact in one place. */
+export const IR_TECHNIQUE_RULES = {
+  infrared: {
+    name: 'infrared',
+    modes: ['transmittance', 'absorbance'],
+    xTitle: 'wavenumber (cm⁻¹)',
+    /**
+     * 4000 at the left and 400 at the right, which is how every infrared
+     * spectrum has been printed since the instruments scanned that way.
+     */
+    reverseX: true,
+    assignments: true,
+    dataType: 'INFRARED SPECTRUM',
+  },
+  raman: {
+    name: 'Raman',
+    /** One axis: a Raman spectrum is the light scattered, and nothing else. */
+    modes: ['intensity'],
+    xTitle: 'Raman shift (cm⁻¹)',
+    /** The shift grows away from the laser line, left to right. */
+    reverseX: false,
+    /**
+     * The table holds infrared group frequencies and infrared strengths. A
+     * vibration strong in one technique is often weak or silent in the other,
+     * so its candidates offered for a Raman band would claim what the table
+     * does not know.
+     */
+    assignments: false,
+    dataType: 'RAMAN SPECTRUM',
+  },
+} as const satisfies Record<IrTechnique, IrTechniqueRules>;
+
+/**
+ * The value axis a viewer of a technique opens on.
+ * @param technique - What was measured.
+ * @returns Its first mode.
+ */
+export function defaultIrMode(technique: IrTechnique): IrMode {
+  return IR_TECHNIQUE_RULES[technique].modes[0];
+}
+
+/**
+ * Whether a technique reads its spectra on a value axis.
+ * @param technique - What was measured.
+ * @param mode - The axis asked about; `undefined` is offered by none.
+ * @returns Whether the technique offers it.
+ */
+export function offersIrMode(
+  technique: IrTechnique,
+  mode: IrMode | undefined,
+): mode is IrMode {
+  if (mode === undefined) return false;
+  const modes: readonly IrMode[] = IR_TECHNIQUE_RULES[technique].modes;
+  return modes.includes(mode);
+}
+
+/**
+ * The value axis to read a technique's spectra on, given the one asked for.
+ * @param technique - What was measured.
+ * @param mode - The axis asked for, if any.
+ * @returns It when the technique offers it, the technique's first otherwise.
+ */
+export function irModeFor(technique: IrTechnique, mode?: IrMode): IrMode {
+  return offersIrMode(technique, mode) ? mode : defaultIrMode(technique);
+}
+
+/**
+ * The technique that reads its spectra on a value axis.
+ *
+ * Every axis belongs to exactly one technique, so the axis a file was written
+ * on says what was measured.
+ * @param mode - The value axis.
+ * @returns The technique offering it.
+ */
+export function irModeTechnique(mode: IrMode): IrTechnique {
+  return offersIrMode('raman', mode) ? 'raman' : 'infrared';
+}

package/src/ir/core/irTechniqueCommands.ts

@@ -0,0 +1,82 @@
+/**
+ * The commands each technique's viewer offers.
+ *
+ * A Raman viewer offers the infrared table less the commands with nothing to
+ * act on — one value axis is nothing to toggle, and no assignment is nothing to
+ * name — and words the rest without the absorbance and transmittance it does
+ * not have. It is built from the infrared table, so a command added there
+ * reaches both.
+ */
+
+import type { IrCommand, IrCommandId, IrCommandTable } from './irCommands.ts';
+import { irCommands } from './irCommands.ts';
+import type { IrTechnique } from './irTechnique.ts';
+import { IR_TECHNIQUE_RULES } from './irTechnique.ts';
+
+/**
+ * Whether a viewer of a technique offers a command at all.
+ * @param technique - What was measured.
+ * @param id - Which command.
+ * @returns False for the toggle of a technique with one value axis, and for
+ * the assignments of one the correlation table says nothing about.
+ */
+export function irCommandOffered(
+  technique: IrTechnique,
+  id: IrCommandId,
+): boolean {
+  const { modes, assignments } = IR_TECHNIQUE_RULES[technique];
+  if (id === 'toggleMode') return modes.length > 1;
+  if (id === 'toggleAssignments') return assignments;
+  return true;
+}
+
+/**
+ * Everything a viewer of a technique offers, in the order it is reached for.
+ * @param technique - What was measured.
+ * @returns The table; for infrared, `irCommands` itself.
+ */
+export function irCommandsFor(technique: IrTechnique): IrCommandTable {
+  return COMMAND_TABLES[technique];
+}
+
+/** Where the chart is, for a gesture made anywhere on it. */
+const OVER_THE_CHART = 'Over the chart';
+
+/** How a Raman viewer words the commands it shares with infrared. */
+const RAMAN_WORDING: Partial<Record<IrCommandId, Partial<IrCommand>>> = {
+  about: { title: 'About the Raman viewer' },
+  documentation: {
+    description: 'How the bands are read, and every gesture.',
+  },
+  readTool: {
+    description:
+      'A drag narrows the Raman shift axis. Released past the baseline, it takes the intensity axis with it.',
+    gestures: [{ title: OVER_THE_CHART, shortcuts: ['Drag'] }],
+  },
+  boxTool: {
+    description:
+      'A drag zooms to exactly the rectangle it sweeps out, both axes at once — for looking into a baseline or a shoulder rather than across the spectrum.',
+  },
+  zoomIn: {
+    description:
+      'Brings the weak bands up, scaling the intensity axis about zero.',
+    gestures: [{ title: OVER_THE_CHART, shortcuts: ['Scroll wheel'] }],
+  },
+  zoomOut: {
+    gestures: [{ title: OVER_THE_CHART, shortcuts: ['Scroll wheel'] }],
+  },
+  togglePicking: {
+    description:
+      'Finds the bands of the selected spectrum, marks them on the chart and lists them.',
+  },
+};
+
+/** The command table of each technique. */
+const COMMAND_TABLES: Record<IrTechnique, IrCommandTable> = {
+  infrared: irCommands,
+  raman: Object.fromEntries(
+    (Object.keys(irCommands) as IrCommandId[])
+      .filter((id) => irCommandOffered('raman', id))
+      .map((id) => [id, { ...irCommands[id], ...RAMAN_WORDING[id] }]),
+  ),
+};

package/src/ir/core/pickBands.ts

@@ -3,11 +3,12 @@
  *
  * Everything here is the two things that call needs and does not have: a
  * `MeasurementXY` built out of the arrays the viewer holds, and the decision to
- * pick on **absorbance** rather than on transmittance. That second one is the
- * only judgement in the file and it is not a preference — peak picking finds
- * maxima, and a band is a maximum in absorbance but a *minimum* in transmittance,
- * so picking on transmittance would return the flat baseline between the bands
- * and miss every band there is.
+ * pick an infrared spectrum on **absorbance** rather than on transmittance. That
+ * second one is the only judgement in the file and it is not a preference — peak
+ * picking finds maxima, and a band is a maximum in absorbance but a *minimum* in
+ * transmittance, so picking on transmittance would return the flat baseline
+ * between the bands and miss every band there is. A Raman spectrum is picked on
+ * its intensity, by `ramanBands`, with the same picker.
  */
 
 import type { MeasurementXY } from 'cheminfo-types';
@@ -15,7 +16,10 @@ import { autoPeakPicking } from 'ir-spectrum';
 import { xMaxValue, xMinValue } from 'ml-spectra-processing';
 
 import type { IrBand, IrBandStrength } from './irBand.ts';
+import { bandHeight } from './irBand.ts';
 import type { IrSpectrum } from './irSpectrum.ts';
+import type { PeakPickingOptions } from './ramanBands.ts';
+import { ramanBands } from './ramanBands.ts';
 
 /** How the bands are picked. */
 export interface PickBandsOptions {
@@ -86,20 +90,50 @@ export function pickBands(
   } = options;
   if (spectrum.wavenumber.length < 2) return [];
 
-  const picked = autoPeakPicking(measurementOf(spectrum), {
-    // Absorbance, because a band is a maximum there and a minimum in the other.
-    yVariable: 'a',
+  const picking: PeakPickingOptions = {
     minMaxRatio: minRelativeHeight,
     minPeakWidth,
     ...(from === undefined ? {} : { from }),
     ...(to === undefined ? {} : { to }),
-  });
+  };
+  // A spectrum carrying an intensity is a Raman one; any other is infrared.
+  const bands =
+    spectrum.intensity === undefined
+      ? infraredBands(spectrum, picking)
+      : ramanBands(spectrum, spectrum.intensity, picking);
+
+  const kept =
+    limit === undefined || bands.length <= limit
+      ? bands
+      : bands.toSorted(byDescendingHeight).slice(0, limit);
+  return kept.toSorted(byAscendingWavenumber);
+}
+
+/**
+ * The bands of an infrared spectrum, picked on its absorbance.
+ * @param spectrum - The spectrum to pick from.
+ * @param picking - Where to pick, and how finely.
+ * @returns The bands, in the order they were found; none when the spectrum
+ * carries only one of its two axes, since the strength is read off the other.
+ */
+function infraredBands(
+  spectrum: IrSpectrum,
+  picking: PeakPickingOptions,
+): IrBand[] {
+  const { id, wavenumber, absorbance, transmittance } = spectrum;
+  if (absorbance === undefined || transmittance === undefined) return [];
+
+  const picked = autoPeakPicking(
+    measurementOf(wavenumber, absorbance, transmittance),
+    // Absorbance, because a band is a maximum there and a minimum in the other.
+    { yVariable: 'a', ...picking },
+  );
 
   const bands: IrBand[] = [];
   for (const peak of picked) {
     if (!Number.isFinite(peak.wavenumber)) continue;
     bands.push({
-      spectrumId: spectrum.id,
+      spectrumId: id,
       wavenumber: peak.wavenumber,
       absorbance: peak.absorbance,
       // `ConvertedPeak.transmittance` is a fraction where the spectrum's own
@@ -109,12 +143,7 @@ export function pickBands(
       strength: peak.kind as IrBandStrength,
     });
   }
-
-  const kept =
-    limit === undefined || bands.length <= limit
-      ? bands
-      : bands.toSorted(byDescendingAbsorbance).slice(0, limit);
-  return kept.toSorted(byAscendingWavenumber);
+  return bands;
 }
 
 /**
@@ -124,17 +153,23 @@ export function pickBands(
  * letter is worked out from: without them the conversion assumes a spectrum
  * running the full 0 to 100 percent, and every band of a shallow ATR trace that
  * never leaves the eighties comes back weak.
- * @param spectrum - The spectrum the viewer holds.
+ * @param wavenumber - The wavenumbers, ascending.
+ * @param absorbance - Absorbance at each.
+ * @param transmittance - Percent transmittance at each.
  * @returns A measurement carrying all three variables.
  */
-function measurementOf(spectrum: IrSpectrum): MeasurementXY {
-  const transmittance = {
+function measurementOf(
+  wavenumber: Float64Array,
+  absorbance: Float64Array,
+  transmittance: Float64Array,
+): MeasurementXY {
+  const percent = {
     label: 'Transmittance (%)',
     units: '%',
     symbol: 't' as const,
-    data: spectrum.transmittance,
-    min: xMinValue(spectrum.transmittance),
-    max: xMaxValue(spectrum.transmittance),
+    data: transmittance,
+    min: xMinValue(transmittance),
+    max: xMaxValue(transmittance),
   };
   return {
     variables: {
@@ -142,20 +177,20 @@ function measurementOf(spectrum: IrSpectrum): MeasurementXY {
         label: 'Wavenumber',
         units: '1/cm',
         symbol: 'x',
-        data: spectrum.wavenumber,
+        data: wavenumber,
       },
       // `y` is required of every measurement, and stands for whichever axis was
       // recorded. Nothing here reads it — the picking is told to use `a` and the
       // strength letter is read off `t` — so it carries the transmittance rather
       // than a third copy of anything.
-      y: transmittance,
+      y: percent,
       a: {
         label: 'Absorbance',
         units: '',
         symbol: 'a',
-        data: spectrum.absorbance,
+        data: absorbance,
       },
-      t: transmittance,
+      t: percent,
     },
   };
 }
@@ -166,8 +201,8 @@ function measurementOf(spectrum: IrSpectrum): MeasurementXY {
  * @param second - The other.
  * @returns The comparison.
  */
-function byDescendingAbsorbance(first: IrBand, second: IrBand): number {
-  return second.absorbance - first.absorbance;
+function byDescendingHeight(first: IrBand, second: IrBand): number {
+  return bandHeight(second) - bandHeight(first);
 }
 
 /**