react-cheminfo 0.9.0 → 0.10.0

package/src/spectra/ui/PrincipalComponentSelect.tsx

@@ -0,0 +1,245 @@
+import { HTMLSelect, Switch } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import type {
+  PrincipalComponentSelection,
+  PrincipalComponentSettings,
+} from '../core/principalComponents.ts';
+import {
+  PCA_METHODS,
+  clampPrincipalComponents,
+  principalComponentChoices,
+  selectedExplainedVariance,
+} from '../core/principalComponents.ts';
+
+import { NumberField } from './NumberField.tsx';
+
+/** What {@link PrincipalComponentSelect} picks. */
+export interface PrincipalComponentSelectProps {
+  /** Which two components are drawn. Both are columns of the score matrix, counting from zero. */
+  value: PrincipalComponentSelection;
+  /** Called with the pair whenever either axis changes. */
+  onChange: (selection: PrincipalComponentSelection) => void;
+  /** How many components the decomposition produced. */
+  count: number;
+  /**
+   * What `pca.getExplainedVariance()` returned, as fractions in component order.
+   * @default undefined — the choices read `PC1` alone and no total is drawn
+   */
+  explainedVariance?: readonly number[];
+  /**
+   * The options the decomposition was asked for.
+   * @default undefined — the decomposition's own options are not offered
+   */
+  settings?: PrincipalComponentSettings;
+  /**
+   * Called with the options whenever one of them changes.
+   * @default undefined — the decomposition's own options are not offered
+   */
+  onSettingsChange?: (settings: PrincipalComponentSettings) => void;
+}
+
+/**
+ * Which two principal components a score plot is drawn against.
+ *
+ * This is the one control here that reports on its own rather than through the
+ * settings object, so `onChange` is the whole contract and fires on every pick.
+ * What it hands up stays zero-based even though the labels read `PC1`, because
+ * a reader who takes those numbers straight to the score matrix has to land on
+ * the right column: shifting by one would draw the wrong component under the
+ * right name.
+ * @param props - See {@link PrincipalComponentSelectProps}.
+ * @returns The two pickers, and the decomposition's options when both are given.
+ */
+export function PrincipalComponentSelect(
+  props: PrincipalComponentSelectProps,
+): ReactElement {
+  const {
+    value,
+    onChange,
+    count,
+    explainedVariance,
+    settings,
+    onSettingsChange,
+  } = props;
+  const selection = clampPrincipalComponents(value, count);
+  const share = selectedExplainedVariance(selection, explainedVariance ?? []);
+  const choices = principalComponentChoices(count, explainedVariance).map(
+    (choice) => (
+      <option key={choice.index} value={choice.index}>
+        {choice.label}
+      </option>
+    ),
+  );
+
+  function pick(next: PrincipalComponentSelection): void {
+    onChange(clampPrincipalComponents(next, count));
+  }
+
+  return (
+    <div style={ROOT_STYLE}>
+      <div style={ROW_STYLE}>
+        <label style={FIELD_STYLE}>
+          <span style={LABEL_STYLE}>Horizontal axis</span>
+          <HTMLSelect
+            fill
+            value={String(selection.x)}
+            onChange={(event) => {
+              pick({ x: Number(event.currentTarget.value), y: selection.y });
+            }}
+          >
+            {choices}
+          </HTMLSelect>
+        </label>
+        <label style={FIELD_STYLE}>
+          <span style={LABEL_STYLE}>Vertical axis</span>
+          <HTMLSelect
+            fill
+            value={String(selection.y)}
+            onChange={(event) => {
+              pick({ x: selection.x, y: Number(event.currentTarget.value) });
+            }}
+          >
+            {choices}
+          </HTMLSelect>
+        </label>
+      </div>
+      {share === undefined ? null : (
+        <span style={HELP_STYLE}>
+          {`Together they carry ${(share * 100).toFixed(1)} % of the variance.`}
+        </span>
+      )}
+      {settings === undefined || onSettingsChange === undefined ? null : (
+        <DecompositionFields settings={settings} onChange={onSettingsChange} />
+      )}
+    </div>
+  );
+}
+
+/** What {@link DecompositionFields} edits. */
+interface DecompositionFieldsProps {
+  /** The options the decomposition was asked for. */
+  settings: PrincipalComponentSettings;
+  /** Called with the options whenever one of them changes. */
+  onChange: (settings: PrincipalComponentSettings) => void;
+}
+
+/**
+ * How `ml-pca` is asked to decompose the matrix.
+ *
+ * The NIPALS count is drawn only under NIPALS, the one method that reads it.
+ * @param props - See {@link DecompositionFieldsProps}.
+ * @returns The decomposition's own options.
+ */
+function DecompositionFields(props: DecompositionFieldsProps): ReactElement {
+  const { settings, onChange } = props;
+  const method = settings.method ?? 'SVD';
+
+  function write(patch: PrincipalComponentSettings): void {
+    onChange({ ...settings, ...patch });
+  }
+
+  return (
+    <div style={OPTIONS_STYLE}>
+      <label style={FIELD_STYLE}>
+        <span style={LABEL_STYLE}>Method</span>
+        <HTMLSelect
+          fill
+          value={method}
+          onChange={(event) => {
+            const picked = event.currentTarget.value;
+            const entry = PCA_METHODS.find((one) => one.value === picked);
+            if (entry !== undefined) write({ method: entry.value });
+          }}
+        >
+          {PCA_METHODS.map((entry) => (
+            <option key={entry.value} value={entry.value}>
+              {entry.label}
+            </option>
+          ))}
+        </HTMLSelect>
+      </label>
+      {method === 'NIPALS' ? (
+        <NumberField
+          label="Components to compute"
+          value={settings.nCompNIPALS}
+          placeholder="2"
+          integer
+          help="NIPALS stops once it has this many components."
+          onChange={(nCompNIPALS) => {
+            write({ nCompNIPALS });
+          }}
+        />
+      ) : null}
+      <Switch
+        checked={settings.center !== false}
+        label="Centre the columns (on unless turned off)"
+        style={SWITCH_STYLE}
+        onChange={(event) => {
+          write({ center: event.currentTarget.checked });
+        }}
+      />
+      <Switch
+        checked={settings.scale === true}
+        label="Scale the columns (off unless turned on)"
+        style={SWITCH_STYLE}
+        onChange={(event) => {
+          write({ scale: event.currentTarget.checked });
+        }}
+      />
+      <Switch
+        checked={settings.ignoreZeroVariance === true}
+        label="Ignore flat columns (only matters while scaling)"
+        style={SWITCH_STYLE}
+        onChange={(event) => {
+          write({ ignoreZeroVariance: event.currentTarget.checked });
+        }}
+      />
+    </div>
+  );
+}
+
+const ROOT_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+} as const satisfies CSSProperties;
+
+const ROW_STYLE = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'flex-end',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const OPTIONS_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+  paddingTop: 6,
+  borderTop: '1px solid var(--border, #d8dee6)',
+} as const satisfies CSSProperties;
+
+const FIELD_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 2,
+  minWidth: 160,
+  flex: '1 1 160px',
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  fontSize: 11,
+  fontWeight: 600,
+  color: 'var(--text-muted, #5b6875)',
+} as const satisfies CSSProperties;
+
+const SWITCH_STYLE = {
+  margin: 0,
+  fontSize: 12,
+} as const satisfies CSSProperties;
+
+const HELP_STYLE = {
+  fontSize: 11,
+  color: 'var(--text-faint, #8a96a3)',
+} as const satisfies CSSProperties;

