react-cheminfo 0.69.0 → 0.71.0

package/src/host/testing/sciPeaks.ts

@@ -8,6 +8,10 @@
  * The sample is a real one, and so are its quirks: its molfile is V2000 with
  * every atom at the origin, its title is blank so the label is its first name,
  * and its formula travels as a kind no structure input reads.
+ *
+ * Its infrared spectrum is pinned here before the tool tab sends it: the bands
+ * are the sample's own, and the message is the one visualizer-helper's `ir`
+ * reader has to write.
  */
 
 import type { LoadRequest } from '../core/protocol.ts';
@@ -64,3 +68,139 @@ export const SCIPEAKS_ETHYLBENZENE_LOAD: LoadRequest & { accept: string[] } = {
   ],
   accept: [],
 };
+
+/** Where SciPeaks keeps that sample's infrared spectrum: its attachment. */
+export const SCIPEAKS_ETHYLBENZENE_IR_FILENAME =
+  'spectra/ir/spectra_ir_100-41-4-IR.jdx';
+
+/**
+ * The bands SciPeaks keeps for that spectrum, as stored: out of wavenumber
+ * order, a transmittance that is a fraction, and the visualizer's `_highlight`.
+ */
+export const SCIPEAKS_ETHYLBENZENE_IR_PEAKS = [
+  peak(
+    1613.8583376884494,
+    0.473660722610156,
+    0.33599999999999997,
+    'm',
+    0.5620600551849647,
+  ),
+  peak(
+    1952.5275809045322,
+    0.13123804178794973,
+    0.7392,
+    'w',
+    0.5211472441361716,
+  ),
+  peak(
+    2872.4947788943773,
+    0.4610494379856386,
+    0.3459,
+    'm',
+    0.30496127508514037,
+  ),
+  peak(2887.659073366737, 0.7066374452885544, 0.1965, 'S', 0.6306151483877337),
+  peak(2907.878132663217, 0.4962093169428189, 0.319, 'S', 0.7220300834282813),
+  peak(2944.9464080400967, 1.0867160982395816, 0.0819, 'S', 0.8391486100817713),
+  peak(2978.6448402008964, 1.7958800173440752, 0.016, 'S', 0.6098050482700554),
+  peak(3014.028193969736, 0.32975414692587596, 0.468, 'm', 0.39091552830124354),
+  peak(3039.302018090336, 1.0969100130080565, 0.08, 'S', 0.502385910408338),
+  peak(
+    3076.3702934672156,
+    0.5831931281770556,
+    0.2611,
+    'S',
+    0.06293920935800923,
+  ),
+  peak(
+    3098.2742743717354,
+    0.38658105496542694,
+    0.4106,
+    'm',
+    0.4934643842659038,
+  ),
+  peak(
+    3118.493333668215,
+    0.16557929631846746,
+    0.6829999999999999,
+    'w',
+    0.05290000144269602,
+  ),
+  peak(
+    1875.0211869346824,
+    0.11935787359571505,
+    0.7597,
+    'w',
+    0.9972320630781272,
+  ),
+  peak(
+    1812.6790874371945,
+    0.11125903931710739,
+    0.774,
+    'w',
+    0.07102323198933491,
+  ),
+  peak(
+    1753.706831155787,
+    0.0834934128848443,
+    0.8251000000000001,
+    'w',
+    0.0750629173499594,
+  ),
+];
+
+/**
+ * The `load` the tool tab is to send that sample to a site that reads
+ * infrared spectra and hands their bands back, once its `ir` reader and its
+ * `save` exist: the structure as it is sent today, one `spectra.ir.jdx` item
+ * per spectrum — the attachment's text, its name and its bands, under the
+ * attachment's name as `id` — and `accept` naming the kind saved back, as
+ * the tool tab's `save` names it.
+ * @param jdx - The attachment's text, which SciPeaks serves at its `dUrl`.
+ * @returns The request, its bands copied so that reading them cannot strip
+ * this module's own.
+ */
+export function sciPeaksEthylbenzeneIrLoad(
+  jdx: string,
+): LoadRequest & { accept: string[] } {
+  return {
+    type: 'load',
+    id: 'load-1',
+    document: SCIPEAKS_ETHYLBENZENE_LOAD.document,
+    items: [
+      ...SCIPEAKS_ETHYLBENZENE_LOAD.items,
+      {
+        kind: 'spectra.ir.jdx',
+        id: SCIPEAKS_ETHYLBENZENE_IR_FILENAME,
+        label: 'spectra_ir_100-41-4-IR.jdx',
+        value: {
+          jdx,
+          filename: SCIPEAKS_ETHYLBENZENE_IR_FILENAME,
+          peaks: SCIPEAKS_ETHYLBENZENE_IR_PEAKS.map((stored) => ({
+            ...stored,
+          })),
+        },
+      },
+    ],
+    accept: ['spectra.ir.peaks'],
+  };
+}
+
+/**
+ * One stored band.
+ * @param wavenumber - Where it sits, in cm⁻¹.
+ * @param absorbance - Its absorbance.
+ * @param transmittance - Its transmittance, a fraction.
+ * @param kind - Its strength letter.
+ * @param highlight - The visualizer's own `_highlight`, stored with it.
+ * @returns The band as SciPeaks stores it.
+ */
+function peak(
+  wavenumber: number,
+  absorbance: number,
+  transmittance: number,
+  kind: string,
+  highlight: number,
+) {
+  return { wavenumber, absorbance, transmittance, kind, _highlight: highlight };
+}

