react-cheminfo 0.9.0 → 0.10.0

package/src/scatter/ui/useScatterSelection.ts

@@ -0,0 +1,189 @@
+import { useCallback, useMemo, useState } from 'react';
+
+import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
+import {
+  mergeScatterSelection,
+  scatterSelectedIndices,
+  scatterSelectionMask,
+} from '../core/scatterSelection.ts';
+
+/** What a gesture did to a scatter's selection. */
+export interface SelectionChange {
+  /** The selected rows, ascending, as indices into the arrays the caller passed. */
+  indices: readonly number[];
+  /** Whether the gesture replaced the previous selection, added to it, or cut from it. */
+  mode: ScatterSelectionMode;
+  /** Which gesture produced it. */
+  source: 'lasso' | 'point' | 'keyboard' | 'clear' | 'all';
+}
+
+/** What {@link useScatterSelection} needs. */
+export interface ScatterSelectionOptions {
+  /** How many points the cloud holds. */
+  count: number;
+  /**
+   * The selected rows when the caller owns them. Present, it wins over
+   * anything the reader has done here — see {@link useScatterSelection} for
+   * what that means for a caller that stops passing it.
+   * @default undefined — the hook keeps the selection itself
+   */
+  selected?: readonly number[];
+  /**
+   * The rows selected before the reader touches anything, for the uncontrolled
+   * case. It is read once; changing it later moves nothing.
+   * @default undefined — nothing is selected
+   */
+  defaultSelected?: readonly number[];
+  /**
+   * Called once per settled gesture, never while a lasso is being drawn.
+   * @default undefined
+   */
+  onSelectionChange?: (change: SelectionChange) => void;
+}
+
+/** A scatter's selection, and the four ways a gesture changes it. */
+export interface ScatterSelectionApi {
+  /**
+   * One entry per point, `1` for selected. It includes whatever a lasso is
+   * currently previewing, so the dots under a half-drawn ring already look
+   * picked.
+   */
+  mask: Uint8Array;
+  /** The same, as ascending indices. */
+  indices: number[];
+  /** How many points that is, without walking the list again. */
+  selectedCount: number;
+  /** Whether a lasso is showing what it would do rather than having done it. */
+  previewing: boolean;
+  /** Settle a new selection from a list of rows. */
+  select: (
+    rows: Iterable<number>,
+    mode?: ScatterSelectionMode,
+    source?: SelectionChange['source'],
+  ) => void;
+  /** Settle one from a mask, which is the shape a lasso hands back. */
+  selectMask: (
+    hits: Uint8Array,
+    mode?: ScatterSelectionMode,
+    source?: SelectionChange['source'],
+  ) => void;
+  /** Show what a gesture would do without settling it; `null` clears it. */
+  preview: (hits: Uint8Array | null, mode?: ScatterSelectionMode) => void;
+  /** Empty the selection. */
+  clear: () => void;
+  /** Select every point. */
+  selectAll: () => void;
+}
+
+/**
+ * The set of points a scatter has picked out, controlled or not.
+ *
+ * A caller may own the selection and pass it back through `selected`, or leave
+ * it here and only listen. Both work through one hook, and the controlled
+ * value wins on every render: a parent that answers a change by passing
+ * something else — a filter that keeps only the rows still on screen — sees
+ * what it asked for and not what the gesture asked for. The hook keeps its own
+ * copy up to date all the same, so a caller that stops passing `selected`
+ * carries on from where the reader left off rather than from nothing.
+ *
+ * A preview is deliberately not a change. What a half-drawn lasso would catch
+ * is merged in for the render and never reported, which is what lets a
+ * controlled parent stay out of a drag it would otherwise be re-rendered by
+ * sixty times a second.
+ * @param options - See {@link ScatterSelectionOptions}.
+ * @returns The selection. See {@link ScatterSelectionApi}.
+ */
+export function useScatterSelection(
+  options: ScatterSelectionOptions,
+): ScatterSelectionApi {
+  const { count, selected, defaultSelected, onSelectionChange } = options;
+
+  const [own, setOwn] = useState<readonly number[]>(defaultSelected ?? EMPTY);
+  const [draft, setDraft] = useState<SelectionDraft | null>(null);
+  const committed = selected ?? own;
+
+  const mask = useMemo(() => {
+    const base = scatterSelectionMask(committed, count);
+    if (draft === null) return base;
+    return mergeScatterSelection(base, draft.hits, draft.mode, base);
+  }, [committed, count, draft]);
+
+  const indices = useMemo(() => scatterSelectedIndices(mask), [mask]);
+
+  const commit = useCallback(
+    (
+      rows: number[],
+      mode: ScatterSelectionMode,
+      source: SelectionChange['source'],
+    ) => {
+      setDraft(null);
+      setOwn(rows);
+      onSelectionChange?.({ indices: rows, mode, source });
+    },
+    [onSelectionChange],
+  );
+
+  const selectMask = useCallback(
+    (
+      hits: Uint8Array,
+      mode: ScatterSelectionMode = 'replace',
+      source: SelectionChange['source'] = 'lasso',
+    ) => {
+      const base = scatterSelectionMask(committed, count);
+      const merged = mergeScatterSelection(base, hits, mode, base);
+      commit(scatterSelectedIndices(merged), mode, source);
+    },
+    [commit, committed, count],
+  );
+
+  const select = useCallback(
+    (
+      rows: Iterable<number>,
+      mode: ScatterSelectionMode = 'replace',
+      source: SelectionChange['source'] = 'point',
+    ) => {
+      selectMask(scatterSelectionMask(rows, count), mode, source);
+    },
+    [count, selectMask],
+  );
+
+  const preview = useCallback(
+    (hits: Uint8Array | null, mode: ScatterSelectionMode = 'replace') => {
+      setDraft(hits === null ? null : { hits, mode });
+    },
+    [],
+  );
+
+  const clear = useCallback(() => {
+    commit([], 'replace', 'clear');
+  }, [commit]);
+
+  const selectAll = useCallback(() => {
+    const rows = new Array<number>(Math.max(0, count));
+    for (let index = 0; index < rows.length; index++) rows[index] = index;
+    commit(rows, 'replace', 'all');
+  }, [commit, count]);
+
+  return {
+    mask,
+    indices,
+    selectedCount: indices.length,
+    previewing: draft !== null,
+    select,
+    selectMask,
+    preview,
+    clear,
+    selectAll,
+  };
+}
+
+/** Shared, so an uncontrolled scatter with nothing picked allocates nothing. */
+const EMPTY: readonly number[] = [];
+
+/** What a lasso is showing it would do, before it has been released. */
+interface SelectionDraft {
+  /** The points the half-drawn gesture is over. */
+  hits: Uint8Array;
+  /** What releasing would do with them. */
+  mode: ScatterSelectionMode;
+}

