react-cheminfo 0.9.0 → 0.10.0

package/src/projection/core/loadingProfiles.ts

@@ -0,0 +1,226 @@
+import type { ChartExtent } from '../../chart/core/chartExtent.ts';
+import { chartPadExtent } from '../../chart/core/chartExtent.ts';
+import { chartSeriesColor } from '../../chart/core/chartPalette.ts';
+import type { MatrixLike } from '../../chart/core/matrix.ts';
+
+import type { ProjectionVariablesView } from './projectionOptions.ts';
+import type { ProjectionAxis, ProjectionLoadings } from './projectionResult.ts';
+import type { VariableAxis } from './variableAxis.ts';
+import { variableCount } from './variableAxis.ts';
+import { drawableVariablesView } from './variablesView.ts';
+
+/** One component's line or bars, everything a panel draws. */
+export interface LoadingProfile {
+  /** Which component, from 0. */
+  index: number;
+  /** What the panel is titled, e.g. `PC 2`. */
+  label: string;
+  /** The colour this component carries on every tab. */
+  color: string;
+  /**
+   * Its share of the differences, between 0 and 1, written after the title.
+   * @default undefined — nothing is written after the title
+   */
+  share?: number;
+  /** The values the panel draws, one per measurement, in the panel's own order. */
+  values: readonly number[];
+  /**
+   * The second line a panel draws, for a view that has two.
+   * @default undefined — the panel draws one line
+   */
+  secondValues?: readonly number[];
+}
+
+/** What the "what differs" tab draws, all of it. */
+export interface LoadingProfiles {
+  /** How the measurements are laid out, which decides a line or bars. */
+  axis: VariableAxis;
+  /** Which measurement each drawn slot is, so a tracking event can name it. */
+  order: Int32Array;
+  /**
+   * The average sample, in the measurements' own units and the drawn order —
+   * the faint reference line.
+   * @default undefined — no reference line is drawn
+   */
+  mean?: readonly number[];
+  /** One panel per component. */
+  profiles: readonly LoadingProfile[];
+  /** What the values measure, for the vertical axis. */
+  valueLabel: string;
+  /** Whether every panel shares one vertical scale. */
+  sharedScale: boolean;
+  /** The scale they share, when they do. */
+  domain: ChartExtent;
+  /** Which view produced them, for the legend sentence. */
+  view: ProjectionVariablesView;
+}
+
+/** How {@link loadingProfiles} builds its panels. */
+export interface LoadingProfilesOptions {
+  /** What loads onto each axis. */
+  loadings: ProjectionLoadings;
+  /** The axes, for the panel titles and their shares. */
+  axes: readonly ProjectionAxis[];
+  /** Which view to draw. */
+  view: ProjectionVariablesView;
+  /** How many components to draw. */
+  count: number;
+  /** How far along a component the average sample is pushed, in standard deviations. */
+  spread: number;
+  /** Whether every panel shares one vertical scale. */
+  sharedScale: boolean;
+  /** The order the measurements are drawn in. */
+  order: 'original' | 'strongest';
+  /**
+   * The one selected sample's scores, for the `sample` view.
+   * @default undefined — the `sample` view falls back to `weights`
+   */
+  sampleScores?: readonly number[];
+  /**
+   * What that sample is called, for the legend sentence.
+   * @default ''
+   */
+  sampleLabel?: string;
+}
+
+/**
+ * The panels of the "what differs" tab.
+ *
+ * A view whose data is not there falls back to `weights` rather than throwing
+ * or drawing nothing: `effect` needs the average and the spread, `rescaled`
+ * needs the scaling the model applied, and `sample` needs exactly one selected
+ * sample.
+ * @param options - See {@link LoadingProfilesOptions}.
+ * @returns Everything the tab draws.
+ */
+export function loadingProfiles(
+  options: LoadingProfilesOptions,
+): LoadingProfiles {
+  const {
+    loadings,
+    axes,
+    count,
+    spread,
+    sharedScale,
+    order,
+    view: wanted,
+    sampleScores,
+  } = options;
+  const {
+    weights,
+    variables,
+    mean,
+    scales,
+    spread: axisSpread,
+    valueLabel = '',
+  } = loadings;
+  const width = variableCount(variables);
+  const panels = Number.isFinite(count) ? Math.floor(count) : axes.length;
+  const drawn = Math.max(0, Math.min(panels, weights.rows, axes.length));
+  // An empty selection rather than an unknown one: the panels always know
+  // what is selected, and nothing selected is nothing to rebuild.
+  const view = drawableVariablesView(wanted, loadings, sampleScores ?? []);
+  // A number line cannot be reordered: a peak stands at its own position, so
+  // sorting the slots by strength would move every stick to a mass it was not
+  // measured at. The choice is only meaningful where the slots are a list.
+  const sortable = variables.kind === 'named' ? order : 'original';
+  const slots = slotOrder(sortable, weights, width, drawn);
+
+  // A panel in the measurements' own units starts from the average sample and
+  // walks away from it; one drawing weights starts from nothing at all.
+  const inUnits = view === 'effect' || view === 'sample';
+  const running = view === 'sample' ? new Float64Array(width) : null;
+  const profiles: LoadingProfile[] = [];
+  let low = Number.POSITIVE_INFINITY;
+  let high = Number.NEGATIVE_INFINITY;
+
+  for (let index = 0; index < drawn; index++) {
+    const values = new Array<number>(width);
+    const second = view === 'effect' ? new Array<number>(width) : null;
+    const reach = spread * (axisSpread?.[index] ?? 0);
+    const score = sampleScores?.[index] ?? 0;
+    for (let slot = 0; slot < width; slot++) {
+      const measurement = slots[slot] ?? slot;
+      const weight = weights.get(index, measurement);
+      const scale = scales?.[measurement] ?? 1;
+      const base = mean?.[measurement] ?? 0;
+      let value = weight;
+      if (view === 'rescaled') {
+        value = weight * scale;
+      } else if (second !== null) {
+        const step = reach * weight * scale;
+        value = base + step;
+        second[slot] = base - step;
+        if (base - step < low) low = base - step;
+        if (base - step > high) high = base - step;
+      } else if (running !== null) {
+        const total = (running[slot] ?? 0) + score * weight * scale;
+        running[slot] = total;
+        value = base + total;
+      }
+      values[slot] = value;
+      if (value < low) low = value;
+      if (value > high) high = value;
+    }
+    const axis = axes[index];
+    profiles.push({
+      index,
+      label: axis?.name ?? `Component ${index + 1}`,
+      color: chartSeriesColor(index, 'component'),
+      share: axis?.share,
+      values,
+      secondValues: second ?? undefined,
+    });
+  }
+
+  let reference: number[] | undefined;
+  if (inUnits && mean !== undefined) {
+    reference = new Array<number>(width);
+    for (let slot = 0; slot < width; slot++) {
+      const value = mean[slots[slot] ?? slot] ?? 0;
+      reference[slot] = value;
+      if (value < low) low = value;
+      if (value > high) high = value;
+    }
+  }
+
+  const padded = chartPadExtent({ min: low, max: high });
+  return {
+    axis: variables,
+    order: slots,
+    mean: reference,
+    profiles,
+    // Weights are a share of a direction, not a quantity anybody measured.
+    valueLabel: view === 'weights' ? 'Weight' : valueLabel,
+    sharedScale,
+    // Bars are read from the zero line, so the line has to be on the panel; a
+    // spectrum sitting on a baseline would be squashed into its top third by
+    // the same rule, so it is only applied where a value means a weight.
+    domain: inUnits
+      ? padded
+      : { min: Math.min(padded.min, 0), max: Math.max(padded.max, 0) },
+    view,
+  };
+}
+
+function slotOrder(
+  order: 'original' | 'strongest',
+  weights: MatrixLike,
+  width: number,
+  drawn: number,
+): Int32Array {
+  const slots = new Int32Array(width);
+  for (let index = 0; index < width; index++) slots[index] = index;
+  if (order === 'original' || drawn === 0) return slots;
+
+  // Every panel takes the order the strongest component puts the measurements
+  // in. Sorting each panel to its own component would move a measurement from
+  // slot to slot down the stack, and the stack is read down a column.
+  const strength = new Float64Array(width);
+  for (let index = 0; index < width; index++) {
+    strength[index] = Math.abs(weights.get(0, index));
+  }
+  return slots.toSorted(
+    (left, right) => (strength[right] ?? 0) - (strength[left] ?? 0),
+  );
+}