package/src/spectra/ui/ProblemList.tsx

@@ -0,0 +1,77 @@
+import { Callout } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { SettingsProblem } from '../core/problems.ts';
+
+/** What {@link ProblemList} reports. */
+export interface ProblemListProps {
+  /** The problems of one part of the settings, errors and advice together. */
+  problems: readonly SettingsProblem[];
+  /**
+   * What the errors are headed with; the advice is always headed `Worth a look`.
+   * @default 'The processor would fail on this' — what an error always means
+   */
+  title?: string;
+}
+
+/**
+ * What is wrong, or probably wrong, with one part of the settings.
+ *
+ * Errors and advice are kept apart because they ask for different things: an
+ * error is a value the processor throws on and has to be fixed before anything
+ * runs, while a warning is a chain that runs and most likely does not mean what
+ * the reader thinks. Nothing here blocks — the editor reports, it does not gate.
+ * @param props - See {@link ProblemListProps}.
+ * @returns The two callouts, or nothing at all when there is nothing to say.
+ */
+export function ProblemList(props: ProblemListProps): ReactElement | null {
+  const { problems, title = 'The processor would fail on this' } = props;
+  const errors = problems.filter((entry) => entry.severity === 'error');
+  const warnings = problems.filter((entry) => entry.severity !== 'error');
+  if (errors.length === 0 && warnings.length === 0) return null;
+
+  return (
+    <div style={LIST_STYLE}>
+      {errors.length === 0 ? null : (
+        <Callout intent="danger" compact title={title}>
+          <Lines problems={errors} />
+        </Callout>
+      )}
+      {warnings.length === 0 ? null : (
+        <Callout intent="warning" compact title="Worth a look">
+          <Lines problems={warnings} />
+        </Callout>
+      )}
+    </div>
+  );
+}
+
+/**
+ * One line per problem, naming the part before saying what is wrong.
+ * @param props - What the lines are made of.
+ * @param props.problems - The problems to list.
+ * @returns The list.
+ */
+function Lines(props: { problems: readonly SettingsProblem[] }): ReactElement {
+  return (
+    <ul style={LINES_STYLE}>
+      {props.problems.map((entry) => (
+        <li key={`${entry.severity} ${entry.where} ${entry.message}`}>
+          {`${entry.where} — ${entry.message}`}
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+const LIST_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+} as const satisfies CSSProperties;
+
+const LINES_STYLE = {
+  margin: 0,
+  paddingLeft: 18,
+  fontSize: 12,
+} as const satisfies CSSProperties;

package/src/spectra/ui/RangeRows.tsx

@@ -0,0 +1,175 @@
+import { Button, InputGroup } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { useState } from 'react';
+
+import type { SpectraRange } from '../core/settings.ts';
+
+import { NumberField } from './NumberField.tsx';
+import { fitKeys, nextKey } from './rowKeys.ts';
+
+/** What {@link RangeRows} edits. */
+export interface RangeRowsProps {
+  /** The named stretches of x whose integral is reported per spectrum. */
+  value: readonly SpectraRange[];
+  /** Called with the new list on every edit. */
+  onChange: (ranges: SpectraRange[]) => void;
+}
+
+/**
+ * The stretches of x reported, and named, per spectrum.
+ *
+ * A range's name is not decoration: it becomes a variable the calculations
+ * read, so it is asked for on the same row as the bounds rather than treated as
+ * an afterthought. The integral and the tallest point are left out of the form
+ * entirely — the processor writes those back into the very same objects. The
+ * point numbers are drawn beside the bounds because the processor resolves the
+ * window with the same call the scaling uses, where a point number wins.
+ * @param props - See {@link RangeRowsProps}.
+ * @returns The list and the button that adds to it.
+ */
+export function RangeRows(props: RangeRowsProps): ReactElement {
+  const { value, onChange } = props;
+  const [rowKeys, setRowKeys] = useState<readonly number[]>(() =>
+    value.map((_, index) => index),
+  );
+
+  if (rowKeys.length !== value.length) {
+    setRowKeys(fitKeys(rowKeys, value.length));
+  }
+
+  function write(index: number, patch: SpectraRange): void {
+    onChange(
+      value.map((range, at) => (at === index ? { ...range, ...patch } : range)),
+    );
+  }
+
+  return (
+    <div style={LIST_STYLE}>
+      {value.length === 0 ? (
+        <span style={EMPTY_STYLE}>
+          None — nothing is integrated, and no calculation has anything to read.
+        </span>
+      ) : null}
+      {value.map((range, index) => (
+        <div key={rowKeys[index] ?? index} style={ROW_STYLE}>
+          <label style={NAME_FIELD_STYLE}>
+            <span style={LABEL_STYLE}>Name</span>
+            <InputGroup
+              size="small"
+              fill
+              aria-label={`Name of range ${String(index + 1)}`}
+              placeholder="a name a formula can read"
+              intent={(range.label ?? '') === '' ? 'danger' : 'none'}
+              spellCheck={false}
+              autoComplete="off"
+              value={range.label ?? ''}
+              onValueChange={(label) => {
+                write(index, { label });
+              }}
+            />
+          </label>
+          <NumberField
+            label="From"
+            value={range.from}
+            placeholder="the first x"
+            onChange={(from) => {
+              write(index, { from });
+            }}
+          />
+          <NumberField
+            label="To"
+            value={range.to}
+            placeholder="the last x"
+            onChange={(to) => {
+              write(index, { to });
+            }}
+          />
+          <NumberField
+            label="From point"
+            value={range.fromIndex}
+            integer
+            placeholder="0"
+            onChange={(fromIndex) => {
+              write(index, { fromIndex });
+            }}
+          />
+          <NumberField
+            label="To point"
+            value={range.toIndex}
+            integer
+            placeholder="the last point"
+            onChange={(toIndex) => {
+              write(index, { toIndex });
+            }}
+          />
+          <Button
+            icon="cross"
+            variant="minimal"
+            size="small"
+            aria-label={`Remove range ${String(index + 1)}`}
+            onClick={() => {
+              setRowKeys(rowKeys.filter((_, at) => at !== index));
+              onChange(value.filter((_, at) => at !== index));
+            }}
+          />
+        </div>
+      ))}
+      <div>
+        <Button
+          icon="plus"
+          size="small"
+          text="Add a range"
+          onClick={() => {
+            setRowKeys([...rowKeys, nextKey(rowKeys)]);
+            onChange([...value, { label: '' }]);
+          }}
+        />
+      </div>
+      <span style={HELP_STYLE}>
+        A range with no name is silently skipped, and the name has to be one a
+        variable could take — no spaces, and not starting with a digit.
+      </span>
+      <span style={HELP_STYLE}>
+        A range resolves its window the same way the scaling does: a point
+        number silently wins, so with From point set, From is never read.
+      </span>
+    </div>
+  );
+}
+
+const LIST_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+} as const satisfies CSSProperties;
+
+const ROW_STYLE = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'flex-end',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const NAME_FIELD_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 2,
+  minWidth: 140,
+  flex: '1 1 140px',
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  fontSize: 11,
+  fontWeight: 600,
+  color: 'var(--text-muted, #5b6875)',
+} as const satisfies CSSProperties;
+
+const EMPTY_STYLE = {
+  fontSize: 12,
+  color: 'var(--text-faint, #8a96a3)',
+} as const satisfies CSSProperties;
+
+const HELP_STYLE = {
+  fontSize: 11,
+  color: 'var(--text-faint, #8a96a3)',
+} as const satisfies CSSProperties;

package/src/spectra/ui/ScaleFields.tsx

@@ -0,0 +1,183 @@
+import { HTMLSelect, InputGroup, Switch } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { ScaleSettings } from '../core/settings.ts';
+
+import { NumberField } from './NumberField.tsx';
+import {
+  scaleMethodOptions,
+  withScaleMethod,
+  withScaleRange,
+  withScaleTarget,
+} from './scaleOptions.ts';
+
+/** What {@link ScaleFields} edits. */
+export interface ScaleFieldsProps {
+  /** How every spectrum is scaled onto the reference one. */
+  value: ScaleSettings;
+  /** Called with the edited scaling on every change. */
+  onChange: (scale: ScaleSettings) => void;
+  /**
+   * The ids the processor holds, so the reference is picked rather than typed.
+   * @default undefined — the reference is typed into a box instead
+   */
+  spectrumIds?: readonly string[];
+}
+
+/**
+ * What every spectrum is scaled against, and over which stretch of x.
+ *
+ * The reference is a spectrum rather than a number, because the point of this
+ * stage is to make one dataset comparable with itself: every spectrum is
+ * stretched until the chosen feature — its smallest value, its largest, its
+ * integral — matches the reference's over the same window. A method or a
+ * reference the processor cannot match is still drawn, because a menu that
+ * quietly falls back to its first entry would show settings nobody holds.
+ * @param props - See {@link ScaleFieldsProps}.
+ * @returns The method, the reference, the window and the relative switch.
+ */
+export function ScaleFields(props: ScaleFieldsProps): ReactElement {
+  const { value, onChange, spectrumIds } = props;
+  const range = value.range ?? {};
+
+  return (
+    <div style={FIELDS_STYLE}>
+      <label style={FIELD_STYLE}>
+        <span style={LABEL_STYLE}>Method</span>
+        <HTMLSelect
+          aria-label="Scaling method"
+          fill
+          value={value.method ?? ''}
+          options={scaleMethodOptions(value.method)}
+          onChange={(event) => {
+            onChange(withScaleMethod(value, event.currentTarget.value));
+          }}
+        />
+      </label>
+
+      <label style={FIELD_STYLE}>
+        <span style={LABEL_STYLE}>Reference spectrum</span>
+        {spectrumIds === undefined ? (
+          <InputGroup
+            size="small"
+            fill
+            aria-label="Reference spectrum"
+            placeholder="the first spectrum the processor holds"
+            spellCheck={false}
+            autoComplete="off"
+            value={value.targetID ?? ''}
+            onValueChange={(targetID) => {
+              onChange(withScaleTarget(value, targetID));
+            }}
+          />
+        ) : (
+          <HTMLSelect
+            aria-label="Reference spectrum"
+            fill
+            value={value.targetID ?? ''}
+            onChange={(event) => {
+              onChange(withScaleTarget(value, event.currentTarget.value));
+            }}
+          >
+            <option value="">The first spectrum the processor holds</option>
+            {spectrumIds.map((id) => (
+              <option key={id} value={id}>
+                {id}
+              </option>
+            ))}
+            {value.targetID === undefined ||
+            spectrumIds.includes(value.targetID) ? null : (
+              <option value={value.targetID}>
+                {`${value.targetID} — not a spectrum the processor holds`}
+              </option>
+            )}
+          </HTMLSelect>
+        )}
+      </label>
+
+      <div style={ROW_STYLE}>
+        <NumberField
+          label="From"
+          value={range.from}
+          placeholder="the first x"
+          onChange={(from) => {
+            onChange(withScaleRange(value, { from }));
+          }}
+        />
+        <NumberField
+          label="To"
+          value={range.to}
+          placeholder="the last x"
+          onChange={(to) => {
+            onChange(withScaleRange(value, { to }));
+          }}
+        />
+        <NumberField
+          label="From point"
+          value={range.fromIndex}
+          integer
+          placeholder="0"
+          onChange={(fromIndex) => {
+            onChange(withScaleRange(value, { fromIndex }));
+          }}
+        />
+        <NumberField
+          label="To point"
+          value={range.toIndex}
+          integer
+          placeholder="the last point"
+          onChange={(toIndex) => {
+            onChange(withScaleRange(value, { toIndex }));
+          }}
+        />
+      </div>
+      <span style={HELP_STYLE}>
+        A point number silently wins over an x value: with From point set, From
+        is never read.
+      </span>
+
+      <Switch
+        checked={value.relative === true}
+        label="Subtract the reference spectrum"
+        style={SWITCH_STYLE}
+        onChange={(event) => {
+          onChange({ ...value, relative: event.currentTarget.checked });
+        }}
+      />
+    </div>
+  );
+}
+
+const FIELDS_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const FIELD_STYLE = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 2,
+} as const satisfies CSSProperties;
+
+const ROW_STYLE = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  gap: 8,
+} as const satisfies CSSProperties;
+
+const LABEL_STYLE = {
+  fontSize: 11,
+  fontWeight: 600,
+  color: 'var(--text-muted, #5b6875)',
+} as const satisfies CSSProperties;
+
+const HELP_STYLE = {
+  fontSize: 11,
+  color: 'var(--text-faint, #8a96a3)',
+} as const satisfies CSSProperties;
+
+const SWITCH_STYLE = {
+  margin: 0,
+  fontSize: 12,
+} as const satisfies CSSProperties;