react-cheminfo 0.9.0 → 0.10.0

package/src/spectra/core/filterChain.ts

@@ -0,0 +1,194 @@
+import type { SpectrumFilter, SpectrumFilterName } from './settings.ts';
+
+/** What a step's options are, before any one filter's shape is assumed. */
+type OptionsRecord = Record<string, unknown>;
+
+/**
+ * The peak-picking `calibrateX` tunes for itself.
+ *
+ * Upstream reads these off the whole `gsd` object, so the moment the settings
+ * carry a `gsd` at all — even an empty one — every value here is replaced by
+ * ml-gsd's own, which pick peaks a four-hundredth as tall. The editor therefore
+ * writes them out in full rather than ever emitting a partial one.
+ */
+const CALIBRATE_PEAK_PICKING = {
+  maxCriteria: true,
+  minMaxRatio: 0.1,
+  realTopDetection: true,
+  smoothY: true,
+  sgOptions: { windowSize: 7, polynomial: 3 },
+};
+
+/**
+ * A new chain step, carrying only the options upstream cannot default safely.
+ * @param name - Which step to add.
+ * @returns The step.
+ */
+export function defaultFilter(name: SpectrumFilterName): SpectrumFilter {
+  if (name === 'calibrateX') {
+    return { name, options: { gsd: { ...CALIBRATE_PEAK_PICKING } } };
+  }
+  return { name };
+}
+
+/**
+ * The chain with one more step at the end.
+ * @param chain - The steps, in the order they run.
+ * @param name - Which step to add.
+ * @returns A new chain.
+ */
+export function addFilter(
+  chain: readonly SpectrumFilter[],
+  name: SpectrumFilterName,
+): SpectrumFilter[] {
+  return [...chain, defaultFilter(name)];
+}
+
+/**
+ * The chain without the step at that position.
+ * @param chain - The steps, in the order they run.
+ * @param index - Which step to drop.
+ * @returns A new chain.
+ */
+export function removeFilter(
+  chain: readonly SpectrumFilter[],
+  index: number,
+): SpectrumFilter[] {
+  return chain.filter((_, position) => position !== index);
+}
+
+/**
+ * The chain with the step at that position repeated just after it.
+ * @param chain - The steps, in the order they run.
+ * @param index - Which step to repeat.
+ * @returns A new chain.
+ */
+export function duplicateFilter(
+  chain: readonly SpectrumFilter[],
+  index: number,
+): SpectrumFilter[] {
+  const step = chain[index];
+  if (step === undefined) return [...chain];
+  return [
+    ...chain.slice(0, index + 1),
+    structuredClone(step),
+    ...chain.slice(index + 1),
+  ];
+}
+
+/**
+ * The chain with one step moved.
+ *
+ * Order is the whole meaning of a chain — scaling before a baseline correction
+ * measures an offset that is about to change — so moving a step is a first-class
+ * edit rather than something to be done by deleting and adding again.
+ * @param chain - The steps, in the order they run.
+ * @param index - Which step to move.
+ * @param offset - How far, negative towards the start.
+ * @returns A new chain, unchanged when the move would fall off either end.
+ */
+export function moveFilter(
+  chain: readonly SpectrumFilter[],
+  index: number,
+  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);
+  return moved;
+}
+
+/**
+ * What one option of a step is set to.
+ * @param filter - The step.
+ * @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;
+  for (const segment of key.split('.')) {
+    if (typeof current !== 'object' || current === null) return undefined;
+    current = (current as OptionsRecord)[segment];
+  }
+  return current;
+}
+
+/**
+ * The step with one option set, or dropped when the value is undefined.
+ *
+ * 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.
+ * @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.
+ * @returns A new step.
+ */
+export function setFilterOption(
+  filter: SpectrumFilter,
+  key: string,
+  value: unknown,
+): SpectrumFilter {
+  const written = writePath(filterOptions(filter), key.split('.'), value);
+  if (Object.keys(written).length === 0) return { name: filter.name };
+  return { name: filter.name, options: written };
+}
+
+/**
+ * The step's options as a plain record, for a form that walks the catalog.
+ * @param filter - The step.
+ * @returns Its options, empty when it carries none.
+ */
+export function filterOptions(filter: SpectrumFilter): Readonly<OptionsRecord> {
+  const options = 'options' in filter ? filter.options : undefined;
+  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.
+  return options as OptionsRecord;
+}
+
+/**
+ * A copy of the record with one path written, creating what it passes through.
+ * @param record - What to copy.
+ * @param path - The remaining segments.
+ * @param value - What to set, or undefined to drop the key.
+ * @returns A new record.
+ */
+function writePath(
+  record: Readonly<OptionsRecord>,
+  path: readonly string[],
+  value: unknown,
+): OptionsRecord {
+  const [head, ...rest] = path;
+  if (head === undefined) return { ...record };
+
+  if (rest.length === 0 && value === undefined) {
+    const kept: OptionsRecord = {};
+    for (const [name, held] of Object.entries(record)) {
+      if (name !== head) kept[name] = held;
+    }
+    return kept;
+  }
+
+  const next: OptionsRecord = { ...record };
+  if (rest.length === 0) {
+    next[head] = value;
+    return next;
+  }
+  const child = next[head];
+  const childRecord =
+    typeof child === 'object' && child !== null ? (child as OptionsRecord) : {};
+  const written = writePath(childRecord, rest, value);
+  // An emptied nested object is not the same as an absent one: upstream reads a
+  // present `gsd` as "options were given" and drops its own tuned defaults.
+  if (Object.keys(written).length === 0) {
+    return writePath(record, [head], undefined);
+  }
+  next[head] = written;
+  return next;
+}

