react-cheminfo 0.9.0 → 0.10.0

package/src/spectra/core/principalComponents.ts

@@ -0,0 +1,130 @@
+import type { PCAOptions } from 'ml-pca';
+
+/**
+ * How the principal components are computed.
+ *
+ * `spectra-processor` hands out the normalized matrix and stops there, so the
+ * decomposition is the consumer's `new PCA(matrix, options)` call — these are
+ * that call's options, read off `ml-pca` rather than retyped.
+ */
+export type PrincipalComponentSettings = Omit<PCAOptions, 'isCovarianceMatrix'>;
+
+/**
+ * Which two components a score plot is drawn against.
+ *
+ * Both are columns of the score matrix, counting from zero: `PC1` is `0`. The
+ * labels say `PC1` because that is what a chemist writes; the numbers stay
+ * zero-based because that is what indexes the matrix.
+ */
+export interface PrincipalComponentSelection {
+  /** The component along x — `0` is `PC1`. */
+  x: number;
+  /** The component along y — `1` is `PC2`. */
+  y: number;
+}
+
+/** The first two components, which is what a score plot opens on. */
+export const DEFAULT_PRINCIPAL_COMPONENTS: PrincipalComponentSelection = {
+  x: 0,
+  y: 1,
+};
+
+/** How `ml-pca` may be asked to decompose the matrix. */
+export const PCA_METHODS: ReadonlyArray<{
+  value: NonNullable<PCAOptions['method']>;
+  label: string;
+}> = [
+  { value: 'SVD', label: 'Singular value decomposition' },
+  { value: 'NIPALS', label: 'NIPALS' },
+  { value: 'covarianceMatrix', label: 'Covariance matrix' },
+];
+
+/**
+ * What one component is called, with the share of the variance it carries.
+ * @param index - The component, counting from zero.
+ * @param explainedVariance - What `pca.getExplainedVariance()` returned, as fractions.
+ * @returns For instance `PC1 — 74.2 %`, or just `PC1` when no variance is known.
+ */
+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)} %`;
+}
+
+/**
+ * Every component that can be picked, in order.
+ *
+ * A component nobody can read is worse than none, so the share of the variance
+ * travels with the label: a reader picking `PC7 — 0.3 %` can see they are about
+ * to plot noise.
+ * @param count - How many components the decomposition produced.
+ * @param explainedVariance - What `pca.getExplainedVariance()` returned.
+ * @returns The choices, one per component.
+ */
+export function principalComponentChoices(
+  count: number,
+  explainedVariance?: readonly number[],
+): ReadonlyArray<{ index: number; label: string }> {
+  const choices: Array<{ index: number; label: string }> = [];
+  for (let index = 0; index < count; index++) {
+    choices.push({
+      index,
+      label: principalComponentLabel(index, explainedVariance),
+    });
+  }
+  return choices;
+}
+
+/**
+ * The selection made safe against the decomposition that actually came back.
+ *
+ * A saved selection outlives the data it was made on: reload with fewer spectra
+ * and `PC8` no longer exists. Rather than let a plot ask for a column that is
+ * not there, the pair is pulled back inside what was computed, and the two axes
+ * are kept apart so the plot never collapses onto its diagonal.
+ * @param selection - What the reader picked, possibly on other data.
+ * @param count - How many components the decomposition produced.
+ * @returns A selection both of whose components exist.
+ */
+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 };
+}
+
+/**
+ * The share of the variance the two picked components carry together.
+ * @param selection - Which components are drawn.
+ * @param explainedVariance - What `pca.getExplainedVariance()` returned.
+ * @returns The sum as a fraction, or undefined when either share is unknown.
+ */
+export function selectedExplainedVariance(
+  selection: PrincipalComponentSelection,
+  explainedVariance: readonly number[],
+): number | undefined {
+  const along = explainedVariance[selection.x];
+  const up = explainedVariance[selection.y];
+  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

@@ -0,0 +1,143 @@
+/** How much a problem matters. */
+export type ProblemSeverity = 'error' | 'warning';
+
+/** Something the settings get wrong, or probably get wrong. */
+export interface SettingsProblem {
+  /**
+   * `error` when the processor throws or the matrix comes out wrong;
+   * `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. */
+  where: string;
+  /** What is wrong, in one sentence a reader can act on. */
+  message: string;
+}
+
+/**
+ * A problem, spelled out.
+ * @param severity - How much it matters.
+ * @param where - Which part of the settings it is about.
+ * @param message - What is wrong.
+ * @returns The problem.
+ */
+export function problem(
+  severity: ProblemSeverity,
+  where: string,
+  message: string,
+): SettingsProblem {
+  return { severity, where, message };
+}
+
+/**
+ * Whether a value is a number the processor can work with.
+ * @param value - What the settings hold.
+ * @returns True when it is a finite number.
+ */
+export function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+/**
+ * Whether a value is a whole number.
+ * @param value - What the settings hold.
+ * @returns True when it is a finite integer.
+ */
+export function isWholeNumber(value: unknown): value is number {
+  return isNumber(value) && Number.isInteger(value);
+}
+
+/**
+ * Whether a label can stand as the name of a variable.
+ *
+ * A range's label becomes a parameter of the function the calculations are
+ * compiled into, so a label with a space in it fails far from the field that
+ * caused it — which is why it is checked here instead.
+ * @param label - What the reader typed.
+ * @returns True when the label can be a variable name.
+ */
+export function isUsableLabel(label: string): boolean {
+  return /^[A-Za-z_$][\w$]*$/.test(label) && !RESERVED_WORDS.has(label);
+}
+
+/**
+ * What is wrong with an expression, as far as can be told without running it.
+ *
+ * The expression is compiled by the processor, not here, so this catches what
+ * a reader actually mistypes — an empty box, unclosed brackets, a variable that
+ * never appears — and stays silent about the rest rather than pretending to be
+ * a parser.
+ * @param formula - What the reader typed.
+ * @param variable - The one name the expression may read, `x` or `y`.
+ * @returns The complaint, or undefined when nothing obvious is wrong.
+ */
+export function formulaProblem(
+  formula: string,
+  variable: string,
+): string | undefined {
+  const trimmed = formula.trim();
+  if (trimmed === '') return 'The expression is empty.';
+  if (!new RegExp(String.raw`\b${variable}\b`).test(trimmed)) {
+    return `The expression never reads ${variable}, so every point would get the same value.`;
+  }
+  let depth = 0;
+  for (const character of trimmed) {
+    if (character === '(') depth++;
+    if (character === ')') depth--;
+    if (depth < 0) return 'A closing bracket has nothing to close.';
+  }
+  if (depth > 0) return 'A bracket is left open.';
+  return undefined;
+}
+
+/** The names a range may not take, because a function cannot be given them. */
+const RESERVED_WORDS: ReadonlySet<string> = new Set([
+  'arguments',
+  'await',
+  'break',
+  'case',
+  'catch',
+  'class',
+  'const',
+  'continue',
+  'debugger',
+  'default',
+  'delete',
+  'do',
+  'else',
+  'enum',
+  'eval',
+  'export',
+  'extends',
+  'false',
+  'finally',
+  'for',
+  'function',
+  'if',
+  'implements',
+  'import',
+  'in',
+  'instanceof',
+  'interface',
+  'let',
+  'new',
+  'null',
+  'package',
+  'private',
+  'protected',
+  'public',
+  'return',
+  'static',
+  'super',
+  'switch',
+  'this',
+  'throw',
+  'true',
+  'try',
+  'typeof',
+  'var',
+  'void',
+  'while',
+  'with',
+  'yield',
+]);

