react-cheminfo 0.65.0 → 0.67.0

package/src/ir/core/irState.ts

@@ -13,8 +13,10 @@
  * a stale band is then impossible rather than merely unlikely.
  */
 
-import type { IrSidePanelId } from './irSidePanels.ts';
+import type { IrPanelId, 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. */
@@ -40,15 +42,23 @@ export interface IrView {
   domain: IrDomain | null;
   /** Which tool a drag across the chart is running. */
   tool: IrTool;
-  /** The side panels that are open, in the order their icons are stacked. */
-  openPanelIds: IrSidePanelId[];
+  /**
+   * The side panels that are open: the viewer's own and any a host added. An id
+   * no panel on offer answers to opens nothing.
+   */
+  openPanelIds: IrPanelId[];
   /** Why the last action was refused, `null` as soon as one succeeds. */
   error: string | null;
 }
 
 /** 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 +118,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 +127,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, the viewer's own or a host's.
+   * @default DEFAULT_SIDE_PANELS
+   */
+  panelIds?: readonly IrPanelId[];
+}
+
+/**
+ * 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 +185,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 +201,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);
 }
 
 /**

package/src/ir/core/ramanBands.ts

@@ -0,0 +1,105 @@
+/**
+ * Finding the bands of a Raman spectrum, with the picker infrared bands are
+ * found with.
+ *
+ * `autoPeakPicking` from `ir-spectrum` is `common-spectrum`'s, which runs
+ * `ml-gsd` over whichever variable it is pointed at — the picker
+ * `raman-spectrum` itself exports — and converts each peak to absorbance and
+ * transmittance on top. A Raman band is a maximum of intensity, so the picker is
+ * pointed at the intensity and only where each peak sits is read back: the
+ * conversion speaks two axes a Raman spectrum does not have.
+ *
+ * The strength letter follows the rule `ir-spectrum` applies to transmittance,
+ * applied to intensity: where the band's top sits between the spectrum's own
+ * lowest and highest intensity — below a third weak, below two thirds medium,
+ * strong above.
+ */
+
+import type { MeasurementXY } from 'cheminfo-types';
+import { autoPeakPicking } from 'ir-spectrum';
+import { xFindClosestIndex, xMinMaxValues } from 'ml-spectra-processing';
+
+import type { IrBand, IrBandStrength } from './irBand.ts';
+import type { IrSpectrum } from './irSpectrum.ts';
+
+/** What the picker is asked, whichever technique it picks for. */
+export type PeakPickingOptions = NonNullable<
+  Parameters<typeof autoPeakPicking>[1]
+>;
+
+/**
+ * The bands of a Raman spectrum, picked on its intensity.
+ * @param spectrum - The spectrum to pick from.
+ * @param intensity - Its intensity, which the bands are maxima of.
+ * @param picking - Where to pick, and how finely.
+ * @returns The bands, in the order they were found.
+ */
+export function ramanBands(
+  spectrum: IrSpectrum,
+  intensity: Float64Array,
+  picking: PeakPickingOptions,
+): IrBand[] {
+  const { id, wavenumber } = spectrum;
+  const picked = autoPeakPicking(measurementOf(wavenumber, intensity), {
+    ...picking,
+    yVariable: 'y',
+  });
+  const { min, max } = xMinMaxValues(intensity);
+
+  const bands: IrBand[] = [];
+  for (const peak of picked) {
+    if (!Number.isFinite(peak.wavenumber)) continue;
+    // The peak sits on a sample, so its intensity is read off that sample.
+    const value = intensity[xFindClosestIndex(wavenumber, peak.wavenumber)];
+    if (value === undefined) continue;
+    bands.push({
+      spectrumId: id,
+      wavenumber: peak.wavenumber,
+      intensity: value,
+      strength: strengthOf(value, min, max),
+    });
+  }
+  return bands;
+}
+
+/**
+ * How strong a band is, from where its top sits in the spectrum's range.
+ * @param value - The band's intensity.
+ * @param lowest - The spectrum's lowest intensity.
+ * @param highest - Its highest.
+ * @returns The letter a correlation table would use.
+ */
+function strengthOf(
+  value: number,
+  lowest: number,
+  highest: number,
+): IrBandStrength {
+  const position = (value - lowest) / (highest - lowest);
+  if (position < WEAK_BELOW) return 'w';
+  if (position < MEDIUM_BELOW) return 'm';
+  return 'S';
+}
+
+/** Below this fraction of the spectrum's range a band is weak. */
+const WEAK_BELOW = 0.33;
+
+/** Below this one it is medium, and strong from here up. */
+const MEDIUM_BELOW = 0.66;
+
+/**
+ * The spectrum as `ir-spectrum` wants it: the shifts, and the intensity as `y`.
+ * @param shift - The Raman shifts, ascending.
+ * @param intensity - The intensity at each.
+ * @returns The measurement.
+ */
+function measurementOf(
+  shift: Float64Array,
+  intensity: Float64Array,
+): MeasurementXY {
+  return {
+    variables: {
+      x: { label: 'Raman shift', units: '1/cm', symbol: 'x', data: shift },
+      y: { label: 'Intensity', units: '', symbol: 'y', data: intensity },
+    },
+  };
+}