package/src/spectra/core/filterEntries.ts

@@ -0,0 +1,214 @@
+import type { FilterField, FilterGroup } from './filterFields.ts';
+import {
+  enumField,
+  formulaField,
+  integerField,
+  numberField,
+  zonesField,
+} from './filterFields.ts';
+
+/** What the editor knows about one chain step. */
+export interface FilterCatalogEntry {
+  /** What the step is called. */
+  label: string;
+  /** Which part of the signal it works on. */
+  group: FilterGroup;
+  /** One sentence on what it does to the data. */
+  summary: string;
+  /** Its editable options, in the order they are drawn. */
+  fields: readonly FilterField[];
+  /**
+   * The parameters upstream fixes and does not forward, so a reader is told
+   * there are no knobs rather than left hunting for them.
+   * @default undefined — every parameter of the step is editable
+   */
+  fixed?: string;
+  /**
+   * The way the step is most often got wrong.
+   * @default undefined — the step holds no trap
+   */
+  caution?: string;
+}
+
+const SG_FIELDS: readonly FilterField[] = [
+  integerField(
+    'windowSize',
+    'Window size',
+    '9',
+    'An odd number of points, 5 or more.',
+  ),
+  integerField(
+    'polynomial',
+    'Polynomial degree',
+    '3',
+    'Below the window size; 6 and above oscillates.',
+  ),
+];
+
+/** The x bounds every cropping and resampling step asks for. */
+export const RANGE_FIELDS: readonly FilterField[] = [
+  numberField('from', 'From (x)', 'the first x'),
+  numberField('to', 'To (x)', 'the last x'),
+];
+
+/** The two zone lists a step offers when it can keep or drop stretches of x. */
+export const ZONE_FIELDS: readonly FilterField[] = [
+  zonesField('zones', 'Zones to keep'),
+  zonesField(
+    'exclusions',
+    'Zones to drop',
+    'Dropping wins: name zones or exclusions, not both.',
+  ),
+];
+
+/** The five baseline estimates, none of which forwards a parameter. */
+export const BASELINE_ENTRIES = {
+  airPLSBaseline: {
+    label: 'airPLS baseline',
+    group: 'baseline',
+    summary:
+      'Subtracts an asymmetrically weighted penalized least-squares baseline — the general-purpose choice for a broad drift.',
+    fields: [],
+    fixed: 'Fitted against the point index, 100 iterations, tolerance 0.001.',
+  },
+  iterativePolynomialBaseline: {
+    label: 'Iterative polynomial baseline',
+    group: 'baseline',
+    summary:
+      'Fits a polynomial to the signal, iterating until the peaks stop pulling it up.',
+    fields: [],
+    fixed: 'Fitted against the point index, 100 iterations, tolerance 0.001.',
+  },
+  rollingAverageBaseline: {
+    label: 'Rolling-average baseline',
+    group: 'baseline',
+    summary: 'Subtracts a rolling mean. Cheap, and it eats into a broad peak.',
+    fields: [],
+    fixed: 'Window of a tenth of the points, duplicated at the edges.',
+  },
+  rollingBallBaseline: {
+    label: 'Rolling-ball baseline',
+    group: 'baseline',
+    summary:
+      'Rolls a ball under the signal — the robust choice when peaks overlap.',
+    fields: [],
+    fixed: 'Windows of 4 % and 8 % of the points.',
+  },
+  rollingMedianBaseline: {
+    label: 'Rolling-median baseline',
+    group: 'baseline',
+    summary:
+      'Subtracts a rolling median, which a peak pulls on far less than a mean.',
+    fields: [],
+    fixed: 'Window of a tenth of the points, duplicated at the edges.',
+  },
+} as const satisfies Record<string, FilterCatalogEntry>;
+
+/** Smoothing, the derivatives, and everything that changes the y scale. */
+export const SIGNAL_ENTRIES = {
+  savitzkyGolay: {
+    label: 'Savitzky–Golay smoothing',
+    group: 'smoothing',
+    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,
+      integerField(
+        'derivative',
+        'Derivative',
+        '0',
+        'Zero smooths; one, two and three differentiate.',
+      ),
+    ],
+  },
+  firstDerivative: {
+    label: 'First derivative',
+    group: 'smoothing',
+    summary:
+      'dy/dx by Savitzky–Golay. Removes an additive baseline and turns every peak into a zero crossing.',
+    fields: SG_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,
+  },
+  thirdDerivative: {
+    label: 'Third derivative',
+    group: 'smoothing',
+    summary: 'd³y/dx³ by Savitzky–Golay. Rarely worth it: noise dominates.',
+    fields: SG_FIELDS,
+  },
+  centerMean: {
+    label: 'Centre on the mean',
+    group: 'scaling',
+    summary: 'Subtracts the mean of y, so the spectrum sits about zero.',
+    fields: [],
+  },
+  centerMedian: {
+    label: 'Centre on the median',
+    group: 'scaling',
+    summary:
+      'Subtracts the median of y — the same idea, unmoved by a few large peaks.',
+    fields: [],
+  },
+  divideBySD: {
+    label: 'Divide by the standard deviation',
+    group: 'scaling',
+    summary:
+      'Divides y by its standard deviation; after centring on the mean this is autoscaling.',
+    fields: [],
+  },
+  paretoNormalization: {
+    label: 'Pareto scaling',
+    group: 'scaling',
+    summary:
+      'Divides y by the square root of its standard deviation, so magnitude survives and noise is amplified less than by autoscaling.',
+    fields: [],
+  },
+  normed: {
+    label: 'Normalize',
+    group: 'scaling',
+    summary:
+      'Divides y so that a chosen aggregate reaches the value asked for.',
+    fields: [
+      enumField(
+        'algorithm',
+        'Divide by',
+        [
+          { value: 'absolute', label: 'Sum of absolute values' },
+          { value: 'max', label: 'Largest value' },
+          { value: 'sum', label: 'Signed sum' },
+        ],
+        'Largest value with 100 is the familiar “normalize to 100 %”.',
+      ),
+      numberField('value', 'Target', '1'),
+    ],
+  },
+  rescale: {
+    label: 'Rescale between two values',
+    group: 'scaling',
+    summary: 'Maps y linearly onto the range given.',
+    fields: [
+      numberField('min', 'Minimum', '0'),
+      numberField('max', 'Maximum', '1'),
+    ],
+  },
+  yFunction: {
+    label: 'Apply a formula to y',
+    group: 'y-axis',
+    summary:
+      'Rewrites every y through an expression. A run of lowercase letters is read as a Math function, so `log10(y)` works as typed.',
+    fields: [
+      formulaField(
+        'function',
+        'Expression in y',
+        'For instance -log10(y), which reads transmittance as absorbance.',
+      ),
+    ],
+  },
+} as const satisfies Record<string, FilterCatalogEntry>;
+
+/** Everything that moves, crops or resamples the x axis, and the two housekeeping steps. */

