react-cheminfo 0.64.1 → 0.66.0

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

package/src/ir/core/spectrumJcamp.ts

@@ -7,7 +7,8 @@
  * turned inside out, and a bare column of numbers leaves whoever opens it next
  * to guess which. `##YUNITS=` states it, and `ir-spectrum` reads it back and
  * derives the other axis from it, so a spectrum written here returns carrying
- * both.
+ * both. A Raman spectrum is written as its intensity, under a `##DATA TYPE=`
+ * that says it is Raman.
  *
  * The points are written as an `##PEAK TABLE=` of explicit `x y` pairs rather
  * than as a compressed `##XYDATA=` record. An XYDATA record states a first
@@ -20,6 +21,7 @@
 import { fromJSON } from 'convert-to-jcamp';
 
 import type { IrMode, IrSpectrum } from './irSpectrum.ts';
+import { IR_TECHNIQUE_RULES, irModeTechnique } from './irTechnique.ts';
 
 /** The extension a written spectrum is saved under. */
 export const JCAMP_EXTENSION = '.jdx';
@@ -27,8 +29,8 @@ export const JCAMP_EXTENSION = '.jdx';
 /** What a JCAMP-DX file is served as. */
 export const JCAMP_MIME_TYPE = 'chemical/x-jcamp-dx';
 