package/src/share/core/query.ts

@@ -26,10 +26,16 @@ export function parseQuery(search: string): QueryEntry[] {
 }
 
 /**
- * Write pairs back into a query string, keeping the two characters a reader
- * of these links cares about legible: a comma stays a comma rather than
- * `%2C`, and a plus stays a plus rather than `%2B`. Both parse back
- * identically through {@link parseQuery}.
+ * Write pairs back into a query string, keeping the comma legible — `hide=a,b`
+ * rather than `hide=a%2Cb` — because a teacher has to read these links, and a
+ * comma has only one reading.
+ *
+ * A plus is written `%2B`, even though {@link parseQuery} would read a literal
+ * one back. We are liberal in what we accept and strict in what we write: a
+ * bare `+` in a query string is read as a space by `URLSearchParams`,
+ * `query-string` and every server-side parser, so `ionizations=H+` comes back
+ * as `H ` and `smiles=CC[N+](C)(C)C` as a different molecule — silently,
+ * anywhere the link is read by something other than {@link parseQuery}.
  * @param entries - The pairs to write, in the order they should appear.
  * @returns The query string, without its leading `?`.
  */
@@ -66,7 +72,5 @@ function decodeComponent(value: string): string {
 }
 
 function encodeComponent(value: string): string {
-  return encodeURIComponent(value)
-    .replaceAll('%2C', ',')
-    .replaceAll('%2B', '+');
+  return encodeURIComponent(value).replaceAll('%2C', ',');
 }

package/src/spectra/core/axisEntries.ts