package/src/projection/core/pcaLike.ts

@@ -0,0 +1,33 @@
+import type { MatrixLike } from '../../chart/core/matrix.ts';
+
+/**
+ * A fitted principal component analysis, described structurally so that
+ * nothing in this package imports `ml-pca`.
+ *
+ * `ml-pca`'s `PCA` satisfies it as it stands, with no adapter and no cast.
+ * `getEigenvectors`, `getStandardDeviations`, `invert` and `toJSON` are
+ * deliberately absent: nothing here needs them, and `getEigenvectors` hands
+ * out the model's live internal matrix, which a component library must never
+ * be given.
+ */
+export interface PcaLike {
+  /**
+   * Place samples in the model's space.
+   * @param samples - One array per sample, one value per original measurement.
+   * @param options - `nComponents` keeps only the first few columns.
+   * @param options.nComponents - How many of them to keep.
+   * @returns One row per sample, one column per kept component.
+   */
+  predict: (
+    samples: number[][],
+    options?: { nComponents?: number },
+  ) => MatrixLike;
+  /** The share of the variance each component carries, as fractions summing to 1 — never percentages. */
+  getExplainedVariance: () => number[];
+  /** The running total of the above; the last value is 1 to within float error, so never compare it to 1. */
+  getCumulativeVariance: () => number[];
+  /** The variance of each component's own scores. */
+  getEigenvalues: () => number[];
+  /** Row `i` is component `i`, column `j` is original measurement `j`. */
+  getLoadings: () => MatrixLike;
+}

