react-cheminfo 0.10.0 → 0.12.0

package/src/spectra/core/filterChain.ts

@@ -1,4 +1,25 @@
-import type { SpectrumFilter, SpectrumFilterName } from './settings.ts';
+import type {
+  MatrixFilter,
+  SpectrumFilter,
+  SpectrumFilterName,
+} from './settings.ts';
+
+/**
+ * A step of either stage, as far as its options go: a chain step and a matrix
+ * step both have this shape, so one reader and one writer serve both.
+ */
+export interface FilterStep {
+  /**
+   * The step's name.
+   * @default undefined — a matrix step may carry none, and is then skipped
+   */
+  name?: string;
+  /**
+   * The step's options, whatever shape they turn out to be.
+   * @default undefined — upstream's defaults apply
+   */
+  options?: unknown;
+}
 
 /** What a step's options are, before any one filter's shape is assumed. */
 type OptionsRecord = Record<string, unknown>;
@@ -28,7 +49,10 @@ export function defaultFilter(name: SpectrumFilterName): SpectrumFilter {
   if (name === 'calibrateX') {
     return { name, options: { gsd: { ...CALIBRATE_PEAK_PICKING } } };
   }
-  return { name };
+  // TypeScript matches an object literal against a discriminated union of at
+  // most 25 members, and the chain has more. Every step's options are optional
+  // upstream, so a bare name is a whole step of whichever filter it names.
+  return { name } as SpectrumFilter;
 }
 
 /**
@@ -54,7 +78,8 @@ export function removeFilter(
   chain: readonly SpectrumFilter[],
   index: number,
 ): SpectrumFilter[] {
-  return chain.filter((_, position) => position !== index);
+  if (index < 0 || index >= chain.length) return [...chain];
+  return chain.toSpliced(index, 1);
 }
 
 /**
@@ -69,11 +94,7 @@ export function duplicateFilter(
 ): SpectrumFilter[] {
   const step = chain[index];
   if (step === undefined) return [...chain];
-  return [
-    ...chain.slice(0, index + 1),
-    structuredClone(step),
-    ...chain.slice(index + 1),
-  ];
+  return chain.toSpliced(index + 1, 0, structuredClone(step));
 }
 
 /**
@@ -93,24 +114,37 @@ export function moveFilter(
   offset: number,
 ): SpectrumFilter[] {
   const target = index + offset;
-  const step = chain[index];
-  if (step === undefined || target < 0 || target >= chain.length) {
-    return [...chain];
-  }
-  const moved = [...chain];
-  moved.splice(index, 1);
-  moved.splice(target, 0, step);
+  if (index < 0 || index >= chain.length) return [...chain];
+  if (target < 0 || target >= chain.length) return [...chain];
+  return reorder(chain, index, target);
+}
+
+/**
+ * A list with one entry moved to another position.
+ * @param list - What to reorder.
+ * @param index - Which entry to move.
+ * @param target - Where it lands.
+ * @returns A new list, the same entries when there is nothing at `index`.
+ */
+export function reorder<T>(
+  list: readonly T[],
+  index: number,
+  target: number,
+): T[] {
+  const moved = [...list];
+  const [entry] = moved.splice(index, 1);
+  if (entry !== undefined) moved.splice(target, 0, entry);
   return moved;
 }
 
 /**
  * What one option of a step is set to.
- * @param filter - The step.
+ * @param filter - The step, of the chain or of the matrix stage.
  * @param key - Where the value sits, dotted for a nested one.
  * @returns The value, or undefined when the step leaves it to upstream.
  */