@@ -0,0 +1,107 @@
+import type { FilterCatalogEntry } from './filterEntries.ts';
+import { RANGE_FIELDS, ZONE_FIELDS } from './filterEntries.ts';
+import {
+  booleanField,
+  enumField,
+  formulaField,
+  integerField,
+  numberField,
+} from './filterFields.ts';
+
+export const AXIS_ENTRIES = {
+  xFunction: {
+    label: 'Apply a formula to x',
+    group: 'x-axis',
+    summary:
+      'Rewrites every x through an expression, read the same way as the y one.',
+    fields: [
+      formulaField(
+        'function',
+        'Expression in x',
+        'For instance 10000000/x, which reads nanometres as wavenumbers.',
+      ),
+    ],
+    caution:
+      'Every range below is then read in the new units — including the resampling range, which runs last unless you resample first.',
+  },
+  fromTo: {
+    label: 'Crop',
+    group: 'x-axis',
+    summary: 'Keeps one stretch of the spectrum and drops the rest.',
+    fields: [
+      ...RANGE_FIELDS,
+      integerField('fromIndex', 'From (point)', '0'),
+      integerField('toIndex', 'To (point)', 'the last point'),
+    ],
+    caution:
+      'Give x values or point numbers, not both: a point number silently wins over an x value.',
+  },
+  filterX: {
+    label: 'Keep or drop x zones',
+    group: 'x-axis',
+    summary:
+      'Keeps the points falling in the zones named, without resampling anything.',
+    fields: [...RANGE_FIELDS, ...ZONE_FIELDS],
+  },
+  equallySpaced: {
+    label: 'Resample on a regular grid',
+    group: 'x-axis',
+    summary: 'Interpolates onto evenly spaced x values.',
+    fields: [
+      ...RANGE_FIELDS,
+      integerField('numberOfPoints', 'Number of points', '100'),
+      ...ZONE_FIELDS,
+    ],
+    caution:
+      'The settings above already resample once, so this resamples twice; whichever of the two runs last sets the point count.',
+  },
+  calibrateX: {
+    label: 'Calibrate x on a peak',
+    group: 'x-axis',
+    summary:
+      'Finds the strongest peaks in a stretch and shifts the whole axis so their mean lands on the value asked for.',
+    fields: [
+      ...RANGE_FIELDS,
+      integerField('nbPeaks', 'Peaks to find', '1'),
+      numberField('targetX', 'Move them to', '0'),
+      booleanField('gsd.smoothY', 'Smooth before picking'),
+      booleanField(
+        'gsd.maxCriteria',
+        'Pick maxima',
+        'Off picks minima instead.',
+      ),
+      numberField(
+        'gsd.minMaxRatio',
+        'Smallest peak kept',
+        '0.00025',
+        'As a fraction of the tallest. A step added here starts at 0.1; empty the box and this far lower default takes over.',
+      ),
+      numberField('gsd.noiseLevel', 'Noise level', 'not set'),
+      booleanField('gsd.realTopDetection', 'Refine the summit'),
+      integerField('gsd.sgOptions.windowSize', 'Peak-picking window', '9'),
+      integerField('gsd.sgOptions.polynomial', 'Peak-picking polynomial', '3'),
+      enumField('gsd.peakDetectionAlgorithm', 'Detected on', [
+        { value: 'first', label: 'The first derivative' },
+        { value: 'second', label: 'The second derivative' },
+        { value: 'auto', label: 'Whichever fits' },
+      ]),
+    ],
+    caution:
+      'When fewer peaks are found than asked for, the spectrum is returned untouched and nothing says so.',
+  },
+  ensureGrowing: {
+    label: 'Make x strictly increasing',
+    group: 'utility',
+    summary:
+      'Drops the points that repeat or go backwards, which resampling and cropping both assume never happens.',
+    fields: [],
+  },
+  reverseIfNeeded: {
+    label: 'Reverse a descending x',
+    group: 'utility',
+    summary: 'Turns a descending axis the right way round.',
+    fields: [],
+    caution:
+      'The chain already does this before every step, so adding it here changes nothing.',
+  },
+} as const satisfies Record<string, FilterCatalogEntry>;

package/src/spectra/core/chainProblems.ts