package/src/projection/core/pcaResult.ts

@@ -0,0 +1,238 @@
+import type { MatrixLike } from '../../chart/core/matrix.ts';
+import { mappedMatrix, stackedMatrix } from '../../chart/core/matrix.ts';
+
+import type { PcaLike } from './pcaLike.ts';
+import type { ProjectionAxis, ProjectionResult } from './projectionResult.ts';
+import type { VariableAxis } from './variableAxis.ts';
+
+/** How a {@link ProjectionResult} is built from a fitted model. */
+export interface PcaResultOptions {
+  /**
+   * The measurements the model was fitted on, one array per sample. They are
+   * read in place: the average and the spread of each measurement are
+   * accumulated in one centred pass and nothing is copied.
+   */
+  rows: readonly number[][];
+  /**
+   * Further samples to place into the finished model, one array per sample,
+   * each as wide as a row of `rows`.
+   *
+   * These took no part in fitting: the axes were already chosen when they
+   * arrived. They are appended after the fitted samples and drawn hollow, so a
+   * reader can see at a glance which points the model has already accounted
+   * for and which it is being asked about — a new batch, a suspected outlier,
+   * next year's measurements against last year's model.
+   *
+   * They are placed by one further `predict` call, and the two sets of scores
+   * are read as one table without either being copied.
+   * @default undefined — every sample built the model
+   */
+  projected?: readonly number[][];
+  /**
+   * How the original measurements are laid out.
+   * @default the columns numbered `1` to `n`, drawn as bars
+   */
+  variables?: VariableAxis;
+  /**
+   * Where the samples landed. Left out, they are placed by projecting `rows`
+   * through the model, which is one call.
+   * @default the model's own projection of `rows`
+   */
+  scores?: MatrixLike;
+  /**
+   * Whether the model divided each measurement by its spread — the `scale`
+   * given to `new PCA(...)`. It cannot be read back from the model's public
+   * surface, and getting it wrong offers a view that is the same drawing
+   * twice.
+   * @default false
+   */
+  scaled?: boolean;
+  /**
+   * How many components to keep.
+   * @default every component the model holds
+   */
+  count?: number;
+  /**
+   * What the measured values are, e.g. `Absorbance`.
+   * @default ''
+   */
+  valueLabel?: string;
+  /**
+   * Whether each component is flipped so that its strongest measurement comes
+   * out positive. The direction of a component is arbitrary and flips when the
+   * model is refitted — on iris, refitting on fifty of the hundred and fifty
+   * flowers turned the first component's weights right around — so without
+   * this a map mirrors itself when one sample is added, which reads as a fault
+   * to everyone who is not a statistician. The scores are flipped with the
+   * weights, through a mapped view rather than a copy.
+   * @default 'largest-positive'
+   */
+  signConvention?: 'largest-positive' | 'none';
+  /**
+   * What the method is called in the headings.
+   * @default 'Principal components'
+   */
+  method?: string;
+}
+
+/**
+ * A fitted principal component model as the viewer reads it.
+ * @param pca - The fitted model.
+ * @param options - See {@link PcaResultOptions}.
+ * @returns The result, with every tab's data filled in.
+ * @throws {Error} When `rows` is empty, when a row's length differs from the
+ * first row's, when a measurement is not a finite number, or when the model's
+ * loadings are not as wide as a row — which is what happens when the model was
+ * fitted with `ignoreZeroVariance` and silently dropped a column, and which
+ * would otherwise label every loadings panel one measurement out.
+ */
+export function pcaResult(
+  pca: PcaLike,
+  options: PcaResultOptions,
+): ProjectionResult {
+  const {
+    rows,
+    projected,
+    variables,
+    scores,
+    scaled = false,
+    count,
+    valueLabel = '',
+    signConvention = 'largest-positive',
+    method = 'Principal components',
+  } = options;
+
+  const first = rows[0];
+  if (first === undefined) {
+    throw new Error('pcaResult was given no rows, so nothing can be read.');
+  }
+  const width = first.length;
+  const { mean, deviation } = columnStats(rows, width);
+
+  const weights = pca.getLoadings();
+  if (weights.columns < width) {
+    throw new Error(
+      `pcaResult was given rows ${width} measurements wide but a model holding ${weights.columns} weights, which is what \`ignoreZeroVariance\` leaves behind when it drops a column that never moves. Every panel after the dropped one would carry its neighbour's name.`,
+    );
+  }
+
+  const wanted = Number.isFinite(count) ? Math.floor(count ?? 0) : weights.rows;
+  const kept = Math.min(weights.rows, Math.max(1, wanted));
+  const signs = signsOf(weights, signConvention === 'largest-positive');
+  const explained = pca.getExplainedVariance();
+  const eigenvalues = pca.getEigenvalues();
+
+  const axes: ProjectionAxis[] = [];
+  const spread: number[] = [];
+  for (let index = 0; index < kept; index++) {
+    const eigenvalue = eigenvalues[index];
+    axes.push({ name: `PC${index + 1}`, share: explained[index], eigenvalue });
+    spread.push(Math.sqrt(Math.max(0, eigenvalue ?? 0)));
+  }
+
+  const fitted =
+    scores ?? pca.predict(rows as number[][], { nComponents: kept });
+  const extra =
+    projected === undefined || projected.length === 0
+      ? undefined
+      : pca.predict(projected as number[][], { nComponents: kept });
+  const placed = extra === undefined ? fitted : stackedMatrix(fitted, extra);
+  return {
+    method,
+    axes,
+    scores: signedView(placed, placed.rows, kept, signs, false),
+    fittedCount: extra === undefined ? undefined : fitted.rows,
+    loadings: {
+      weights: signedView(weights, kept, width, signs, true),
+      variables: variables ?? numberedVariables(width),
+      mean,
+      spread,
+      scales: scaled ? deviation : undefined,
+      valueLabel,
+    },
+  };
+}
+
+function columnStats(
+  rows: readonly number[][],
+  width: number,
+): { mean: number[]; deviation: number[] } {
+  // Centred on the average so far, in one pass: a running total of the raw
+  // values squared loses the low bits of a spectrum sitting on a baseline.
+  // `deviation` carries the squared spread until the last loop roots it.
+  const mean = new Array<number>(width).fill(0);
+  const deviation = new Array<number>(width).fill(0);
+  for (let index = 0; index < rows.length; index++) {
+    const row = rows[index];
+    if (row?.length !== width) {
+      throw new Error(
+        `pcaResult was given a row ${row?.length ?? 0} measurements wide at index ${index}, where the first row is ${width} wide.`,
+      );
+    }
+    const seen = index + 1;
+    for (let column = 0; column < width; column++) {
+      const value = row[column];
+      if (value === undefined || !Number.isFinite(value)) {
+        throw new Error(
+          `pcaResult was given ${String(value)} at row ${index}, measurement ${column}. A model carries it on into a map of nothing at all.`,
+        );
+      }
+      const before = mean[column] ?? 0;
+      const step = value - before;
+      const after = before + step / seen;
+      mean[column] = after;
+      deviation[column] = (deviation[column] ?? 0) + step * (value - after);
+    }
+  }
+
+  const divisor = Math.max(1, rows.length - 1);
+  for (let column = 0; column < width; column++) {
+    deviation[column] = Math.sqrt((deviation[column] ?? 0) / divisor);
+  }
+  return { mean, deviation };
+}
+
+function signsOf(weights: MatrixLike, flip: boolean): Float64Array {
+  const signs = new Float64Array(weights.rows).fill(1);
+  if (!flip) return signs;
+  for (let row = 0; row < weights.rows; row++) {
+    let strongest = 0;
+    let reach = 0;
+    for (let column = 0; column < weights.columns; column++) {
+      const value = weights.get(row, column);
+      const size = Math.abs(value);
+      if (size > reach) {
+        reach = size;
+        strongest = value;
+      }
+    }
+    if (strongest < 0) signs[row] = -1;
+  }
+  return signs;
+}
+
+function signedView(
+  source: MatrixLike,
+  rowCount: number,
+  columnCount: number,
+  signs: Float64Array,
+  byRow: boolean,
+): MatrixLike {
+  return mappedMatrix(
+    {
+      rows: rowCount,
+      columns: columnCount,
+      get: (row: number, column: number) =>
+        row >= 0 && row < rowCount && column >= 0 && column < columnCount
+          ? source.get(row, column)
+          : Number.NaN,
+    },
+    (value, row, column) => value * (signs[byRow ? row : column] ?? 1),
+  );
+}
+
+function numberedVariables(width: number): VariableAxis {
+  const names = new Array<string>(width);
+  for (let index = 0; index < width; index++) names[index] = String(index + 1);
+  return { kind: 'named', names };
+}