package/src/spectra/core/filterFields.ts

@@ -0,0 +1,159 @@
+/** What a chain step's option is edited with. */
+export type FilterFieldKind =
+  'boolean' | 'enum' | 'formula' | 'integer' | 'number' | 'zones';
+
+/** One choice of an `enum` field. */
+export interface FilterChoice {
+  /** What goes into the options object. */
+  value: string;
+  /** What the reader picks. */
+  label: string;
+}
+
+/** One editable option of a chain step. */
+export interface FilterField {
+  /**
+   * Where the value sits inside the step's `options`, dotted for a nested one
+   * such as `gsd.minMaxRatio`.
+   */
+  key: string;
+  /** What the field is called. */
+  label: string;
+  /** What it is edited with. */
+  kind: FilterFieldKind;
+  /**
+   * What upstream does when the field is left empty, shown in the control.
+   * @default undefined — the control carries no placeholder
+   */
+  placeholder?: string;
+  /**
+   * The choices, for an `enum` field.
+   * @default undefined — the field is not an enum
+   */
+  choices?: readonly FilterChoice[];
+  /**
+   * One line saying what the option changes, hung off the label.
+   * @default undefined — the label says enough
+   */
+  help?: string;
+}
+
+/** Which part of the signal a step works on, and so where it belongs in the menu. */
+export type FilterGroup =
+  'baseline' | 'scaling' | 'smoothing' | 'utility' | 'x-axis' | 'y-axis';
+
+/** The groups in the order a chain is usually built: shape, then scale, then axis. */
+export const FILTER_GROUPS: readonly FilterGroup[] = [
+  'baseline',
+  'smoothing',
+  'scaling',
+  'y-axis',
+  'x-axis',
+  'utility',
+];
+
+/** What each group is called above its slice of the menu. */
+export const FILTER_GROUP_LABELS: Readonly<Record<FilterGroup, string>> = {
+  baseline: 'Baseline',
+  smoothing: 'Smoothing and derivatives',
+  scaling: 'Scaling',
+  'y-axis': 'y axis',
+  'x-axis': 'x axis',
+  utility: 'Housekeeping',
+};
+
+/**
+ * A whole number field.
+ * @param key - Where the value sits in the step's options.
+ * @param label - What the field is called.
+ * @param placeholder - What upstream does when it is empty.
+ * @param help - One line saying what it changes.
+ * @returns The descriptor.
+ */
+export function integerField(
+  key: string,
+  label: string,
+  placeholder?: string,
+  help?: string,
+): FilterField {
+  return { key, label, kind: 'integer', placeholder, help };
+}
+
+/**
+ * A field taking any number.
+ * @param key - Where the value sits in the step's options.
+ * @param label - What the field is called.
+ * @param placeholder - What upstream does when it is empty.
+ * @param help - One line saying what it changes.
+ * @returns The descriptor.
+ */
+export function numberField(
+  key: string,
+  label: string,
+  placeholder?: string,
+  help?: string,
+): FilterField {
+  return { key, label, kind: 'number', placeholder, help };
+}
+
+/**
+ * A field taking one of a fixed set of values.
+ * @param key - Where the value sits in the step's options.
+ * @param label - What the field is called.
+ * @param choices - What may be picked.
+ * @param help - One line saying what it changes.
+ * @returns The descriptor.
+ */
+export function enumField(
+  key: string,
+  label: string,
+  choices: readonly FilterChoice[],
+  help?: string,
+): FilterField {
+  return { key, label, kind: 'enum', choices, help };
+}
+
+/**
+ * A yes-or-no field.
+ * @param key - Where the value sits in the step's options.
+ * @param label - What the field is called.
+ * @param help - One line saying what it changes.
+ * @returns The descriptor.
+ */
+export function booleanField(
+  key: string,
+  label: string,
+  help?: string,
+): FilterField {
+  return { key, label, kind: 'boolean', help };
+}
+
+/**
+ * A field taking an expression over one variable.
+ * @param key - Where the value sits in the step's options.
+ * @param label - What the field is called.
+ * @param help - One line saying what it changes.
+ * @returns The descriptor.
+ */
+export function formulaField(
+  key: string,
+  label: string,
+  help?: string,
+): FilterField {
+  return { key, label, kind: 'formula', help };
+}
+
+/**
+ * A field taking a list of `from` / `to` stretches.
+ * @param key - Where the value sits in the step's options.
+ * @param label - What the field is called.
+ * @param help - One line saying what it changes.
+ * @returns The descriptor.
+ */
+export function zonesField(
+  key: string,
+  label: string,
+  help?: string,
+): FilterField {
+  return { key, label, kind: 'zones', help };
+}