package/src/spectra/core/settings.ts

@@ -0,0 +1,119 @@
+/*
+ * The one file in the package that names `spectra-processor` and
+ * `ml-signal-processing`. Every type below is read off their published surface
+ * 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 { SpectraProcessor } from 'spectra-processor';
+
+/** Everything `new SpectraProcessor(…)` is built with. */
+export type SpectraProcessorSettings = NonNullable<
+  ConstructorParameters<typeof SpectraProcessor>[0]
+>;
+
+/**
+ * How every spectrum is brought onto one x grid. Until this is settled no two
+ * spectra can be compared, which is why it is the first thing the editor asks.
+ */
+export type NormalizationSettings = NonNullable<
+  SpectraProcessorSettings['normalization']
+>;
+
+/** A stretch of x the resampling grid skips. */
+export type ExclusionZone = NonNullable<
+  NormalizationSettings['exclusions']
+>[number];
+
+/** What `getPostProcessedData` reads, once every spectrum shares one grid. */
+export type PostProcessingSettings = NonNullable<
+  Parameters<SpectraProcessor['getPostProcessedData']>[0]
+>;
+
+/** How every spectrum is scaled onto a reference one. */
+export type ScaleSettings = NonNullable<PostProcessingSettings['scale']>;
+
+/** A named stretch of x whose integral is reported per spectrum. */
+export type SpectraRange = NonNullable<
+  PostProcessingSettings['ranges']
+>[number];
+
+/** A formula over the range integrals, reported per spectrum. */
+export type SpectraCalculation = NonNullable<
+  PostProcessingSettings['calculations']
+>[number];
+
+/** One step of the matrix stage, which works across spectra rather than along one. */
+export type MatrixFilter = NonNullable<
+  PostProcessingSettings['filters']
+>[number];
+
+/**
+ * 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.
+ */
+export type SpectrumFilter = FilterXYType;
+
+/** 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';
+
+/** Both settings objects the processor takes, which are independent of each other. */
+export interface SpectraSettings {
+  /** What the constructor is handed. */
+  processor: SpectraProcessorSettings;
+  /** What `getPostProcessedData` is handed. */
+  postProcessing: PostProcessingSettings;
+}
+
+/** The bytes of original data kept before the processor starts discarding it. */
+export const DEFAULT_MAX_MEMORY = 256 * 1024 * 1024;
+
+/** Points the injected resampling lands on when the settings name no number. */
+export const DEFAULT_NUMBER_OF_POINTS = 1024;
+
+/** Nothing set: the processor's own defaults, spelled out so a reset is one value. */
+export const EMPTY_SETTINGS: SpectraSettings = {
+  processor: { normalization: {} },
+  postProcessing: {},
+};
+
+/**
+ * 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.
+ * @param settings - What the constructor would be handed.
+ * @returns The chain steps, in the order they run.
+ */
+export function normalizationFilters(
+  settings: SpectraProcessorSettings,
+): readonly SpectrumFilter[] {
+  return (settings.normalization?.filters ?? []) as readonly SpectrumFilter[];
+}
+
+/**
+ * The same settings with a different chain, leaving every other field alone.
+ * @param settings - What the constructor would be handed.
+ * @param filters - The chain to put in its place.
+ * @returns A new settings object.
+ */
+export function withNormalizationFilters(
+  settings: SpectraProcessorSettings,
+  filters: readonly SpectrumFilter[],
+): SpectraProcessorSettings {
+  return {
+    ...settings,
+    normalization: { ...settings.normalization, filters: [...filters] },
+  };
+}