-export function readFilterOption(filter: SpectrumFilter, key: string): unknown {
-  let current: unknown = 'options' in filter ? filter.options : undefined;
+export function readFilterOption(filter: FilterStep, key: string): unknown {
+  let current: unknown = filter.options;
   for (const segment of key.split('.')) {
     if (typeof current !== 'object' || current === null) return undefined;
     current = (current as OptionsRecord)[segment];
@@ -123,7 +157,9 @@ export function readFilterOption(filter: SpectrumFilter, key: string): unknown {
  *
  * Dropping rather than writing `undefined` is what lets a cleared field mean
  * "whatever upstream does", which is the only way a reader can get back to the
- * default once they have typed over it.
+ * default once they have typed over it. Options that are not an object are
+ * thrown away rather than read, so a written step is always one the processor
+ * can take.
  * @param filter - The step.
  * @param key - Where the value sits, dotted for a nested one.
  * @param value - What to set it to, or undefined to clear it.
@@ -133,19 +169,48 @@ export function setFilterOption(
   filter: SpectrumFilter,
   key: string,
   value: unknown,
-): SpectrumFilter {
+): SpectrumFilter;
+export function setFilterOption(
+  filter: MatrixFilter,
+  key: string,
+  value: unknown,
+): MatrixFilter;
+export function setFilterOption(
+  filter: FilterStep,
+  key: string,
+  value: unknown,
+): FilterStep {
   const written = writePath(filterOptions(filter), key.split('.'), value);
   if (Object.keys(written).length === 0) return { name: filter.name };
   return { name: filter.name, options: written };
 }
 
+/**
+ * One option of a step as a number box can show it.
+ *
+ * Anything that is not a number — a bound pasted in as text, a `null` — reads
+ * as nothing, so the box shows its placeholder rather than junk.
+ * @param filter - The step, of the chain or of the matrix stage.
+ * @param key - Where the value sits, dotted for a nested one.
+ * @returns The number, or undefined when the step holds none there.
+ */
+export function readNumberOption(
+  filter: FilterStep,
+  key: string,
+): number | undefined {
+  const value = readFilterOption(filter, key);
+  return typeof value === 'number' ? value : undefined;
+}
+
 /**
  * The step's options as a plain record, for a form that walks the catalog.
- * @param filter - The step.
+ * @param filter - The step, of the chain or of the matrix stage.
  * @returns Its options, empty when it carries none.
  */
-export function filterOptions(filter: SpectrumFilter): Readonly<OptionsRecord> {
-  const options = 'options' in filter ? filter.options : undefined;
+export function filterOptions(
+  filter: FilterStep,
+): Readonly<Record<string, unknown>> {
+  const { options } = filter;
   if (typeof options !== 'object' || options === null) return {};
   // An interface carries no index signature, so a form that walks the catalog
   // has to read it as the record the catalog's keys describe.

package/src/spectra/core/filterEntries.ts

@@ -30,7 +30,8 @@ export interface FilterCatalogEntry {
   caution?: string;
 }
 
-const SG_FIELDS: readonly FilterField[] = [
+/** The window and degree every Savitzky–Golay step asks for. */
+const SAVITZKY_GOLAY_FIELDS: readonly FilterField[] = [
   integerField(
     'windowSize',
     'Window size',
@@ -112,7 +113,7 @@ export const SIGNAL_ENTRIES = {
     summary:
       'Fits a polynomial over a sliding window; with a derivative above zero it is the general form of the three below.',
     fields: [
-      ...SG_FIELDS,
+      ...SAVITZKY_GOLAY_FIELDS,
       integerField(
         'derivative',
         'Derivative',
@@ -126,20 +127,20 @@ export const SIGNAL_ENTRIES = {
     group: 'smoothing',
     summary:
       'dy/dx by Savitzky–Golay. Removes an additive baseline and turns every peak into a zero crossing.',
-    fields: SG_FIELDS,
+    fields: SAVITZKY_GOLAY_FIELDS,
   },
   secondDerivative: {
     label: 'Second derivative',
     group: 'smoothing',
     summary:
       'd²y/dx² by Savitzky–Golay — the classic way to pull apart overlapping infrared bands.',
-    fields: SG_FIELDS,
+    fields: SAVITZKY_GOLAY_FIELDS,
   },
   thirdDerivative: {
     label: 'Third derivative',
     group: 'smoothing',
     summary: 'd³y/dx³ by Savitzky–Golay. Rarely worth it: noise dominates.',
-    fields: SG_FIELDS,
+    fields: SAVITZKY_GOLAY_FIELDS,
   },
   centerMean: {
     label: 'Centre on the mean',
@@ -209,6 +210,20 @@ export const SIGNAL_ENTRIES = {
       ),
     ],
   },
+  setMinY: {
+    label: 'Shift y to start at a value',
+    group: 'y-axis',
+    summary:
+      'Adds one constant to every y so the smallest lands on the value given — a shift, not a rescale.',
+    fields: [numberField('min', 'Smallest y', '0')],
+    caution: 'Left empty, the smallest y is moved to 0, not left where it is.',
+  },
+  setMaxY: {
+    label: 'Shift y to end at a value',
+    group: 'y-axis',
+    summary:
+      'Adds one constant to every y so the largest lands on the value given — a shift, not a rescale.',
+    fields: [numberField('max', 'Largest y', '1')],
+    caution: 'Left empty, the largest y is moved to 1, not left where it is.',
+  },
 } as const satisfies Record<string, FilterCatalogEntry>;
-
-/** Everything that moves, crops or resamples the x axis, and the two housekeeping steps. */

package/src/spectra/core/index.ts

@@ -1,4 +1,8 @@
-export type { ProblemSeverity, SettingsProblem } from './problems.ts';
+export type {
+  ProblemPart,
+  ProblemSeverity,
+  SettingsProblem,
+} from './problems.ts';
 export { formulaProblem, isUsableLabel } from './problems.ts';
 export type { FilterCatalogEntry } from './filterEntries.ts';
 export type {
@@ -15,6 +19,7 @@ export {
   filterMenu,
   filterNamesInGroup,
 } from './filterCatalog.ts';
+export type { FilterStep } from './filterChain.ts';
 export {
   addFilter,
   defaultFilter,
@@ -40,10 +45,8 @@ export {
 export type {
   ExclusionZone,
   MatrixFilter,
-  MatrixFilterName,
   NormalizationSettings,
   PostProcessingSettings,
-  ScaleMethod,
   ScaleSettings,
   SpectraCalculation,
   SpectraProcessorSettings,
@@ -59,9 +62,7 @@ export {
   normalizationFilters,
   withNormalizationFilters,
 } from './settings.ts';
-export {
-  MATRIX_FILTER_NAMES,
-  SCALE_METHODS,
-  settingsProblems,
-} from './settingsProblems.ts';
+export type { MatrixFilterName, ScaleMethod } from './matrixCatalog.ts';
+export { MATRIX_FILTER_NAMES, SCALE_METHODS } from './matrixCatalog.ts';
+export { settingsProblems } from './settingsProblems.ts';
 export { chainProblems } from './chainProblems.ts';

package/src/spectra/core/matrixCatalog.ts

@@ -0,0 +1,111 @@
+/** The only three names `getPostProcessedData` matches; anything else throws. */
+export const MATRIX_FILTER_NAMES = ['pqn', 'centerMean', 'rescale'] as const;
+
+/** The three names `getPostProcessedData`'s own switch matches. */
+export type MatrixFilterName = (typeof MATRIX_FILTER_NAMES)[number];
+
+/** The only four scalings it matches, which it lower-cases before comparing. */
+export const SCALE_METHODS = ['min', 'max', 'minmax', 'integration'] as const;
+
+/** The four scalings `getPostProcessedData` matches, lower-cased. */
+export type ScaleMethod = (typeof SCALE_METHODS)[number];
+
+/** What each scaling is called, in the order the processor's switch lists them. */
+export const SCALE_METHOD_LABELS = {
+  min: 'Smallest value',
+  max: 'Largest value',
+  minmax: 'Both ends',
+  integration: 'Integral',
+} as const satisfies Record<ScaleMethod, string>;
+
+/** One editable option of a matrix step. */
+interface MatrixOptionField {
+  /** Which key it sits under in the step's options. */
+  key: string;
+  /** What the field is called. */
+  label: string;
+  /**
+   * What upstream does when it is left empty.
+   * @default undefined — the field carries no placeholder
+   */
+  placeholder?: string;
+}
+
+/** What the editor knows about one matrix step. */
+interface MatrixStep {
+  /** What it is called in the list. */
+  label: string;
+  /** One line saying what it does to the matrix. */
+  summary: string;
+  /** Its editable options, empty when it takes none. */
+  fields: readonly MatrixOptionField[];
+}
+
+/**
+ * What the editor knows about the three steps the matrix stage dispatches.
+ *
+ * Keyed by the name rather than listed, so a name the processor's own switch
+ * does not match cannot reach the menu: an unknown name is the one way this
+ * stage throws.
+ */
+export const MATRIX_STEPS: Readonly<Record<MatrixFilterName, MatrixStep>> = {
+  pqn: {
+    label: 'Probabilistic quotient normalization',
+    summary:
+      'Divides every spectrum by its own dilution factor, read against the median spectrum. Min is declared upstream but never read.',
+    fields: [
+      { key: 'min', label: 'Min' },
+      { key: 'max', label: 'Max', placeholder: '100' },
+    ],
+  },
+  centerMean: {
+    label: 'Centre on the mean',
+    summary:
+      'Subtracts the mean of every column. It takes no options: anything set here is ignored.',
+    fields: [],
+  },
+  rescale: {
+    label: 'Rescale',
+    summary: 'Brings the whole matrix between two values.',
+    fields: [
+      { key: 'min', label: 'Min', placeholder: '0' },
+      { key: 'max', label: 'Max', placeholder: '1' },
+    ],
+  },
+};
+
+/**
+ * Whether a name is one the matrix stage dispatches, spelled exactly.
+ * @param name - The name the settings hold.
+ * @returns True for `pqn`, `centerMean` and `rescale`.
+ */
+export function isMatrixFilterName(name: string): name is MatrixFilterName {
+  for (const known of MATRIX_FILTER_NAMES) {
+    if (known === name) return true;
+  }
+  return false;
+}
+
+/**
+ * Whether a lower-cased method is one of the four scalings.
+ * @param method - The method, already lower-cased as the processor compares it.
+ * @returns True for `min`, `max`, `minmax` and `integration`.
+ */
+export function isScaleMethod(method: string): method is ScaleMethod {
+  for (const known of SCALE_METHODS) {
+    if (known === method) return true;
+  }
+  return false;
+}
+
+/**
+ * What the editor knows about a matrix step, when it knows it at all.
+ * @param name - The name the settings hold.
+ * @returns Its entry, or undefined for a name the processor would throw on.
+ */
+export function findMatrixStep(
+  name: string | undefined,
+): MatrixStep | undefined {
+  if (name === undefined || !isMatrixFilterName(name)) return undefined;
+  return MATRIX_STEPS[name];
+}

package/src/spectra/core/principalComponents.ts

@@ -1,5 +1,8 @@
 import type { PCAOptions } from 'ml-pca';
 
+import { clampAxisPair } from '../../chart/core/chartAxisPair.ts';
+import { chartAxisTitle } from '../../chart/core/chartLabels.ts';
+
 /**
  * How the principal components are computed.
  *
@@ -49,10 +52,9 @@ export function principalComponentLabel(
   index: number,
   explainedVariance?: readonly number[],
 ): string {
-  const name = `PC${String(index + 1)}`;
-  const share = explainedVariance?.[index];
-  if (share === undefined || !Number.isFinite(share)) return name;
-  return `${name} — ${(share * 100).toFixed(1)} %`;
+  return chartAxisTitle(`PC${String(index + 1)}`, {
+    share: explainedVariance?.[index],
+  });
 }
 
 /**
@@ -94,12 +96,7 @@ export function clampPrincipalComponents(
   selection: PrincipalComponentSelection,
   count: number,
 ): PrincipalComponentSelection {
-  if (count < 1) return { x: 0, y: 0 };
-  const last = count - 1;
-  const x = clamp(selection.x, last);
-  let y = clamp(selection.y, last);
-  if (y === x && count > 1) y = x === 0 ? 1 : x - 1;
-  return { x, y };
+  return clampAxisPair(selection.x, selection.y, count);
 }
 
 /**
@@ -117,14 +114,3 @@ export function selectedExplainedVariance(
   if (along === undefined || up === undefined) return undefined;
   return along + up;
 }
-
-/**
- * A component index brought inside the components that exist.
- * @param index - What was asked for.
- * @param last - The highest component there is.
- * @returns A whole number between zero and `last`.
- */
-function clamp(index: number, last: number): number {
-  if (!Number.isFinite(index)) return 0;
-  return Math.min(Math.max(Math.round(index), 0), last);
-}

package/src/spectra/core/problems.ts

@@ -1,6 +1,17 @@
 /** How much a problem matters. */
 export type ProblemSeverity = 'error' | 'warning';
 
+/** Which part of the settings a problem is about, which is how a panel finds its own. */
+export type ProblemPart =
+  | 'calculation'
+  | 'chain'
+  | 'exclusion'
+  | 'matrix'
+  | 'memory'
+  | 'range'
+  | 'resampling'
+  | 'scaling';
+
 /** Something the settings get wrong, or probably get wrong. */
 export interface SettingsProblem {
   /**
@@ -8,25 +19,42 @@ export interface SettingsProblem {
    * `warning` when it runs and the reader most likely did not mean it.
    */
   severity: ProblemSeverity;
-  /** Which part of the settings it is about, as the panel labels that part. */
+  /**
+   * Which part of the settings it is about. A panel picks its problems by this,
+   * never by `where`, so rewording a label cannot lose a problem.
+   */
+  part: ProblemPart;
+  /**
+   * Which entry of the part, counting from zero: a step of the chain, a zone,
+   * a matrix step, a range, a calculation.
+   * @default undefined — the problem is about the part as a whole
+   */
+  index?: number;
+  /** How the panel labels the place, written before the message. */
   where: string;
   /** What is wrong, in one sentence a reader can act on. */
   message: string;
 }
 
+/** Where a problem sits: everything about it except how bad it is and what it says. */
+export type ProblemPlace = Pick<SettingsProblem, 'index' | 'part' | 'where'>;
+
 /**
  * A problem, spelled out.
  * @param severity - How much it matters.
- * @param where - Which part of the settings it is about.
+ * @param place - Which part, which entry of it, and how the panel labels it.
  * @param message - What is wrong.
- * @returns The problem.
+ * @returns The problem, with no `index` key at all when the place names none.
  */
 export function problem(
   severity: ProblemSeverity,
-  where: string,
+  place: ProblemPlace,
   message: string,
 ): SettingsProblem {
-  return { severity, where, message };
+  const { part, index, where } = place;
+  return index === undefined
+    ? { severity, part, where, message }
+    : { severity, part, index, where, message };
 }
 
 /**
@@ -80,8 +108,17 @@ export function formulaProblem(
   if (!new RegExp(String.raw`\b${variable}\b`).test(trimmed)) {
     return `The expression never reads ${variable}, so every point would get the same value.`;
   }
+  return bracketProblem(trimmed);
+}
+
+/**
+ * What is wrong with the brackets of an expression.
+ * @param expression - What the reader typed, already trimmed.
+ * @returns The complaint, or undefined when every bracket is closed in order.
+ */
+export function bracketProblem(expression: string): string | undefined {
   let depth = 0;
-  for (const character of trimmed) {
+  for (const character of expression) {
     if (character === '(') depth++;
     if (character === ')') depth--;
     if (depth < 0) return 'A closing bracket has nothing to close.';

package/src/spectra/core/settings.ts

@@ -4,7 +4,13 @@
  * rather than retyped, so a change upstream is a compile error here instead of
  * a settings object the processor quietly rejects.
  */
-import type { FilterXYType } from 'ml-signal-processing';
+import type {
+  FilterXYType,
+  SetMaxXFilter,
+  SetMaxYFilter,
+  SetMinXFilter,
+  SetMinYFilter,
+} from 'ml-signal-processing';
 import type { SpectraProcessor } from 'spectra-processor';
 
 /** Everything `new SpectraProcessor(…)` is built with. */
@@ -52,19 +58,16 @@ export type MatrixFilter = NonNullable<
  * One step of the per-spectrum chain.
  *
  * `spectra-processor` types the same array as `{ name: string }`, which accepts
- * names `filterXY` throws on. The editor holds the union `filterXY` actually
- * dispatches, so a chain that type-checks is a chain that runs.
+ * names `filterXY` throws on. The editor holds the names `filterXY` actually
+ * dispatches, so a chain that type-checks is a chain that runs. That is
+ * `FilterXYType` plus the four `set…` shifts it leaves out: `filterXY` looks a
+ * name up among every export of its filters module, and those four are there.
  */
-export type SpectrumFilter = FilterXYType;
+export type SpectrumFilter =
+  FilterXYType | SetMaxXFilter | SetMaxYFilter | SetMinXFilter | SetMinYFilter;
 
-/** The name of a chain step — the 23 `filterXY` knows. */
-export type SpectrumFilterName = FilterXYType['name'];
-
-/** The three names `getPostProcessedData`'s own switch matches. */
-export type MatrixFilterName = 'centerMean' | 'pqn' | 'rescale';
-
-/** The four scalings `getPostProcessedData` matches, lower-cased. */
-export type ScaleMethod = 'integration' | 'max' | 'min' | 'minmax';
+/** The name of a chain step — the 27 `filterXY` dispatches. */
+export type SpectrumFilterName = SpectrumFilter['name'];
 
 /** Both settings objects the processor takes, which are independent of each other. */
 export interface SpectraSettings {
@@ -89,10 +92,10 @@ export const EMPTY_SETTINGS: SpectraSettings = {
 /**
  * The chain as the editor understands it.
  *
- * The single cast in the package. Upstream types the array as
- * `{ name: string; options?: any }[]` while its own `getNormalized` types the
- * very same array as `FilterXYType[]`; this reads it back at the narrower type
- * its consumer already assumes.
+ * The cast is sound because upstream types the array as
+ * `{ name: string; options?: any }[]` while its own `getNormalized` hands the
+ * very same array to `filterXY`; this reads it back at the narrower type that
+ * consumer already assumes.
  * @param settings - What the constructor would be handed.
  * @returns The chain steps, in the order they run.
  */