react-cheminfo 0.70.0 → 0.71.0

package/src/ir/core/handPicking.ts

@@ -0,0 +1,154 @@
+/**
+ * Picking bands by hand.
+ *
+ * Where a click lands is not where the band is: it is taken to the top of the
+ * band it was aimed at, and the band is read off the spectrum there exactly as
+ * automatic picking reads one — the same values, and the same strength letter.
+ */
+
+import { peakPicking } from 'ir-spectrum';
+import {
+  xMinMaxValues,
+  xyMaxClosestYPoint,
+  xyMaxYPoint,
+  xyMinYPoint,
+} from 'ml-spectra-processing';
+
+import type { IrBand, IrBandStrength } from './irBand.ts';
+import type { IrSpectrum } from './irSpectrum.ts';
+import { infraredMeasurement } from './pickBands.ts';
+import { intensityStrength } from './ramanBands.ts';
+
+/**
+ * What a click while picking by hand makes of a spectrum's bands: the band it
+ * landed on taken away, or else the band under it added.
+ * @param spectrum - The spectrum picked on.
+ * @param wavenumber - Where the click landed, in cm⁻¹.
+ * @param reach - How close to a band counts as on it, and how far either side
+ * to look for one, in cm⁻¹: a few pixels' worth at the zoom of the chart.
+ * @returns The new bands, or the spectrum's own list when nothing changed.
+ */
+export function editBandsAt(
+  spectrum: IrSpectrum,
+  wavenumber: number,
+  reach: number,
+): IrBand[] {
+  const bands = spectrum.bands ?? [];
+  let hit: IrBand | null = null;
+  let nearest = Math.abs(reach);
+  for (const band of bands) {
+    const distance = Math.abs(band.wavenumber - wavenumber);
+    if (distance <= nearest) {
+      nearest = distance;
+      hit = band;
+    }
+  }
+  if (hit !== null) return removeBand(bands, hit.wavenumber);
+  const band = pickBandAt(spectrum, wavenumber, reach);
+  return band === null ? bands : addBand(bands, band);
+}
+
+/**
+ * The band a click asks for: the top of the band under it.
+ *
+ * The highest point within reach of the click first, then uphill from there to
+ * the top: a click lands on a band's flank as often as on its top, and a flank
+ * carries bumps of noise that a climb from the click alone would stop at. A
+ * band is a maximum of absorbance, or of intensity for a Raman spectrum,
+ * whichever way up the chart is drawn.
+ * @param spectrum - The spectrum picked on.
+ * @param wavenumber - Where the click landed, in cm⁻¹.
+ * @param reach - How far either side of it to look, in cm⁻¹.
+ * @returns The band, or `null` when the spectrum carries no axis a band is a
+ * maximum of, or is flat within reach.
+ */
+export function pickBandAt(
+  spectrum: IrSpectrum,
+  wavenumber: number,
+  reach: number,
+): IrBand | null {
+  const { wavenumber: x, intensity, absorbance } = spectrum;
+  const y = intensity ?? absorbance;
+  if (y === undefined || x.length < 2 || !Number.isFinite(wavenumber)) {
+    return null;
+  }
+  const around = Number.isFinite(reach) ? Math.abs(reach) : 0;
+  const within = { from: wavenumber - around, to: wavenumber + around };
+  const near = xyMaxYPoint({ x, y }, within);
+  // A stretch that does not rise at all has no band to climb to.
+  if (around > 0 && near.y <= xyMinYPoint({ x, y }, within).y) return null;
+  const top = xyMaxClosestYPoint({ x, y }, { targetIndex: near.index });
+  return bandAtIndex(spectrum, top.index);
+}
+
+/**
+ * The band at one sample of a spectrum, read the way automatic picking reads
+ * one.
+ * @param spectrum - The spectrum.
+ * @param index - The sample.
+ * @returns The band, or `null` when there is no such sample or no axis to read
+ * it on.
+ */
+export function bandAtIndex(
+  spectrum: IrSpectrum,
+  index: number,
+): IrBand | null {
+  const { id, wavenumber, absorbance, transmittance, intensity } = spectrum;
+  const at = wavenumber[index];
+  if (at === undefined) return null;
+  if (intensity !== undefined) {
+    const value = intensity[index] ?? Number.NaN;
+    const { min, max } = xMinMaxValues(intensity);
+    return {
+      spectrumId: id,
+      wavenumber: at,
+      intensity: value,
+      strength: intensityStrength(value, min, max),
+    };
+  }
+  if (absorbance === undefined || transmittance === undefined) return null;
+  // `ir-spectrum` reads the sample and works out the letter, as it does for
+  // every band it picks itself.
+  const peak = peakPicking(
+    infraredMeasurement(wavenumber, absorbance, transmittance),
+    at,
+    { yVariable: 'a' },
+  );
+  if (peak === undefined) return null;
+  return {
+    spectrumId: id,
+    wavenumber: at,
+    absorbance: peak.absorbance,
+    transmittance: peak.transmittance * 100,
+    strength: peak.kind as IrBandStrength,
+  };
+}
+
+/**
+ * The bands with one more, in its place.
+ * @param bands - The bands, ascending.
+ * @param band - The band to add.
+ * @returns A new list, or the same one when a band already sits there.
+ */
+export function addBand(bands: IrBand[], band: IrBand): IrBand[] {
+  let index = 0;
+  while (
+    index < bands.length &&
+    (bands[index]?.wavenumber ?? 0) < band.wavenumber
+  ) {
+    index++;
+  }
+  if (bands[index]?.wavenumber === band.wavenumber) return bands;
+  return bands.toSpliced(index, 0, band);
+}
+
+/**
+ * The bands without the one at a wavenumber.
+ * @param bands - The bands.
+ * @param wavenumber - Where the band to take away sits, exactly.
+ * @returns A new list, or the same one when no band sits there.
+ */
+export function removeBand(bands: IrBand[], wavenumber: number): IrBand[] {
+  const index = bands.findIndex((band) => band.wavenumber === wavenumber);
+  return index === -1 ? bands : bands.toSpliced(index, 1);
+}