package/src/host/testing/standInHost.ts

@@ -37,7 +37,7 @@ export interface StandInHost {
 export interface StandInHostLog {
   /** The tool's `hello`, or `null` before it came. */
   hello: HelloMessage | null;
-  /** Every message the tool sent on the port, in order. */
+  /** Every message the tool sent on the port, in order: results and outputs. */
   results: unknown[];
 }
 
@@ -46,10 +46,15 @@ export interface StandInHostLog {
  * @returns The host; close it when the tests are done.
  */
 export async function startStandInHost(): Promise<StandInHost> {
-  const server: Server = createServer((_request, response) => {
-    response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
-    response.end(HOST_PAGE);
-  });
+  // A setup carrying a spectrum is tens of kilobytes of address, past the
+  // 16 KiB Node allows a request's head by default.
+  const server: Server = createServer(
+    { maxHeaderSize: MAX_SETUP_BYTES },
+    (_request, response) => {
+      response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+      response.end(HOST_PAGE);
+    },
+  );
   await new Promise<void>((resolve) => {
     server.listen(0, '127.0.0.1', resolve);
   });
@@ -81,6 +86,24 @@ export function readStandInHostLog(): StandInHostLog {
   return (globalThis as unknown as { hostLog: StandInHostLog }).hostLog;
 }
 
+/**
+ * Send one more request on the port, once the tool has connected — a `get`
+ * after the user has worked. Runs in the page, as
+ * `page.evaluate(sendStandInHostRequest, request)`.
+ * @param request - What to send.
+ * @returns Whether there was a port to send it on.
+ */
+export function sendStandInHostRequest(request: unknown): boolean {
+  const { hostPort } = globalThis as unknown as {
+    hostPort: MessagePort | null;
+  };
+  hostPort?.postMessage(request);
+  return hostPort !== null;
+}
+
+/** How long the page's address may be, in bytes: Chrome's own limit is 2 MB. */
+const MAX_SETUP_BYTES = 2 * 1024 * 1024;
+
 /**
  * The page. Its setup is its own `?setup=`, so one page serves every test, and
  * it listens before it frames, so the tool's `hello` cannot be missed.
@@ -95,11 +118,13 @@ const { toolUrl, requests } = JSON.parse(new URLSearchParams(location.search).ge
 const toolOrigin = new URL(toolUrl).origin;
 const frame = document.querySelector('#tool');
 globalThis.hostLog = { hello: null, results: [] };
+globalThis.hostPort = null;
 globalThis.addEventListener('message', (event) => {
   if (event.source !== frame.contentWindow || event.origin !== toolOrigin) return;
   if (event.data?.type !== 'cheminfo:hello') return;
   globalThis.hostLog.hello = event.data;
   const channel = new MessageChannel();
+  globalThis.hostPort = channel.port1;
   channel.port1.onmessage = (answer) => {
     globalThis.hostLog.results.push(answer.data);
   };

package/src/host/ui/useHostConnection.ts

@@ -7,17 +7,25 @@
 
 import { useEffect, useRef } from 'react';
 
-import type { LoadedInput } from '../core/connectHost.ts';
+import type { HostOutputs } from '../core/hostOutputs.ts';
 import type { ToolInterface } from '../core/protocol.ts';
+import type { LoadedInput } from '../core/selectInputs.ts';
 
 /** What a tool does with what its host sends, and what it says about itself. */
 export interface HostHandlers {
   /**
-   * Show the inputs of a new document. Throwing means they could not be read:
-   * the error's message goes back to the host, and nothing should have changed
-   * on screen.
+   * Show the inputs of a new document. Throwing, or rejecting, means they
+   * could not be read: the error's message goes back to the host, and nothing
+   * should have changed on screen.
    */
-  load: (inputs: readonly LoadedInput[]) => void;
+  load: (inputs: readonly LoadedInput[]) => void | Promise<void>;
+  /**
+   * Where the values of the tool's outputs are read, and their changes heard.
+   * Read once, when the host connects, so it lives as long as the page — a
+   * store of signals rather than a value of one render.
+   * @default undefined — nothing goes back
+   */
+  outputs?: HostOutputs;
   /**
    * The build that is running — `BUILD_INFO` from `react-cheminfo/build-info`
    * — so a host can record which version produced what it stores.
@@ -67,9 +75,10 @@ export function useHostConnection(
           tool,
           origin: globalThis.location.origin,
           build: latest.current.build ?? null,
-          load: (inputs) => {
-            latest.current.load(inputs);
-          },
+          load: (inputs) => latest.current.load(inputs),
+          ...(latest.current.outputs === undefined
+            ? {}
+            : { outputs: latest.current.outputs }),
         });
       })
       .catch(() => {

package/src/host-testing.ts

@@ -9,10 +9,14 @@ export type {
 } from './host/testing/standInHost.ts';
 export {
   readStandInHostLog,
+  sendStandInHostRequest,
   startStandInHost,
 } from './host/testing/standInHost.ts';
 export {
+  SCIPEAKS_ETHYLBENZENE_IR_FILENAME,
+  SCIPEAKS_ETHYLBENZENE_IR_PEAKS,
   SCIPEAKS_ETHYLBENZENE_LOAD,
   SCIPEAKS_ETHYLBENZENE_MOLFILE,
   SCIPEAKS_HOST_NAME,
+  sciPeaksEthylbenzeneIrLoad,
 } from './host/testing/sciPeaks.ts';

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: ['+', '='] },