react-cheminfo 0.28.0 → 0.30.0

package/src/help/ui/HelpBody.tsx

@@ -20,6 +20,15 @@ export interface HelpExample {
   note?: string;
 }
 
+/**
+ * Help written as prose: one paragraph, or several.
+ *
+ * Several because an explanation worth reading is rarely one thought, and a
+ * dozen sentences run together into one block is a wall nobody reads to the
+ * end — which is the same as not having written it.
+ */
+export type HelpText = string | readonly string[];
+
 /** Everything a piece of help says, wherever it is shown. */
 export interface HelpContent {
   /**
@@ -28,7 +37,8 @@ export interface HelpContent {
    */
   title?: string;
   /**
-   * The explanation: one or two sentences, or any content of the site's own.
+   * The explanation: one or two sentences, any content of the site's own, or
+   * an array of strings, which is set as one paragraph each.
    * @default undefined
    */
   body?: ReactNode;
@@ -82,7 +92,9 @@ export function HelpBody(props: HelpBodyProps): ReactElement {
       style={{ ...BODY_STYLE, maxWidth: width }}
     >
       {title === undefined ? null : <div style={TITLE_STYLE}>{title}</div>}
-      {body === undefined ? null : <div style={TEXT_STYLE}>{body}</div>}
+      {body === undefined ? null : (
+        <div style={TEXT_STYLE}>{paragraphsOf(body)}</div>
+      )}
       {examplesOf(example).map((item) => (
         <div key={exampleKey(item)} style={EXAMPLE_STYLE}>
           <code style={CODE_STYLE}>{item.code}</code>
@@ -110,6 +122,30 @@ export function HelpBody(props: HelpBodyProps): ReactElement {
   );
 }
 
+/**
+ * The body, with an array of strings set as paragraphs rather than run
+ * together.
+ *
+ * React renders `['one', 'two']` as `onetwo`, which is never what a caller who
+ * wrote two sentences meant. Anything else is handed back untouched: a body
+ * built of elements is the site's own and is laid out by whoever wrote it.
+ * @param body - The body, as the caller wrote it.
+ * @returns What to render.
+ */
+function paragraphsOf(body: ReactNode): ReactNode {
+  if (!Array.isArray(body)) return body;
+  const paragraphs: string[] = [];
+  for (const piece of body) {
+    if (typeof piece !== 'string') return body;
+    paragraphs.push(piece);
+  }
+  return paragraphs.map((paragraph) => (
+    <p key={paragraph} style={PARAGRAPH_STYLE}>
+      {paragraph}
+    </p>
+  ));
+}
+
 // Two examples are only the same when all three of their parts are, and a help
 // that repeats one example has nothing to gain from drawing it twice.
 function exampleKey(example: HelpExample): string {
@@ -130,6 +166,9 @@ function examplesOf(example: HelpContent['example']): readonly HelpExample[] {
   return unique;
 }
 
+/** The gap between paragraphs is the column's, so the margin is nobody's. */
+const PARAGRAPH_STYLE = { margin: 0 } as const satisfies CSSProperties;
+
 /** How wide a piece of help is drawn when the caller does not say. */
 const DEFAULT_WIDTH = 280;
 

package/src/help/ui/index.ts

@@ -1,4 +1,9 @@
-export type { HelpBodyProps, HelpContent, HelpExample } from './HelpBody.tsx';
+export type {
+  HelpBodyProps,
+  HelpContent,
+  HelpExample,
+  HelpText,
+} from './HelpBody.tsx';
 export { HelpBody } from './HelpBody.tsx';
 export type { HelpIconProps } from './HelpIcon.tsx';
 export { HelpIcon } from './HelpIcon.tsx';

package/src/ir/core/analysisSpectra.ts

@@ -0,0 +1,231 @@
+/**
+ * The step every reader shares: an `ir-spectrum` `Analysis` becomes spectra.
+ *
+ * All three readers hand back the same `Analysis`, and `ir-spectrum` has already
+ * done the part that needs to know what the file's y axis meant — it puts an `a`
+ * and a `t` variable on every spectrum whichever of the two was written. So what
+ * is left here is bookkeeping: order the points, type the arrays, read the
+ * records, and say which axis the file itself carried.
+ */
+
+import type { DoubleArray, MeasurementXY } from 'cheminfo-types';
+import type { Analysis } from 'ir-spectrum';
+import { xySortX } from 'ml-spectra-processing';
+
+import type { IrMeta, IrMode, IrOrigin } from './irSpectrum.ts';
+
+/** One spectrum as a reader produced it, before it is named and coloured. */
+export interface LoadedIrSpectrum {
+  /** The wavenumbers, ascending. */
+  wavenumber: Float64Array;
+  /** Absorbance at each. */
+  absorbance: Float64Array;
+  /** Percent transmittance at each. */
+  transmittance: Float64Array;
+  /** What the file said about the acquisition, `null` when it said nothing. */
+  meta: IrMeta | null;
+  /** Where it came from. */
+  origin: IrOrigin;
+  /**
+   * What the file called it, absent when it carried no title.
+   * @default undefined
+   */
+  name?: string;
+}
+
+/**
+ * Turn every spectrum an analysis holds into one loaded spectrum.
+ *
+ * All of them, never the first: a JCAMP is a container, and an instrument
+ * exporting a background beside a sample writes both as blocks of one file.
+ * Taking only the first would quietly drop what the chemist exported the file
+ * for, and would do it without an error.
+ *
+ * A block carrying fewer than two points is skipped rather than kept as a
+ * degenerate trace — a JCAMP link block, or a header block an instrument wrote
+ * with no data under it, is not a spectrum.
+ * @param analysis - What the reader built.
+ * @param origin - Where it came from: the format and the file.
+ * @returns One entry per readable block, in the order the file wrote them.
+ */
+export function analysisSpectra(
+  analysis: Analysis,
+  origin: IrOrigin,
+): LoadedIrSpectrum[] {
+  const blocks = analysis.spectra;
+  const spectra: LoadedIrSpectrum[] = [];
+
+  for (let index = 0; index < blocks.length; index++) {
+    const block = blocks[index];
+    if (block === undefined) continue;
+    if (!isInfrared(block)) continue;
+    const wavenumbers = block.variables.x?.data;
+    const absorbances = block.variables.a?.data;
+    const transmittances = block.variables.t?.data;
+    if (
+      wavenumbers === undefined ||
+      absorbances === undefined ||
+      transmittances === undefined ||
+      wavenumbers.length < 2
+    ) {
+      continue;
+    }
+
+    const blockOrigin: IrOrigin = { ...origin };
+    // A file holding one spectrum has no index worth showing; calling it block 0
+    // in the list would suggest there is a block 1 somewhere.
+    if (blocks.length > 1) blockOrigin.blockIndex = index;
+    const recorded = recordedMode(block);
+    if (recorded !== undefined) blockOrigin.recorded = recorded;
+
+    const spectrum: LoadedIrSpectrum = {
+      // Sorted once, on the axis both value arrays are indexed by, and the same
+      // permutation applied to each — sorting them independently would pair an
+      // absorbance with another wavenumber's transmittance.
+      ...sortedByWavenumber(wavenumbers, absorbances, transmittances),
+      meta: blockMeta(block),
+      origin: blockOrigin,
+    };
+    const title = blockTitle(block);
+    // An absent name is an absent key, never a key holding `undefined`: the two
+    // read the same in a debugger and differently in every structural comparison.
+    if (title) spectrum.name = title;
+    spectra.push(spectrum);
+  }
+
+  return spectra;
+}
+
+/** The three arrays of one spectrum, in ascending wavenumber. */
+type SortedTraces = Pick<
+  LoadedIrSpectrum,
+  'wavenumber' | 'absorbance' | 'transmittance'
+>;
+
+/**
+ * Put the points in ascending wavenumber, carrying both value axes along.
+ *
+ * `xySortX` is asked twice with the same x, which sorts it twice — but it is the
+ * one sort in the ecosystem that both orders and types an `xy` pair, and an
+ * infrared spectrum is a few thousand points. Writing a bespoke permutation to
+ * save one pass over four thousand numbers would be a second sort to keep
+ * correct for no measurable gain.
+ * @param wavenumbers - The wavenumbers, in whatever order the file wrote them.
+ * @param absorbances - Absorbance at each.
+ * @param transmittances - Percent transmittance at each.
+ * @returns The three arrays, ascending and typed.
+ */
+function sortedByWavenumber(
+  wavenumbers: DoubleArray,
+  absorbances: DoubleArray,
+  transmittances: DoubleArray,
+): SortedTraces {
+  const byAbsorbance = xySortX({ x: wavenumbers, y: absorbances });
+  const byTransmittance = xySortX({ x: wavenumbers, y: transmittances });
+  return {
+    wavenumber: Float64Array.from(byAbsorbance.x),
+    absorbance: Float64Array.from(byAbsorbance.y),
+    transmittance: Float64Array.from(byTransmittance.y),
+  };
+}
+
+/**
+ * What the block calls itself, with the file's own commentary taken off.
+ *
+ * `$$` opens a comment that runs to the end of the line in JCAMP, and a real
+ * `##TITLE` often carries one: the JSpecView collection is full of
+ * `urea $$ Begin of the data block`. Left in, the comment becomes the name of
+ * the spectrum in the list and the heading of its metadata panel.
+ * @param block - One spectrum of the analysis.
+ * @returns The title, or `undefined` when the block carries none worth showing.
+ */
+function blockTitle(block: MeasurementXY): string | undefined {
+  const written = block.title?.split('$$', 1)[0]?.trim();
+  return written === undefined || written === '' ? undefined : written;
+}
+
+/**
+ * Whether a block is an infrared spectrum rather than something else entirely.
+ *
+ * A JCAMP `LINK` block is a container, and the real ones in the wild put a Raman
+ * spectrum of the same sample in beside the infrared — `DCE.jdx` from the
+ * JSpecView collection holds two of each. A Raman shift is not a wavenumber
+ * absorbed, so loading one as infrared would draw a spectrum whose axis means
+ * something else and offer functional groups for its bands.
+ *
+ * Read off the block's own data type, and a block that states none is **kept**:
+ * plenty of instruments write no `##DATA TYPE` at all, and the file was opened
+ * by an infrared reader, so infrared is the right assumption where the file is
+ * silent. What is dropped is only a block that says it is something else.
+ * @param block - One spectrum of the analysis.
+ * @returns Whether to read it as infrared.
+ */
+function isInfrared(block: MeasurementXY): boolean {
+  const dataType = block.dataType?.toUpperCase();
+  if (dataType === undefined || dataType === '') return true;
+  if (dataType.includes('LINK')) return true;
+  for (const other of NOT_INFRARED) {
+    if (dataType.includes(other)) return false;
+  }
+  return true;
+}
+
+/**
+ * The data types that are certainly not an infrared spectrum.
+ *
+ * Named rather than matching `INFRARED` positively, so a file typed
+ * `IR SPECTRUM`, `FTIR` or `INFRARED SPECTRUM` — all three occur — is read
+ * without the list having to anticipate every spelling.
+ */
+const NOT_INFRARED = [
+  'RAMAN',
+  'NMR',
+  'MASS',
+  'UV',
+  'VISIBLE',
+  'CHROMATOGRAM',
+  'XRD',
+  'FLUORESCENCE',
+];
+
+/**
+ * Which value axis the file itself carried.
+ *
+ * Read off the original `y` variable's label rather than off `a` or `t`, which
+ * `ir-spectrum` adds to every spectrum and so say nothing about the source. A
+ * file whose label names neither is left unanswered rather than guessed at.
+ * @param block - One spectrum of the analysis.
+ * @returns The mode the file was written in, or `undefined` when it is unclear.
+ */
+function recordedMode(block: MeasurementXY): IrMode | undefined {
+  const label = `${block.variables.y?.label ?? ''} ${
+    block.variables.y?.units ?? ''
+  }`.toLowerCase();
+  if (label.includes('transmit')) return 'transmittance';
+  if (label.includes('absorb')) return 'absorbance';
+  return undefined;
+}
+
+/**
+ * The acquisition table, as the file's own records state it.
+ * @param block - One spectrum of the analysis.
+ * @returns The table, `null` when the file carried neither a title nor a record.
+ */
+function blockMeta(block: MeasurementXY): IrMeta | null {
+  const title = blockTitle(block);
+  const fields: IrMetaField[] = [];
+
+  for (const [label, value] of Object.entries(block.meta ?? {})) {
+    const written = typeof value === 'string' ? value.trim() : String(value);
+    if (written !== '') fields.push({ label, value: written });
+  }
+  if (block.dataType) {
+    fields.unshift({ label: 'Technique', value: block.dataType });
+  }
+
+  if (fields.length === 0 && !title) return null;
+  return { title: title ?? null, fields };
+}
+
+/** One row of the acquisition table, as `IrMeta` spells it. */
+type IrMetaField = IrMeta['fields'][number];

package/src/ir/core/assignBands.ts

@@ -0,0 +1,144 @@
+/**
+ * Matching picked bands against the correlation table.
+ *
+ * Every assignment whose range contains the band is kept, and that is the whole
+ * design: infrared assignment is not a lookup with one answer, and a viewer that
+ * showed only the best-fitting vibration would be asserting a structure the
+ * spectrum does not determine. A band at 1715 cm⁻¹ comes back as four
+ * candidates, ordered so the most specific claim reads first, and choosing
+ * between them is the chemist's job — which is what the `note` on each is for.
+ */
+
+import type { BandAssignment } from './bandAssignments.ts';
+import { BAND_ASSIGNMENTS } from './bandAssignments.ts';
+import type { IrBand } from './irBand.ts';
+
+/** One band, with everything it might be. */
+export interface AssignedBand {
+  /** The band that was picked. */
+  band: IrBand;
+  /**
+   * Every vibration whose range contains it, narrowest range first.
+   *
+   * Narrowest first because a narrow range is a more specific claim: at
+   * 1745 cm⁻¹ the ester's fifteen-wavenumber window says more than the
+   * anhydride's ninety, so it is the one worth reading first. Empty for a band
+   * in a region the table says nothing about, which is most of the fingerprint.
+   */
+  candidates: BandAssignment[];
+}
+
+/** How bands are assigned. */
+export interface AssignBandsOptions {
+  /**
+   * The table to match against.
+   * @default BAND_ASSIGNMENTS
+   */
+  assignments?: readonly BandAssignment[];
+  /**
+   * How far outside a range a band may still fall, in cm⁻¹.
+   *
+   * The ranges are conventional values rounded to tens, and a real band sits a
+   * few wavenumbers either side of where a table puts it — a ketone at 1703 is
+   * a ketone. Widening every range by a little is honest about that, where
+   * matching exactly would leave the strongest band in the spectrum unassigned
+   * for being two wavenumbers low.
+   * @default 5
+   */
+  tolerance?: number;
+  /**
+   * Whether a band whose strength disagrees with the table is still offered.
+   *
+   * It is, by default. A weak band where the table expects a strong one is
+   * evidence about concentration or about the assignment being wrong, and either
+   * way it is evidence the reader should see rather than have filtered away.
+   * @default true
+   */
+  keepStrengthMismatch?: boolean;
+}
+
+/**
+ * Assign every band, keeping every candidate.
+ * @param bands - The bands that were picked.
+ * @param options - The table, and how tightly to match it.
+ * @returns One entry per band, in the order the bands were given.
+ */
+export function assignBands(
+  bands: readonly IrBand[],
+  options: AssignBandsOptions = {},
+): AssignedBand[] {
+  const {
+    assignments = BAND_ASSIGNMENTS,
+    tolerance = 5,
+    keepStrengthMismatch = true,
+  } = options;
+
+  const assigned: AssignedBand[] = new Array<AssignedBand>(bands.length);
+  for (let index = 0; index < bands.length; index++) {
+    const band = bands[index] as IrBand;
+    const candidates: BandAssignment[] = [];
+    for (const assignment of assignments) {
+      if (
+        band.wavenumber < assignment.from - tolerance ||
+        band.wavenumber > assignment.to + tolerance
+      ) {
+        continue;
+      }
+      if (!keepStrengthMismatch && assignment.strength !== band.strength) {
+        continue;
+      }
+      candidates.push(assignment);
+    }
+    assigned[index] = {
+      band,
+      candidates: candidates.toSorted(byNarrowestRange),
+    };
+  }
+  return assigned;
+}
+
+/**
+ * How many of the bands the table had something to say about.
+ *
+ * Reported as a count rather than a fraction, because the denominator is the
+ * number of bands picked and that follows the picking threshold — a coverage
+ * percentage would move when somebody adjusted a slider, and read as the
+ * assignment having improved.
+ * @param assigned - The assigned bands.
+ * @returns How many carry at least one candidate.
+ */
+export function countAssigned(assigned: readonly AssignedBand[]): number {
+  let count = 0;
+  for (const entry of assigned) {
+    if (entry.candidates.length > 0) count++;
+  }
+  return count;
+}
+
+/**
+ * The name to write on a band, when there is room for one line.
+ *
+ * The narrowest candidate's group and vibration, which is the first of the
+ * ranked list — the same order the panel shows, so the chart and the table never
+ * disagree about which claim leads.
+ * @param entry - One assigned band.
+ * @returns The label, or `null` when nothing was assigned.
+ */
+export function bandLabel(entry: AssignedBand): string | null {
+  const best = entry.candidates[0];
+  if (best === undefined) return null;
+  return `${best.group} ${best.vibration}`;
+}
+
+/**
+ * Order two assignments by how specific they are, narrowest range first.
+ * @param first - One assignment.
+ * @param second - The other.
+ * @returns The comparison; equal widths keep the table's own order.
+ */
+function byNarrowestRange(
+  first: BandAssignment,
+  second: BandAssignment,
+): number {
+  return first.to - first.from - (second.to - second.from);
+}