-/** How the technique is named when the file that was read named nothing. */
-export const DEFAULT_DATA_TYPE = 'INFRARED SPECTRUM';
+/** The infrared data type, written when the file that was read named none. */
+export const DEFAULT_DATA_TYPE = IR_TECHNIQUE_RULES.infrared.dataType;
 
 /**
  * Write one spectrum as a JCAMP-DX block.
@@ -37,15 +39,20 @@ export const DEFAULT_DATA_TYPE = 'INFRARED SPECTRUM';
  * which that was, and only otherwise the one being read. Writing what is on
  * screen instead would export a spectrum that had been through a logarithm it
  * was never measured with — and, where a band bottoms out at zero transmittance,
- * an absorbance of infinity that no reader can take back.
+ * an absorbance of infinity that no reader can take back. A spectrum carrying
+ * neither falls back on whichever axis it does carry, so a Raman spectrum is
+ * written as its intensity.
  * @param spectrum - The spectrum.
  * @param mode - The axis being read, used when the file named none.
  * @returns The block, `##TITLE=` through `##END=`.
+ * @throws {Error} When the spectrum carries no value axis at all.
  */
 export function irSpectrumToJcamp(spectrum: IrSpectrum, mode: IrMode): string {
-  const written = spectrum.origin.recorded ?? mode;
-  const values =
-    written === 'absorbance' ? spectrum.absorbance : spectrum.transmittance;
+  const written = writtenAxis(spectrum, mode);
+  const values = spectrum[written];
+  if (values === undefined) {
+    throw new Error(`${spectrum.name} carries no value axis to write.`);
+  }
   return fromJSON(
     { x: spectrum.wavenumber, y: values },
     { info: infoRecords(spectrum, written), meta: metaRecords(spectrum) },
@@ -67,13 +74,14 @@ export function irSpectrumToJcamp(spectrum: IrSpectrum, mode: IrMode): string {
  * spectrum would have written.
  * @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.
- * @param title - What to call the file's own outer block.
+ * @param title - What to call the file's own outer block. Defaults to the
+ * count and the technique that reads `mode`: `2 infrared spectra`.
  * @returns The file.
  */
 export function irSpectraToJcamp(
   spectra: readonly IrSpectrum[],
   mode: IrMode,
-  title = `${spectra.length} infrared spectra`,
+  title = `${spectra.length} ${IR_TECHNIQUE_RULES[irModeTechnique(mode)].name} spectra`,
 ): string {
   const only = spectra.length === 1 ? spectra[0] : undefined;
   if (only !== undefined) return irSpectrumToJcamp(only, mode);
@@ -91,6 +99,32 @@ ${blocks.join('\n')}
 `;
 }
 
+/**
+ * Which axis of a spectrum is written.
+ * @param spectrum - The spectrum.
+ * @param mode - The axis being read.
+ * @returns The axis its file recorded, else the one being read, else the first
+ * it carries; `mode` when it carries none, which the caller refuses.
+ */
+function writtenAxis(spectrum: IrSpectrum, mode: IrMode): IrMode {
+  const { recorded } = spectrum.origin;
+  if (recorded !== undefined && spectrum[recorded] !== undefined) {
+    return recorded;
+  }
+  if (spectrum[mode] !== undefined) return mode;
+  for (const axis of WRITTEN_AXES) {
+    if (spectrum[axis] !== undefined) return axis;
+  }
+  return mode;
+}
+
+/** The axes a spectrum may carry, in the order one is looked for. */
+const WRITTEN_AXES: readonly IrMode[] = [
+  'transmittance',
+  'absorbance',
+  'intensity',
+];
+
 /**
  * The standard records of a block: what it is called, and what its axes are.
  * @param spectrum - The spectrum.
@@ -103,17 +137,32 @@ function infoRecords(
 ): Record<string, string> {
   return {
     title: recordValue(spectrum.name),
-    // The technique as the file stated it, so a Raman spectrum that was opened
-    // here is not written back out claiming to be infrared.
-    dataType: technique(spectrum) ?? DEFAULT_DATA_TYPE,
+    // The technique as the file stated it, and otherwise the one the written
+    // axis belongs to, so a Raman spectrum is never written out claiming to be
+    // infrared.
+    dataType:
+      technique(spectrum) ??
+      IR_TECHNIQUE_RULES[irModeTechnique(written)].dataType,
     xUnits: '1/CM',
-    // Spelled the way `ir-spectrum` reads it: it takes the axis to be
-    // transmittance when the label says `trans`, and to be a percentage rather
-    // than a fraction when it carries a `%`.
-    yUnits: written === 'absorbance' ? 'ABSORBANCE' : 'Transmittance (%)',
+    yUnits: Y_UNITS[written],
   };
 }
 
+/**
+ * What each axis is called in `##YUNITS=`.
+ *
+ * Spelled the way `ir-spectrum` reads them: it takes the axis to be
+ * transmittance when the label says `trans`, and to be a percentage rather than
+ * a fraction when it carries a `%`. A Raman intensity has no unit of its own —
+ * counts on one instrument, a fraction of the strongest band on another — so it
+ * is named, as Raman instruments write it.
+ */
+const Y_UNITS: Record<IrMode, string> = {
+  transmittance: 'Transmittance (%)',
+  absorbance: 'ABSORBANCE',
+  intensity: 'INTENSITY',
+};
+
 /**
  * The `$`-prefixed records of a block: the acquisition, as the file stated it.
  *

package/src/ir/core/toIrSpectrum.ts

@@ -64,8 +64,7 @@ export function toIrSpectrum(
     name: name ?? loaded.name ?? loaded.origin.fileName ?? 'spectrum',
     color,
     wavenumber: loaded.wavenumber,
-    absorbance: loaded.absorbance,
-    transmittance: loaded.transmittance,
+    ...valueAxes(loaded),
     meta: loaded.meta,
     origin: loaded.origin,
     visible,
@@ -100,3 +99,22 @@ export function toIrSpectra(
   }
   return spectra;
 }
+
+/**
+ * The value axes a loaded spectrum carries, and only those.
+ *
+ * An absent axis is an absent key, never a key holding `undefined`: the two
+ * read the same in a debugger and differently in every structural comparison.
+ * @param loaded - What the reader produced.
+ * @returns Its absorbance and transmittance, or its intensity.
+ */
+function valueAxes(
+  loaded: LoadedIrSpectrum,
+): Pick<IrSpectrum, 'absorbance' | 'transmittance' | 'intensity'> {
+  const { absorbance, transmittance, intensity } = loaded;
+  return {
+    ...(absorbance === undefined ? {} : { absorbance }),
+    ...(transmittance === undefined ? {} : { transmittance }),
+    ...(intensity === undefined ? {} : { intensity }),
+  };
+}

package/src/ir/ui/BandRow.tsx

@@ -0,0 +1,107 @@
+import { Icon } from '@blueprintjs/core';
+
+import {
+  panelCellStyle,
+  panelNumberCellStyle,
+} from '../../panel/core/panelStyles.ts';
+import type { AssignedBand } from '../core/assignBands.ts';
+import type { IrBand } from '../core/irBand.ts';
+import { bandValue } from '../core/irBand.ts';
+import { formatIrValue, formatWavenumber } from '../core/irFormat.ts';
+import type { IrMode } from '../core/irSpectrum.ts';
+
+export interface BandRowProps {
+  /** The band and everything it might be. */
+  entry: AssignedBand;
+  /** Which value axis is being read. */
+  mode: IrMode;
+  /** Whether the row has a column for what the band could be. */
+  assignments: boolean;
+  /** Whether the pointer is on this band, here or on the chart. */
+  lit: boolean;
+  /**
+   * Told when the pointer arrives on this row, and when it leaves.
+   * @default undefined
+   */
+  onHighlight?: (band: IrBand | null) => void;
+}
+
+/**
+ * One band: where it is, how strong, and every vibration it could be.
+ *
+ * The candidates are written as one line rather than a list, so a strong band
+ * with four of them stays one row of the table and the wavenumbers keep reading
+ * down the column. The `title` carries them again with each one's note, which is
+ * where the reason to prefer one lives.
+ * @param props - Component props.
+ * @returns The row.
+ */
+export function BandRow(props: BandRowProps) {
+  const { entry, mode, assignments, lit, onHighlight } = props;
+  const { band } = entry;
+
+  return (
+    <tr
+      style={lit ? litRowStyle : undefined}
+      onPointerEnter={() => onHighlight?.(band)}
+      onPointerLeave={() => onHighlight?.(null)}
+    >
+      <td style={panelNumberCellStyle}>{formatWavenumber(band.wavenumber)}</td>
+      <td style={panelCellStyle} title={STRENGTH_TITLES[band.strength]}>
+        {band.strength}
+      </td>
+      <td style={panelNumberCellStyle}>
+        {formatIrValue(bandValue(band, mode) ?? Number.NaN, mode)}
+      </td>
+      {assignments ? <CandidatesCell entry={entry} /> : null}
+    </tr>
+  );
+}
+
+interface CandidatesCellProps {
+  /** The band and everything it might be. */
+  entry: AssignedBand;
+}
+
+/**
+ * What a band could be: the narrowest candidate, and how many more there are.
+ * @param props - Component props.
+ * @returns The cell.
+ */
+function CandidatesCell(props: CandidatesCellProps) {
+  const { candidates } = props.entry;
+  const detail = candidates
+    .map((candidate) =>
+      candidate.note === undefined
+        ? `${candidate.group} ${candidate.vibration}`
+        : `${candidate.group} ${candidate.vibration} — ${candidate.note}`,
+    )
+    .join('\n');
+
+  return (
+    <td style={panelCellStyle} title={detail}>
+      {candidates.length === 0 ? (
+        <span style={{ opacity: 0.5 }}>—</span>
+      ) : (
+        <span style={{ whiteSpace: 'normal' }}>
+          {candidates[0]?.group} {candidates[0]?.vibration}
+          {candidates.length > 1 ? (
+            <span style={{ opacity: 0.6 }}>
+              {' '}
+              <Icon icon="more" size={10} /> {candidates.length - 1} more
+            </span>
+          ) : null}
+        </span>
+      )}
+    </td>
+  );
+}
+
+/** What each strength letter means, for the column that shows only the letter. */
+const STRENGTH_TITLES = {
+  w: 'weak, relative to this spectrum',
+  m: 'medium, relative to this spectrum',
+  S: 'strong, relative to this spectrum',
+} as const;
+
+const litRowStyle = { background: '#fff3e0' } as const;