@@ -0,0 +1,165 @@
+import { filterStepLabel, findFilterEntry } from './filterCatalog.ts';
+import type { SettingsProblem } from './problems.ts';
+import { problem } from './problems.ts';
+import type { SpectrumFilter, SpectrumFilterName } from './settings.ts';
+import { stepProblems } from './stepProblems.ts';
+
+/** The steps that all say "make the y scale comparable"; only the last survives. */
+const SCALING_STEPS: ReadonlySet<SpectrumFilterName> = new Set([
+  'divideBySD',
+  'normed',
+  'paretoNormalization',
+  'rescale',
+]);
+
+/** The steps that hand on plain arrays, whatever they were given. */
+const UNTYPES_X: ReadonlySet<SpectrumFilterName> = new Set([
+  'equallySpaced',
+  'filterX',
+]);
+
+/** The steps that read x as a typed array and throw on a plain one. */
+const NEEDS_TYPED_X: ReadonlySet<SpectrumFilterName> = new Set([
+  'calibrateX',
+  'fromTo',
+]);
+
+/**
+ * Everything wrong, or probably wrong, with one chain.
+ *
+ * The order of a chain is its meaning — scaling measured before a baseline is
+ * removed measures an offset that is about to change — so the advice below is
+ * as much about where a step sits as about what it is set to.
+ * @param chain - The steps, in the order they run.
+ * @param resampleFirst - Whether the settings resample before the chain runs.
+ * @returns Every problem found, errors and advice together.
+ */
+export function chainProblems(
+  chain: readonly SpectrumFilter[],
+  resampleFirst: boolean,
+): SettingsProblem[] {
+  const problems: SettingsProblem[] = [];
+  let baselines = 0;
+  let scalings = 0;
+  let firstScaling: number | undefined;
+  let plainX = resampleFirst;
+  let mayBePlainX = resampleFirst;
+
+  for (const [index, step] of chain.entries()) {
+    const where = filterStepLabel(step.name, index);
+    const entry = findFilterEntry(step.name);
+    problems.push(...stepProblems(step, where));
+
+    if (entry === undefined) {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          `${step.name} is not one of the steps this editor knows, so its options are left as they are. The processor throws on a name it cannot dispatch.`,
+        ),
+      );
+      continue;
+    }
+
+    if (NEEDS_TYPED_X.has(step.name)) {
+      if (plainX) {
+        problems.push(problem('error', where, TYPED_X_MESSAGE));
+      } else if (mayBePlainX) {
+        problems.push(problem('warning', where, MAY_BE_PLAIN_MESSAGE));
+      }
+    }
+    if (UNTYPES_X.has(step.name)) {
+      plainX = true;
+      mayBePlainX = true;
+    }
+    if (step.name === 'ensureGrowing') mayBePlainX = true;
+
+    const { group } = entry;
+    if (group === 'baseline') {
+      baselines++;
+      if (firstScaling !== undefined) {
+        problems.push(
+          problem(
+            'warning',
+            where,
+            `Step ${String(firstScaling + 1)} scales the signal before this levels it, so the scaling is measured against an offset that then changes. Level first.`,
+          ),
+        );
+        firstScaling = undefined;
+      }
+    }
+    if (SCALING_STEPS.has(step.name)) {
+      scalings++;
+      firstScaling ??= index;
+    }
+    if (step.name === 'reverseIfNeeded') {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          'The chain already turns a descending axis round before every step, so this one does nothing.',
+        ),
+      );
+    }
+    if (step.name === 'equallySpaced') {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          resampleFirst
+            ? 'The settings resample before the chain runs, so this resamples a second time and the point count set here is the one the matrix ends up with.'
+            : 'The settings resample after the chain runs, so this resamples a second time and the point count set above is the one the matrix ends up with.',
+        ),
+      );
+    }
+    if (
+      !resampleFirst &&
+      (step.name === 'xFunction' || step.name === 'calibrateX')
+    ) {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          'This changes the x axis before the resampling runs, so the range and the exclusions above are read in the new units.',
+        ),
+      );
+    }
+    if (resampleFirst && step.name === 'filterX') {
+      problems.push(
+        problem(
+          'warning',
+          where,
+          'Cropping after the resampling can leave each spectrum on its own grid, and the matrix then lines up rows that do not match. Pin the range above, or turn resampling back to last.',
+        ),
+      );
+    }
+  }
+
+  if (baselines > 1) {
+    problems.push(
+      problem(
+        'warning',
+        'The chain',
+        `${String(baselines)} baselines are subtracted one after another, each estimated from what the last one left.`,
+      ),
+    );
+  }
+  if (scalings > 1) {
+    problems.push(
+      problem(
+        'warning',
+        'The chain',
+        `${String(scalings)} steps set the y scale; only the last of them still shows in the result.`,
+      ),
+    );
+  }
+  return problems;
+}
+
+/** What a step reading x as a typed array is told when it cannot be one. */
+const TYPED_X_MESSAGE =
+  'This step reads x as a typed array, and resampling or cropping has already turned it into a plain one, so the processor throws. Move it before them, or turn resampling back to last.';
+
+/** The same, when only the data can settle whether x was untyped. */
+const MAY_BE_PLAIN_MESSAGE =
+  'This step reads x as a typed array. An earlier step turns x into a plain one whenever it has points to drop, and the processor then throws on this step.';