package/src/ir/core/index.ts

@@ -24,6 +24,14 @@ export type { BandLabelPlan, BandLabelPlanOptions } from './bandLabelPlan.ts';
 export { planBandLabels } from './bandLabelPlan.ts';
 export { detectIrFormat } from './detectIrFormat.ts';
 export { downloadIrSpectra, downloadIrSpectrum } from './downloadSpectra.ts';
+export {
+  addBand,
+  bandAtIndex,
+  editBandsAt,
+  pickBandAt,
+  removeBand,
+} from './handPicking.ts';
+export { bandsFromPeaks, peaksFromBands } from './irPeaks.ts';
 export type { IrJcampReadOptions } from './fromJcamp.ts';
 export type { IrSpcReadOptions } from './fromSpc.ts';
 export type { IrBand, IrBandStrength } from './irBand.ts';
@@ -124,6 +132,12 @@ 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 {
+  orderedBands,
+  repickBands,
+  samePicking,
+  withBands,
+} from './spectrumBands.ts';
 export {
   DEFAULT_DATA_TYPE,
   JCAMP_EXTENSION,

package/src/ir/core/irBandState.ts

@@ -0,0 +1,155 @@
+/**
+ * The changes of the viewer's state that are about bands: spectra arriving
+ * with theirs or without, a list picked by hand, a list found automatically
+ * again, and new picking settings, which pick again every list that was found
+ * automatically.
+ *
+ * Apart from the reducer, which routes these actions here; like it, each
+ * returns the state itself when it has nothing to do.
+ */
+
+import type { IrBand } from './irBand.ts';
+import type { IrSpectrum } from './irSpectrum.ts';
+import type { IrSettings, IrState, PartialIrState } from './irState.ts';
+import { mergeIrSettings } from './irState.ts';
+import type { PickBandsOptions } from './pickBands.ts';
+import {
+  orderedBands,
+  repickBands,
+  samePicking,
+  withBands,
+} from './spectrumBands.ts';
+
+/**
+ * Spectra arriving, each carrying its bands: its own, or picked now.
+ * @param state - The state they arrive in.
+ * @param spectra - The spectra.
+ * @returns A new list.
+ */
+export function arriving(
+  state: IrState,
+  spectra: readonly IrSpectrum[],
+): IrSpectrum[] {
+  const { picking } = state.settings;
+  return spectra.map((spectrum) => withBands(spectrum, picking));
+}
+
+/**
+ * Give one spectrum bands picked by hand.
+ * @param state - The state in force.
+ * @param id - Which spectrum.
+ * @param bands - Its bands, in any order.
+ * @returns The new state, or the old one when they were its own already.
+ */
+export function setSpectrumBands(
+  state: IrState,
+  id: string,
+  bands: IrBand[],
+): IrState {
+  return mapSpectrum(state, id, (spectrum) => {
+    const ordered = orderedBands(spectrum.id, bands);
+    return ordered === spectrum.bands && spectrum.bandsByHand === true
+      ? spectrum
+      : { ...spectrum, bands: ordered, bandsByHand: true };
+  });
+}
+
+/**
+ * Have one spectrum's bands found automatically again.
+ * @param state - The state in force.
+ * @param id - Which spectrum.
+ * @returns The new state, or the old one when they already were.
+ */
+export function resetSpectrumBands(state: IrState, id: string): IrState {
+  const { picking } = state.settings;
+  return mapSpectrum(state, id, (spectrum) =>
+    spectrum.bandsByHand
+      ? repickBands({ ...spectrum, bandsByHand: false }, picking)
+      : spectrum,
+  );
+}
+
+/**
+ * Fold a change into the workspace, and pick again what it changes.
+ * @param state - The state in force.
+ * @param change - What to change about the workspace.
+ * @returns The new state.
+ */
+export function changeSettings(
+  state: IrState,
+  change: Partial<IrSettings>,
+): IrState {
+  const settings = mergeIrSettings(state.settings, change);
+  const { spectra } = state.data;
+  const picked = pickedAgain(spectra, state.settings.picking, settings.picking);
+  return {
+    ...state,
+    data: picked === spectra ? state.data : { spectra: picked },
+    settings,
+  };
+}
+
+/**
+ * Take a whole state, as a host restoring one supplies it.
+ * @param state - The state in force.
+ * @param restored - The parts the host supplies.
+ * @returns The new state.
+ */
+export function restoreState(
+  state: IrState,
+  restored: PartialIrState,
+): IrState {
+  const { data, view, settings } = restored;
+  const merged = mergeIrSettings(state.settings, settings);
+  const spectra =
+    data === undefined
+      ? state.data.spectra
+      : arriving({ ...state, settings: merged }, data.spectra);
+  return {
+    data: {
+      spectra: pickedAgain(spectra, state.settings.picking, merged.picking),
+    },
+    view: { ...state.view, ...view },
+    settings: merged,
+  };
+}
+
+/**
+ * Change one spectrum, leaving the state alone when it did not change.
+ * @param state - The state in force.
+ * @param id - Which spectrum.
+ * @param change - What to make of it; return it unchanged for no change.
+ * @returns The new state, or the old one.
+ */
+export function mapSpectrum(
+  state: IrState,
+  id: string,
+  change: (spectrum: IrSpectrum) => IrSpectrum,
+): IrState {
+  let changed = false;
+  const spectra = state.data.spectra.map((spectrum) => {
+    if (spectrum.id !== id) return spectrum;
+    const next = change(spectrum);
+    if (next !== spectrum) changed = true;
+    return next;
+  });
+  if (!changed) return state;
+  return { ...state, data: { spectra }, view: { ...state.view, error: null } };
+}
+
+/**
+ * The spectra under new picking settings: those found automatically picked
+ * again.
+ * @param spectra - The spectra.
+ * @param before - The settings they were picked with.
+ * @param after - The settings now in force.
+ * @returns The same list when the settings pick as before.
+ */
+function pickedAgain(
+  spectra: IrSpectrum[],
+  before: PickBandsOptions,
+  after: PickBandsOptions,
+): IrSpectrum[] {
+  if (samePicking(before, after)) return spectra;
+  return spectra.map((spectrum) => repickBands(spectrum, after));
+}

package/src/ir/core/irCommands.ts

@@ -86,6 +86,13 @@ export const irCommands = {
       '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. It is the only drag on percent transmittance.',
     gestures: [{ title: 'Over the chart', shortcuts: ['Drag a rectangle'] }],
   },
+  pickTool: {
+    title: 'Pick bands by hand',
+    shortcut: { keys: ['k'] },
+    description:
+      'A click adds the band under it to the selected spectrum, at its top; a click on a marked band takes it away. A drag still zooms, and bands picked by hand stay put when the threshold moves.',
+    gestures: [{ title: 'Over the chart', shortcuts: ['Click'] }],
+  },
   zoomIn: {
     title: 'Zoom in',
     shortcut: { keys: ['+', '='] },

package/src/ir/core/irPeaks.ts

@@ -0,0 +1,79 @@
+/**
+ * The bands of an infrared spectrum as a notebook writes them, and back: the
+ * peaks of the host protocol's `spectra.ir.jdx` and `spectra.ir.peaks`.
+ *
+ * The two differ in two ways only: a notebook's transmittance is a fraction
+ * where the viewer holds a percentage, and it calls a band's strength `kind`.
+ */
+
+import { xFindClosestIndex } from 'ml-spectra-processing';
+
+import type { IrPeakValue } from '../../host/core/irKinds.ts';
+
+import { bandAtIndex } from './handPicking.ts';
+import type { IrBand, IrBandStrength } from './irBand.ts';
+import type { IrSpectrum } from './irSpectrum.ts';
+import { orderedBands } from './spectrumBands.ts';
+
+/**
+ * The bands a notebook handed over with a spectrum.
+ *
+ * Each stays where the notebook put it, with the values it gave; a value it
+ * left out is read off the spectrum at the nearest sample, and a strength
+ * letter that is not one of `w`, `m` and `S` is worked out again.
+ * @param spectrum - The spectrum they were picked on.
+ * @param peaks - The peaks, in any order.
+ * @returns The bands, ascending, one per wavenumber.
+ */
+export function bandsFromPeaks(
+  spectrum: IrSpectrum,
+  peaks: readonly IrPeakValue[],
+): IrBand[] {
+  const bands: IrBand[] = [];
+  for (const peak of peaks) {
+    const { wavenumber, absorbance, transmittance, kind } = peak;
+    if (!Number.isFinite(wavenumber)) continue;
+    const read = bandAtIndex(
+      spectrum,
+      xFindClosestIndex(spectrum.wavenumber, wavenumber),
+    );
+    if (read === null) continue;
+    bands.push({
+      ...read,
+      wavenumber,
+      ...(absorbance === undefined ? {} : { absorbance }),
+      ...(transmittance === undefined
+        ? {}
+        : { transmittance: transmittance * 100 }),
+      strength: isStrength(kind) ? kind : read.strength,
+    });
+  }
+  return orderedBands(spectrum.id, bands);
+}
+
+/**
+ * Bands as a notebook keeps them.
+ * @param bands - The bands, as the viewer holds them.
+ * @returns The peaks, in the same order.
+ */
+export function peaksFromBands(bands: readonly IrBand[]): IrPeakValue[] {
+  const peaks: IrPeakValue[] = [];
+  for (const band of bands) {
+    const { wavenumber, absorbance, transmittance, strength } = band;
+    peaks.push({
+      wavenumber,
+      ...(absorbance === undefined ? {} : { absorbance }),
+      ...(transmittance === undefined
+        ? {}
+        : { transmittance: transmittance / 100 }),
+      kind: strength,
+    });
+  }
+  return peaks;
+}
+
+function isStrength(kind: string | undefined): kind is IrBandStrength {
+  return kind !== undefined && STRENGTHS.includes(kind);
+}
+
+const STRENGTHS: readonly string[] = ['w', 'm', 'S'] satisfies IrBandStrength[];

package/src/ir/core/irReducer.ts

@@ -13,10 +13,19 @@
  * closed.
  */
 
+import type { IrBand } from './irBand.ts';
+import {
+  arriving,
+  changeSettings,
+  mapSpectrum,
+  resetSpectrumBands,
+  restoreState,
+  setSpectrumBands,
+} from './irBandState.ts';
 import type { IrPanelId } from './irSidePanels.ts';
 import type { IrDomain, IrSpectrum } from './irSpectrum.ts';
 import type { IrSettings, IrState, IrTool, PartialIrState } from './irState.ts';
-import { isIrWindow, mergeIrSettings } from './irState.ts';
+import { isIrWindow } from './irState.ts';
 
 /** Everything that can be asked of the viewer. */
 export type IrAction =
@@ -26,6 +35,8 @@ export type IrAction =
   | { type: 'renameSpectrum'; id: string; name: string }
   | { type: 'setSpectrumColor'; id: string; color: string }
   | { type: 'setSpectrumVisible'; id: string; visible: boolean }
+  | { type: 'setBands'; id: string; bands: IrBand[] }
+  | { type: 'resetBands'; id: string }
   | { type: 'selectSpectrum'; id: string | null }
   | { type: 'setDomain'; domain: IrDomain }
   | { type: 'resetDomain' }
@@ -46,7 +57,10 @@ export function irReducer(state: IrState, action: IrAction): IrState {
   switch (action.type) {
     case 'addSpectra': {
       if (action.spectra.length === 0) return state;
-      const spectra = [...state.data.spectra, ...action.spectra];
+      const spectra = [
+        ...state.data.spectra,
+        ...arriving(state, action.spectra),
+      ];
       return {
         ...state,
         data: { spectra },
@@ -65,7 +79,7 @@ export function irReducer(state: IrState, action: IrAction): IrState {
     case 'setSpectra': {
       return {
         ...state,
-        data: { spectra: [...action.spectra] },
+        data: { spectra: arriving(state, action.spectra) },
         view: {
           ...state.view,
           selectedId: action.spectra[0]?.id ?? null,
@@ -122,6 +136,14 @@ export function irReducer(state: IrState, action: IrAction): IrState {
       );
     }
 
+    case 'setBands': {
+      return setSpectrumBands(state, action.id, action.bands);
+    }
+
+    case 'resetBands': {
+      return resetSpectrumBands(state, action.id);
+    }
+
     case 'selectSpectrum': {
       if (state.view.selectedId === action.id) return state;
       return { ...state, view: { ...state.view, selectedId: action.id } };
@@ -162,17 +184,11 @@ export function irReducer(state: IrState, action: IrAction): IrState {
     }
 
     case 'setSettings': {
-      const settings = mergeIrSettings(state.settings, action.settings);
-      return { ...state, settings };
+      return changeSettings(state, action.settings);
     }
 
     case 'loadState': {
-      const { data, view, settings } = action.state;
-      return {
-        data: data === undefined ? state.data : { spectra: [...data.spectra] },
-        view: { ...state.view, ...view },
-        settings: mergeIrSettings(state.settings, settings),
-      };
+      return restoreState(state, action.state);
     }
 
     case 'clear': {
@@ -191,29 +207,6 @@ export function irReducer(state: IrState, action: IrAction): IrState {
   }
 }
 
-/**
- * Change one spectrum, leaving the state alone when it did not change.
- * @param state - The state in force.
- * @param id - Which spectrum.
- * @param change - What to make of it; return it unchanged for no change.
- * @returns The new state, or the old one.
- */
-function mapSpectrum(
-  state: IrState,
-  id: string,
-  change: (spectrum: IrSpectrum) => IrSpectrum,
-): IrState {
-  let changed = false;
-  const spectra = state.data.spectra.map((spectrum) => {
-    if (spectrum.id !== id) return spectrum;
-    const next = change(spectrum);
-    if (next !== spectrum) changed = true;
-    return next;
-  });
-  if (!changed) return state;
-  return { ...state, data: { spectra }, view: { ...state.view, error: null } };
-}
-
 /**
  * Refuse an action, saying why.
  * @param state - The state in force.

package/src/ir/core/irSpectrum.ts

@@ -25,6 +25,8 @@ import type { DataXY } from 'cheminfo-types';
 
 import type { ChartDomain } from '../../chart/core/chartDomain.ts';
 
+import type { IrBand } from './irBand.ts';
+
 /**
  * One trace of a measurement: wavenumber against whichever value axis is drawn.
  *
@@ -150,6 +152,20 @@ export interface IrSpectrum {
    * @default false
    */
   excludeFromDomain?: boolean;
+  /**
+   * The bands picked on it, ascending by wavenumber. The viewer picks them
+   * when a spectrum arrives without any; a host may hand them over with it, as
+   * a notebook that keeps them does.
+   * @default undefined
+   */
+  bands?: IrBand[];
+  /**
+   * Whether `bands` were picked by hand — edited in the viewer, or handed over
+   * — rather than found with the picking settings, which re-pick only a list
+   * that was not.
+   * @default false
+   */
+  bandsByHand?: boolean;
 }
 
 /**

package/src/ir/core/irState.ts

@@ -7,10 +7,10 @@
  * `settings` is the workspace, which is how every spectrum is drawn whichever
  * ones happen to be open.
  *
- * The bands are **not** in here. They are derived from the spectra and the
- * picking settings, so holding them would mean holding an answer that has to be
- * kept in step with its own inputs — `useIrEditor` recomputes them instead, and
- * a stale band is then impossible rather than merely unlikely.
+ * The bands are in `data`, each spectrum carrying its own: picked when it
+ * arrives, picked again by the reducer when the settings change while they were
+ * found automatically, and left alone once picked by hand. That is what lets a
+ * band be added or taken away, and a list be handed to a host and back.
  */
 
 import type { IrPanelId, IrSidePanelId } from './irSidePanels.ts';
@@ -18,6 +18,7 @@ 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';
+import { withBands } from './spectrumBands.ts';
 
 /** The document: what a file holds. */
 export interface IrData {
@@ -25,8 +26,11 @@ export interface IrData {
   spectra: IrSpectrum[];
 }
 
-/** What a drag across the chart is for while it is chosen. */
-export type IrTool = 'read' | 'box';
+/**
+ * What a drag across the chart is for while it is chosen, and for `pick`, what
+ * a click is: a band added where it lands, or taken away.
+ */
+export type IrTool = 'read' | 'box' | 'pick';
 
 /** Where you are in the viewer. */
 export interface IrView {
@@ -165,8 +169,11 @@ export function createIrState(options: CreateIrStateOptions = {}): IrState {
     technique,
     mode: defaultIrMode(technique),
   };
+  const merged = mergeIrSettings(opened, settings);
   return {
-    data: { spectra: [...spectra] },
+    data: {
+      spectra: spectra.map((spectrum) => withBands(spectrum, merged.picking)),
+    },
     view: {
       selectedId: spectra[0]?.id ?? null,
       domain: null,
@@ -174,7 +181,7 @@ export function createIrState(options: CreateIrStateOptions = {}): IrState {
       openPanelIds: [...(panelIds ?? DEFAULT_SIDE_PANELS)],
       error: null,
     },
-    settings: mergeIrSettings(opened, settings),
+    settings: merged,
   };
 }