react-cheminfo 0.9.0 → 0.10.0

package/src/projection/core/projectionCopy.ts

@@ -0,0 +1,252 @@
+import type { ProjectionCopyPatch } from './projectionCopyPatch.ts';
+import type { ProjectionOptionId } from './projectionOptions.ts';
+import type {
+  ProjectionBarWords,
+  ProjectionHelp,
+} from './projectionStrings.ts';
+import {
+  PROJECTION_BAR_WORDS,
+  PROJECTION_HELP,
+  PROJECTION_SHORT_TAB,
+} from './projectionStrings.ts';
+import type { ProjectionTab } from './projectionTabs.ts';
+
+export type {
+  ProjectionBarWords,
+  ProjectionHelp,
+  ProjectionHelpExample,
+} from './projectionStrings.ts';
+
+/** Every word a projection viewer writes. */
+export interface ProjectionCopy {
+  /** What each tab is called. */
+  tab: Record<ProjectionTab, string>;
+  /** What each tab is called on a bar with no room for the long name. */
+  shortTab: Record<ProjectionTab, string>;
+  /** The words the settings bar writes on itself. */
+  bar: ProjectionBarWords;
+  /** The sentence under each tab and above its figure. */
+  intro: {
+    /** The map. */
+    map: string;
+    /** The pair grid. */
+    pairs: string;
+    /**
+     * The "what differs" tab showing weights over a number line. Carries
+     * `{axis}`.
+     */
+    variablesContinuous: string;
+    /** The same, over named measurements, which are drawn as bars. */
+    variablesNamed: string;
+    /** The same tab in its "effect on a sample" view, whatever the axis is. */
+    variablesEffect: string;
+    /** The same tab in its "selected sample" view. */
+    variablesSample: string;
+    /** The shares tab. */
+    shares: string;
+  };
+  /** The sentence naming what colour and shape mean, one per tab and per view. */
+  legend: {
+    /** The map. Carries `{groups}` and `{coverage}`. */
+    map: string;
+    /** The map with no outlines. Carries `{groups}`. */
+    mapNoEllipse: string;
+    /** The pair grid. Carries `{groups}`. */
+    pairs: string;
+    /** The "effect on a sample" view. */
+    variablesEffect: string;
+    /** The "weights" view. */
+    variablesWeights: string;
+    /** The "weights in your units" view. */
+    variablesRescaled: string;
+    /** The "selected sample" view. Carries `{sample}`. */
+    variablesSample: string;
+    /** The shares tab. */
+    shares: string;
+  };
+  /** The sentences the viewer builds from the data. */
+  sentence: {
+    /** Carries `{percent}`. */
+    sharesFirst: string;
+    /** Carries `{count}` and `{percent}`. */
+    sharesTarget: string;
+    /** Carries `{count}` and `{percent}`. */
+    sharesNoTarget: string;
+    /** Carries `{count}` and `{total}`. */
+    selection: string;
+    /** What is said when nothing is selected. */
+    selectionNone: string;
+    /** What is said while a plain drag is under way. */
+    lassoReplace: string;
+    /** While a shift-drag is under way. */
+    lassoAdd: string;
+    /** While an alt-drag is under way. */
+    lassoRemove: string;
+    /** Carries `{names}`. */
+    skippedGroups: string;
+  };
+  /** What the buttons read. */
+  action: {
+    /** Frames the selected samples. */
+    zoomToSelection: string;
+    /** Puts the axes back. */
+    resetView: string;
+    /** Empties the selection. */
+    clearSelection: string;
+    /** Takes the figure off the page as a file. */
+    download: string;
+    /** What the floating bar is called. */
+    options: string;
+  };
+  /** The help behind every option's glyph. */
+  help: Record<ProjectionOptionId, ProjectionHelp>;
+  /** The nouns the viewer builds its sentences from. */
+  words: {
+    /** What one row is called. */
+    sample: string;
+    /** What many rows are called. */
+    samples: string;
+    /** What one axis is called. */
+    component: string;
+    /** What many are called. */
+    components: string;
+  };
+}
+
+/**
+ * The words the viewer writes when a site overrides nothing.
+ *
+ * Two words are kept out of it deliberately. Nothing is ever "reconstructed",
+ * because the reader is being shown their own samples and the word suggests a
+ * repair. Nothing is ever a "variance" either: the quantity every component
+ * carries a share of is written as the differences between your samples, which
+ * is what it is, and the one place a spread has to be named it is named in
+ * standard deviations.
+ */
+export const PROJECTION_COPY: ProjectionCopy = {
+  tab: {
+    map: 'Map',
+    pairs: 'Every pair',
+    variables: 'What differs',
+    shares: 'How much each explains',
+  },
+  shortTab: PROJECTION_SHORT_TAB,
+  bar: PROJECTION_BAR_WORDS,
+  intro: {
+    map: 'Each dot is one sample. Dots that sit together are alike; dots far apart are the ones that differ most. The two axes are the strongest patterns of difference, called components.',
+    pairs:
+      'The same map drawn for every pair of components. A grouping the first two miss often shows up in another pair.',
+    variablesContinuous:
+      'Each panel is one pattern of difference, drawn back over your {axis}: what pushes a sample to one end of the map.',
+    variablesNamed:
+      'Each panel is one pattern of difference, one bar per measurement: the measurements that push a sample to one end of the map.',
+    variablesEffect:
+      'Each panel is one pattern of difference, drawn as your average sample pushed to each end of it: what a sample at each end of the map actually looks like.',
+    variablesSample:
+      'Each panel adds one more component to your average sample, rebuilding the selected sample a step at a time.',
+    shares:
+      'Every component accounts for a share of the differences between your samples, largest first. The first few usually account for most of them.',
+  },
+  legend: {
+    map: 'Colour = {groups}. Each outline covers about {coverage} of that group, assuming the group is roughly bell-shaped.',
+    mapNoEllipse: 'Colour = {groups}.',
+    pairs:
+      'Colour = {groups}. The strip along the diagonal shows how the samples spread out along that component on its own.',
+    variablesEffect:
+      'Grey is the average sample; the coloured lines are that sample pushed to each end of this component.',
+    variablesWeights:
+      'Above and below the zero line are the two opposite ends of this component; which end is which is arbitrary.',
+    variablesRescaled:
+      'The same weights undone through the scaling, so tall peaks read as tall again. Which end is which is still arbitrary.',
+    variablesSample:
+      'Grey is the average sample; the coloured line is {sample} rebuilt from the components shown.',
+    shares:
+      'Each bar carries the colour its component has on the other tabs; the grey line is the running total.',
+  },
+  sentence: {
+    sharesFirst:
+      'Component 1 accounts for {percent} of the differences between your samples.',
+    sharesTarget:
+      'The first {count} components together account for {percent} — the rest is mostly small, scattered differences.',
+    sharesNoTarget:
+      'Even all {count} components only account for {percent}, so your samples differ in many small ways at once.',
+    selection: '{count} of {total} samples selected.',
+    selectionNone: 'Nothing selected — drag a loop around some dots.',
+    lassoReplace: 'Selecting',
+    lassoAdd: 'Adding to selection',
+    lassoRemove: 'Removing from selection',
+    skippedGroups: '{names} not outlined: too few samples.',
+  },
+  action: {
+    zoomToSelection: 'Zoom to selection',
+    resetView: 'Reset view',
+    clearSelection: 'Clear selection',
+    download: 'Save this figure',
+    options: 'Options',
+  },
+  help: PROJECTION_HELP,
+  words: {
+    sample: 'sample',
+    samples: 'samples',
+    component: 'component',
+    components: 'components',
+  },
+};
+
+/**
+ * The words the viewer will write, with a site's overrides merged in one key
+ * at a time, so a site fixing a single sentence keeps every other default.
+ * @param overrides - What the site wants said differently.
+ * @returns Every word, complete.
+ */
+export function mergeProjectionCopy(
+  overrides?: ProjectionCopyPatch<ProjectionCopy>,
+): ProjectionCopy {
+  if (overrides === undefined) return { ...PROJECTION_COPY };
+  return mergeBranch(
+    PROJECTION_COPY as unknown as Branch,
+    overrides,
+  ) as unknown as ProjectionCopy;
+}
+
+/**
+ * A sentence with its placeholders filled in.
+ *
+ * The placeholders are `{name}`, and one with no value is left in place rather
+ * than replaced by an empty string, so a site that mistypes a key sees the
+ * mistake in the figure instead of a sentence that quietly loses a number.
+ * @param template - The sentence, from {@link ProjectionCopy}.
+ * @param values - What each placeholder stands for.
+ * @returns The filled sentence.
+ */
+export function fillCopy(
+  template: string,
+  values: Readonly<Record<string, string>>,
+): string {
+  return template.replaceAll(PLACEHOLDER, (match: string, name: string) => {
+    const value = values[name];
+    return value === undefined ? match : value;
+  });
+}
+
+const PLACEHOLDER = /\{(?<name>[^{}]+)\}/gu;
+
+type Branch = Record<string, unknown>;
+
+function mergeBranch(base: Branch, overrides: Branch): Branch {
+  const merged: Branch = { ...base };
+  for (const key of Object.keys(overrides)) {
+    const value = overrides[key];
+    if (value === undefined) continue;
+    const current = merged[key];
+    merged[key] =
+      isBranch(current) && isBranch(value)
+        ? mergeBranch(current, value)
+        : value;
+  }
+  return merged;
+}
+
+function isBranch(value: unknown): value is Branch {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/projection/core/projectionCopyPatch.ts

@@ -0,0 +1,12 @@
+/**
+ * Every property of an object made optional, all the way down.
+ *
+ * It exists for one thing: a site overriding a single sentence of a viewer's
+ * copy should not have to restate the other sixty. The name carries its
+ * domain because every export of this package shares one flat namespace, and
+ * a bare `DeepPartial` there is a collision waiting for the next domain that
+ * wants one.
+ */
+export type ProjectionCopyPatch<T> = {
+  [K in keyof T]?: T[K] extends object ? ProjectionCopyPatch<T[K]> : T[K];
+};

package/src/projection/core/projectionOptions.ts

@@ -0,0 +1,238 @@
+import type { EllipseSize } from '../../scatter/core/confidenceEllipse.ts';
+import type { ScatterSelectionMode } from '../../scatter/core/scatterSelection.ts';
+
+import type { ProjectionResult } from './projectionResult.ts';
+import { drawableVariablesView } from './variablesView.ts';
+
+/** What the "what differs" panels draw. */
+export type ProjectionVariablesView =
+  /** The average sample pushed to each end of the component, in the data's own units. */
+  | 'effect'
+  /** The weight the component gives each measurement, above or below zero. */
+  | 'weights'
+  /** The same weights undone through the scaling, so tall peaks read as tall again. */
+  | 'rescaled'
+  /** The one selected sample, rebuilt from the components shown. */
+  | 'sample';
+
+/**
+ * What decides a dot's colour on the map: `'group'`, `'none'`, or nothing else
+ * in this release.
+ */
+export type ProjectionColorBy = 'group' | 'none';
+
+/** What the figure is currently showing. Every field is a control in the floating bar. */
+export interface ProjectionOptions {
+  /**
+   * Which axis is drawn horizontally, from 0.
+   * @default 0
+   */
+  xAxis: number;
+  /**
+   * Which axis is drawn vertically.
+   * @default 1
+   */
+  yAxis: number;
+  /**
+   * What decides a dot's colour.
+   * @default 'group'
+   */
+  colorBy: ProjectionColorBy;
+  /**
+   * How large the group outlines are, or `null` for none.
+   * @default { kind: 'coverage', probability: 0.95 }
+   */
+  ellipse: EllipseSize | null;
+  /**
+   * Radius of a dot on the map, in pixels.
+   * @default 3.5
+   */
+  pointRadius: number;
+  /**
+   * Whether each group's average is marked with a cross.
+   * @default false
+   */
+  showGroupMeans: boolean;
+  /**
+   * Whether each group's name is written once, over the middle of that group.
+   * @default false
+   */
+  showGroupLabels: boolean;
+  /**
+   * Whether every sample's own name is written beside its dot.
+   * @default false
+   */
+  showIds: boolean;
+  /**
+   * How many axes the pair grid lays out.
+   * @default 4
+   */
+  pairCount: number;
+  /**
+   * What the "what differs" panels draw.
+   * @default 'effect'
+   */
+  variablesView: ProjectionVariablesView;
+  /**
+   * How many components those panels show. The later ones usually carry noise.
+   * @default 3
+   */
+  variablesCount: number;
+  /**
+   * Whether every panel is drawn on one vertical scale, so a weak component
+   * looks weak. Fitting each panel to itself makes a component carrying two
+   * per cent of the differences look as important as one carrying fifty.
+   * @default true
+   */
+  sharedScale: boolean;
+  /**
+   * Whether the average sample is drawn faintly behind each panel. Without it
+   * the reader cannot tell which peak a wiggle belongs to.
+   * @default true
+   */
+  showAverage: boolean;
+  /**
+   * How far along a component the average sample is pushed, in standard
+   * deviations of that component's scores.
+   * @default 2
+   */
+  spread: number;
+  /**
+   * Order of the bars when the measurements are named. `original` keeps a
+   * measurement in the same slot in every panel, so the panels can be read
+   * down a column.
+   * @default 'original'
+   */
+  variableOrder: 'original' | 'strongest';
+  /**
+   * The cumulative share the marker on the shares tab aims at; `0` draws none.
+   * @default 0.95
+   */
+  shareTarget: number;
+  /**
+   * What a drag does to the selection when no modifier is held.
+   * @default 'replace'
+   */
+  selectMode: ScatterSelectionMode;
+}
+
+/** Every option, by name, so the help cannot drift from the controls. */
+export type ProjectionOptionId = keyof ProjectionOptions;
+
+/** What the figure shows when a site overrides nothing. */
+export const DEFAULT_PROJECTION_OPTIONS: ProjectionOptions = {
+  xAxis: 0,
+  yAxis: 1,
+  colorBy: 'group',
+  ellipse: { kind: 'coverage', probability: 0.95 },
+  pointRadius: 3.5,
+  showGroupMeans: false,
+  showGroupLabels: false,
+  showIds: false,
+  pairCount: 4,
+  variablesView: 'effect',
+  variablesCount: 3,
+  sharedScale: true,
+  showAverage: true,
+  spread: 2,
+  variableOrder: 'original',
+  shareTarget: 0.95,
+  selectMode: 'replace',
+};
+
+const SMALLEST_PAIR_GRID = 2;
+const SMALLEST_PANEL_COUNT = 1;
+
+/**
+ * The options the viewer will use, with a caller's overrides merged in and
+ * every one of them made safe against the result that actually came back.
+ *
+ * A saved option outlives the data it was made on: reload with fewer samples
+ * and axis eight no longer exists. Rather than let a plot ask for a column
+ * that is not there, the two axes are pulled back inside what was computed and
+ * kept apart, the counts are held inside what exists, and a view whose data is
+ * missing falls back to `weights`.
+ * @param overrides - What the caller asked for.
+ * @param result - The reduced space the options will be applied to.
+ * @returns Every option, complete and safe.
+ */
+export function resolveProjectionOptions(
+  overrides: Partial<ProjectionOptions> | undefined,
+  result: ProjectionResult,
+): ProjectionOptions {
+  const axisCount = result.axes.length;
+  const lastAxis = Math.max(0, axisCount - 1);
+  const xAxis = clampIndex(pick(overrides, 'xAxis'), lastAxis);
+
+  return {
+    xAxis,
+    yAxis: apart(
+      clampIndex(pick(overrides, 'yAxis'), lastAxis),
+      xAxis,
+      lastAxis,
+    ),
+    colorBy: pick(overrides, 'colorBy'),
+    ellipse: pick(overrides, 'ellipse'),
+    pointRadius: atLeast(pick(overrides, 'pointRadius'), 3.5, 0),
+    showGroupMeans: pick(overrides, 'showGroupMeans'),
+    showGroupLabels: pick(overrides, 'showGroupLabels'),
+    showIds: pick(overrides, 'showIds'),
+    pairCount: clampCount(
+      pick(overrides, 'pairCount'),
+      DEFAULT_PROJECTION_OPTIONS.pairCount,
+      SMALLEST_PAIR_GRID,
+      Math.max(SMALLEST_PAIR_GRID, axisCount),
+    ),
+    variablesView: drawableVariablesView(
+      pick(overrides, 'variablesView'),
+      result.loadings,
+    ),
+    variablesCount: clampCount(
+      pick(overrides, 'variablesCount'),
+      DEFAULT_PROJECTION_OPTIONS.variablesCount,
+      SMALLEST_PANEL_COUNT,
+      Math.max(SMALLEST_PANEL_COUNT, axisCount),
+    ),
+    sharedScale: pick(overrides, 'sharedScale'),
+    showAverage: pick(overrides, 'showAverage'),
+    spread: atLeast(pick(overrides, 'spread'), 2, 0),
+    variableOrder: pick(overrides, 'variableOrder'),
+    shareTarget: Math.min(1, atLeast(pick(overrides, 'shareTarget'), 0.95, 0)),
+    selectMode: pick(overrides, 'selectMode'),
+  };
+}
+
+function pick<Key extends ProjectionOptionId>(
+  overrides: Partial<ProjectionOptions> | undefined,
+  key: Key,
+): ProjectionOptions[Key] {
+  // Only an absent override defers to the default: `ellipse: null` is a
+  // reader who turned the outlines off, not a reader who said nothing.
+  const value = overrides?.[key];
+  return value === undefined ? DEFAULT_PROJECTION_OPTIONS[key] : value;
+}
+
+function clampIndex(value: number, lastAxis: number): number {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(lastAxis, Math.max(0, Math.floor(value)));
+}
+
+function apart(yAxis: number, xAxis: number, lastAxis: number): number {
+  if (yAxis !== xAxis) return yAxis;
+  // One axis against itself is a diagonal line, which says nothing at all.
+  return xAxis > 0 ? xAxis - 1 : Math.min(1, lastAxis);
+}
+
+function clampCount(
+  value: number,
+  fallback: number,
+  lowest: number,
+  highest: number,
+): number {
+  const wanted = Number.isFinite(value) ? Math.floor(value) : fallback;
+  return Math.min(highest, Math.max(lowest, wanted));
+}
+
+function atLeast(value: number, fallback: number, floor: number): number {
+  return Math.max(floor, Number.isFinite(value) ? value : fallback);
+}

package/src/projection/core/projectionResult.ts

@@ -0,0 +1,123 @@
+import type { MatrixLike } from '../../chart/core/matrix.ts';
+import type { OverlayMarkShape } from '../../overlay/core/overlayMarks.ts';
+
+import type { VariableAxis } from './variableAxis.ts';
+
+/** One axis of a reduced space — a component, a UMAP dimension. */
+export interface ProjectionAxis {
+  /** What it is called on an axis: `PC 1`, `UMAP 1`. */
+  name: string;
+  /**
+   * The share of the differences between the samples it accounts for, between
+   * 0 and 1 — a fraction, never a percentage. Left out by a method that
+   * publishes no such number, which is what removes the "how much each
+   * explains" tab rather than showing it empty.
+   * @default undefined
+   */
+  share?: number;
+  /**
+   * The variance of this axis' own scores, shown only in the fine print of a
+   * hover card, for the one reader in fifty who wants it.
+   * @default undefined
+   */
+  eigenvalue?: number;
+}
+
+/** A reference point drawn over the map that is not a sample. */
+export interface ProjectionMarker {
+  /** What it is called, e.g. `Centre of cluster 2`. */
+  label: string;
+  /** Its position, one value per axis, in the embedding's own units. */
+  position: readonly number[];
+  /**
+   * Which group it belongs to, as an index into the resolved groups, so it
+   * takes that group's colour.
+   * @default -1 — it is drawn in the muted ink
+   */
+  group?: number;
+  /**
+   * The glyph it is drawn with.
+   * @default 'cross'
+   */
+  shape?: OverlayMarkShape;
+}
+
+/** What each original measurement contributes to each axis. */
+export interface ProjectionLoadings {
+  /**
+   * The weight of every measurement in every axis: row `i` is axis `i`,
+   * column `j` is original measurement `j` — the orientation `ml-pca`'s
+   * `getLoadings()` returns.
+   */
+  weights: MatrixLike;
+  /** How the measurements are laid out, which decides a line or bars. */
+  variables: VariableAxis;
+  /**
+   * The average of every measurement, in the data's own units. Without it the
+   * panel can only draw weights; with it, it can draw what a sample at each
+   * end of an axis actually looks like, which is the only view a reader who
+   * has never met a loading can read.
+   * @default undefined — the "effect on a sample" view is not offered
+   */
+  mean?: readonly number[];
+  /**
+   * The standard deviation of each axis' own scores, which is how far along an
+   * axis the average sample is pushed.
+   * @default undefined — the "effect on a sample" view is not offered
+   */
+  spread?: readonly number[];
+  /**
+   * The standard deviation of every measurement, when the model divided by it.
+   * Left out when it did not, which is what removes the "in your units" view,
+   * because it would then be the same drawing twice.
+   * @default undefined
+   */
+  scales?: readonly number[];
+  /**
+   * What the measured values are, for the vertical axis, e.g. `Absorbance`.
+   * @default '' — the axis carries no title
+   */
+  valueLabel?: string;
+}
+
+/** What a dimension-reduction run produced, whatever produced it. */
+export interface ProjectionResult {
+  /**
+   * What produced it, for the headings — `Principal components`, `UMAP`,
+   * `Clusters`. It is a display string and nothing in the viewer ever branches
+   * on it.
+   */
+  method: string;
+  /** The axes, in the order the score columns hold them. */
+  axes: readonly ProjectionAxis[];
+  /** Where every sample landed: one row per sample, one column per axis. */
+  scores: MatrixLike;
+  /**
+   * What loads onto each axis. Left out by a method that cannot say — UMAP and
+   * t-SNE cannot — which is what removes the "what differs" tab.
+   * @default undefined
+   */
+  loadings?: ProjectionLoadings;
+  /**
+   * Reference points drawn over the map: the centres of a k-means run.
+   * @default undefined
+   */
+  markers?: readonly ProjectionMarker[];
+  /**
+   * How many leading rows the model was built from, the rest having been
+   * placed into it afterwards.
+   *
+   * The distinction is worth drawing because the two kinds of row are not
+   * equally trustworthy: a sample the model was fitted on helped choose where
+   * the axes point, so it is bound to sit somewhere reasonable, while one
+   * projected later can land anywhere — and landing far out is the finding,
+   * not a fault. The map draws the fitted samples filled and the projected
+   * ones hollow, and says so in its legend.
+   *
+   * Rows must therefore be ordered fitted-first, which is the order both
+   * `pcaResult` and a `getEmbedding()` followed by a `transform()` already
+   * produce.
+   * @default undefined — every row built the model
+   */
+  fittedCount?: number;
+}