package/src/spectra/core/index.ts

@@ -0,0 +1,67 @@
+export type { ProblemSeverity, SettingsProblem } from './problems.ts';
+export { formulaProblem, isUsableLabel } from './problems.ts';
+export type { FilterCatalogEntry } from './filterEntries.ts';
+export type {
+  FilterChoice,
+  FilterField,
+  FilterFieldKind,
+  FilterGroup,
+} from './filterFields.ts';
+export { FILTER_GROUPS, FILTER_GROUP_LABELS } from './filterFields.ts';
+export {
+  FILTER_CATALOG,
+  FILTER_NAMES,
+  filterEntry,
+  filterMenu,
+  filterNamesInGroup,
+} from './filterCatalog.ts';
+export {
+  addFilter,
+  defaultFilter,
+  duplicateFilter,
+  filterOptions,
+  moveFilter,
+  readFilterOption,
+  removeFilter,
+  setFilterOption,
+} from './filterChain.ts';
+export type {
+  PrincipalComponentSelection,
+  PrincipalComponentSettings,
+} from './principalComponents.ts';
+export {
+  DEFAULT_PRINCIPAL_COMPONENTS,
+  PCA_METHODS,
+  clampPrincipalComponents,
+  principalComponentChoices,
+  principalComponentLabel,
+  selectedExplainedVariance,
+} from './principalComponents.ts';
+export type {
+  ExclusionZone,
+  MatrixFilter,
+  MatrixFilterName,
+  NormalizationSettings,
+  PostProcessingSettings,
+  ScaleMethod,
+  ScaleSettings,
+  SpectraCalculation,
+  SpectraProcessorSettings,
+  SpectraRange,
+  SpectraSettings,
+  SpectrumFilter,
+  SpectrumFilterName,
+} from './settings.ts';
+export {
+  DEFAULT_MAX_MEMORY,
+  DEFAULT_NUMBER_OF_POINTS,
+  EMPTY_SETTINGS,
+  normalizationFilters,
+  withNormalizationFilters,
+} from './settings.ts';
+export {
+  MATRIX_FILTER_NAMES,
+  SCALE_METHODS,
+  settingsProblems,
+} from './settingsProblems.ts';
+export { chainProblems } from './chainProblems.ts';