package/src/spectra/core/settingsProblems.ts

@@ -0,0 +1,222 @@
+import { chainProblems } from './chainProblems.ts';
+import type { SettingsProblem } from './problems.ts';
+import { isNumber, isUsableLabel, isWholeNumber, problem } from './problems.ts';
+import type {
+  MatrixFilterName,
+  ScaleMethod,
+  SpectraSettings,
+} from './settings.ts';
+import { normalizationFilters } from './settings.ts';
+
+/** The only three names `getPostProcessedData` matches; anything else throws. */
+export const MATRIX_FILTER_NAMES: readonly MatrixFilterName[] = [
+  'pqn',
+  'centerMean',
+  'rescale',
+];
+
+/** The only four scalings it matches, which it lower-cases before comparing. */
+export const SCALE_METHODS: readonly ScaleMethod[] = [
+  'min',
+  'max',
+  'minmax',
+  'integration',
+];
+
+/**
+ * Everything wrong, or probably wrong, with a whole settings object.
+ *
+ * Nothing here blocks: the editor is not a gate, and a reader mid-thought is
+ * allowed to hold settings that would throw. What it does is name the value the
+ * processor will fail on before the reader hands it over and reads a stack
+ * trace instead.
+ * @param settings - Both objects the processor would be handed.
+ * @returns Every problem found, errors and advice together.
+ */
+export function settingsProblems(settings: SpectraSettings): SettingsProblem[] {
+  const problems: SettingsProblem[] = [];
+  const normalization = settings.processor.normalization ?? {};
+  const where = 'Resampling';
+
+  const { from, to, numberOfPoints, exclusions } = normalization;
+  if (isNumber(from) && isNumber(to) && from >= to) {
+    problems.push(problem('error', where, 'From is not below to.'));
+  }
+  if (
+    numberOfPoints !== undefined &&
+    (!isWholeNumber(numberOfPoints) || numberOfPoints < 2)
+  ) {
+    problems.push(problem('error', where, 'A grid needs at least two points.'));
+  }
+  const { maxMemory } = settings.processor;
+  if (maxMemory !== undefined && (!isNumber(maxMemory) || maxMemory <= 0)) {
+    problems.push(
+      problem('error', 'Memory', 'The budget must be a number above zero.'),
+    );
+  }
+
+  for (const [index, zone] of (exclusions ?? []).entries()) {
+    const zoneWhere = `Excluded zone ${String(index + 1)}`;
+    if (!isNumber(zone.from) || !isNumber(zone.to) || zone.from >= zone.to) {
+      problems.push(problem('error', zoneWhere, 'From is not below to.'));
+    }
+    if (zone.ignore === true) {
+      problems.push(
+        problem(
+          'warning',
+          zoneWhere,
+          'Hidden only from the chart: the zone is still dropped from the data.',
+        ),
+      );
+    }
+  }
+
+  const { applyRangeSelectionFirst } = normalization;
+  problems.push(
+    ...chainProblems(
+      normalizationFilters(settings.processor),
+      applyRangeSelectionFirst === true,
+    ),
+    ...postProcessingProblems(settings),
+  );
+  return problems;
+}
+
+/**
+ * Everything wrong with the stage that works across spectra rather than along one.
+ * @param settings - Both objects the processor would be handed.
+ * @returns Its problems.
+ */
+function postProcessingProblems(settings: SpectraSettings): SettingsProblem[] {
+  const problems: SettingsProblem[] = [];
+  const { filters, scale, ranges, calculations } = settings.postProcessing;
+
+  for (const [index, step] of (filters ?? []).entries()) {
+    const where = `Matrix step ${String(index + 1)}`;
+    if (
+      step.name !== undefined &&
+      step.name !== '' &&
+      !MATRIX_FILTER_NAMES.includes(step.name as MatrixFilterName)
+    ) {
+      problems.push(
+        problem(
+          'error',
+          where,
+          `The matrix stage only knows ${MATRIX_FILTER_NAMES.join(', ')}; it throws on anything else.`,
+        ),
+      );
+    }
+  }
+
+  const method = scale?.method;
+  if (
+    method !== undefined &&
+    method !== '' &&
+    !SCALE_METHODS.includes(method.toLowerCase() as ScaleMethod)
+  ) {
+    problems.push(
+      problem(
+        'error',
+        'Scaling',
+        `Unknown scaling: ${method}. It throws on anything but ${SCALE_METHODS.join(', ')}.`,
+      ),
+    );
+  }
+  if (scale?.relative === true && scale.targetID === undefined) {
+    problems.push(
+      problem(
+        'warning',
+        'Scaling',
+        'The difference is taken against the first spectrum the processor holds, which is not necessarily one of those selected.',
+      ),
+    );
+  }
+
+  const labels = new Set<string>();
+  for (const [index, range] of (ranges ?? []).entries()) {
+    const where = `Range ${String(index + 1)}`;
+    const label = range.label ?? '';
+    if (label === '') {
+      problems.push(
+        problem('error', where, 'A range with no name is silently skipped.'),
+      );
+    } else if (!isUsableLabel(label)) {
+      problems.push(
+        problem(
+          'error',
+          where,
+          `${label} cannot be the name of a variable, and the calculations read it as one.`,
+        ),
+      );
+    } else if (labels.has(label)) {
+      problems.push(
+        problem('error', where, `${label} names two ranges; the second wins.`),
+      );
+    } else {
+      labels.add(label);
+    }
+    if (isNumber(range.from) && isNumber(range.to) && range.from >= range.to) {
+      problems.push(problem('error', where, 'From is not below to.'));
+    }
+  }
+
+  for (const [index, calculation] of (calculations ?? []).entries()) {
+    const where = `Calculation ${String(index + 1)}`;
+    if (!isUsableLabel(calculation.label)) {
+      problems.push(
+        problem(
+          'error',
+          where,
+          'A calculation needs a name that can be a variable.',
+        ),
+      );
+    }
+    const complaint = calculationProblem(calculation.formula, labels);
+    if (complaint !== undefined) {
+      problems.push(problem('error', where, complaint));
+    }
+  }
+  if ((calculations ?? []).length > 0 && labels.size === 0) {
+    problems.push(
+      problem(
+        'error',
+        'Calculations',
+        'A calculation reads the range integrals, and no range is named.',
+      ),
+    );
+  }
+  return problems;
+}
+
+/**
+ * What is wrong with a calculation, as far as can be told without running it.
+ * @param formula - What the reader typed.
+ * @param labels - The range names it may read.
+ * @returns The complaint, or undefined when nothing obvious is wrong.
+ */
+function calculationProblem(
+  formula: string,
+  labels: ReadonlySet<string>,
+): string | undefined {
+  const trimmed = formula.trim();
+  if (trimmed === '') return 'The formula is empty.';
+  let depth = 0;
+  for (const character of trimmed) {
+    if (character === '(') depth++;
+    if (character === ')') depth--;
+    if (depth < 0) return 'A closing bracket has nothing to close.';
+  }
+  if (depth > 0) return 'A bracket is left open.';
+
+  // The lookbehind keeps the exponent of a number such as `1e3` from reading
+  // as the name of a range.
+  const named =
+    trimmed.replaceAll(/\.\w+/g, '').match(/(?<![\w$.])[A-Za-z_$][\w$]*/g) ??
+    [];
+  for (const name of named) {
+    if (name !== 'Math' && !labels.has(name)) {
+      return `${name} is not the name of a range, so the formula would throw.`;
+    }
+  }
+  return undefined;
+}