package/src/spectra/core/filterCatalog.ts

@@ -0,0 +1,100 @@
+import { AXIS_ENTRIES } from './axisEntries.ts';
+import type { FilterCatalogEntry } from './filterEntries.ts';
+import { BASELINE_ENTRIES, SIGNAL_ENTRIES } from './filterEntries.ts';
+import type { FilterGroup } from './filterFields.ts';
+import { FILTER_GROUPS } from './filterFields.ts';
+import type { SpectrumFilterName } from './settings.ts';
+
+/**
+ * What the editor knows about every step `filterXY` dispatches.
+ *
+ * Keyed by the name rather than listed, so the day `ml-signal-processing` adds
+ * a filter this object stops compiling and the gap is a build failure instead
+ * of a step nobody can reach.
+ */
+export const FILTER_CATALOG: Readonly<
+  Record<SpectrumFilterName, FilterCatalogEntry>
+> = {
+  ...BASELINE_ENTRIES,
+  ...SIGNAL_ENTRIES,
+  ...AXIS_ENTRIES,
+};
+
+/** Every step name, in the order the menu offers them. */
+export const FILTER_NAMES: readonly SpectrumFilterName[] = Object.keys(
+  FILTER_CATALOG,
+) as SpectrumFilterName[];
+
+/**
+ * What the editor knows about one step.
+ * @param name - The step's name.
+ * @returns Its catalog entry.
+ */
+export function filterEntry(name: SpectrumFilterName): FilterCatalogEntry {
+  return FILTER_CATALOG[name];
+}
+
+/**
+ * What the editor knows about a step whose name it may not recognise.
+ *
+ * The settings the processor accepts are typed `{ name: string }`, and
+ * `filterXY` really does dispatch four more names than the union declares, so a
+ * chain reaching the editor can name a step the catalog has never heard of.
+ * Answering nothing lets the panel say so; throwing would take the whole page
+ * down over one row.
+ * @param name - The step's name, from settings that may come from anywhere.
+ * @returns Its catalog entry, or undefined when the name is not one of the 23.
+ */
+export function findFilterEntry(name: string): FilterCatalogEntry | undefined {
+  return Object.hasOwn(FILTER_CATALOG, name)
+    ? FILTER_CATALOG[name as SpectrumFilterName]
+    : undefined;
+}
+
+/**
+ * How the panel labels one step of a chain, whether or not it knows the step.
+ * @param name - The step's name.
+ * @param position - Where it sits, counting from zero.
+ * @returns The label the row and every problem about it share.
+ */
+export function filterStepLabel(name: string, position: number): string {
+  return `Step ${String(position + 1)} — ${findFilterEntry(name)?.label ?? name}`;
+}
+
+/**
+ * The steps of one group, in menu order.
+ * @param group - Which part of the signal the steps work on.
+ * @returns Their names.
+ */
+export function filterNamesInGroup(
+  group: FilterGroup,
+): readonly SpectrumFilterName[] {
+  const names: SpectrumFilterName[] = [];
+  for (const name of FILTER_NAMES) {
+    if (FILTER_CATALOG[name].group === group) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * The whole menu, group by group, skipping a group that holds nothing.
+ *
+ * The 23 steps are unreadable as one list, and grouping them by what they touch
+ * is the same order a chain is usually built in: level the baseline, smooth,
+ * scale, then move the axis.
+ * @returns Each group with its steps.
+ */
+export function filterMenu(): ReadonlyArray<{
+  group: FilterGroup;
+  names: readonly SpectrumFilterName[];
+}> {
+  const menu: Array<{
+    group: FilterGroup;
+    names: readonly SpectrumFilterName[];
+  }> = [];
+  for (const group of FILTER_GROUPS) {
+    const names = filterNamesInGroup(group);
+    if (names.length > 0) menu.push({ group, names });
+  }
+  return menu;
+}