react-cheminfo 0.9.0 → 0.10.0

package/src/overlay/ui/overlayValueStyles.ts

@@ -0,0 +1,210 @@
+/**
+ * The rules a control that writes its own value is drawn with.
+ *
+ * A bar over a figure used to name its settings and hide their answers: a
+ * caption reading `Colour by` beside a box the reader had to open to learn it
+ * said `Species`. The name of a setting is read once, on the first visit; its
+ * value is read every time the figure is looked at. So these controls write
+ * the value and leave the name to the pointer, the screen reader and the menu
+ * they open.
+ *
+ * None of them carries an outline or a fill at rest. The bar already has one
+ * container edge in the sunken track the tabs sit in, and a second and third
+ * box beside it turn the chrome into the loudest thing on a page whose point
+ * is the picture underneath. What stands in for the box is the ink — the value
+ * at full strength, its key word in the caption's grey — and a ground that
+ * only appears under the pointer.
+ */
+
+import type { CSSProperties } from 'react';
+
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+
+/** How a value-bearing control stands. */
+export interface OverlayValueLook {
+  /**
+   * Whether the pointer is over it.
+   * @default false
+   */
+  hovered?: boolean;
+  /**
+   * Whether the keyboard is on it. Drawn as a ring rather than as the hover
+   * ground, because a reader tabbing through a bar has to be able to tell
+   * where the focus is from a control the pointer happens to be resting on.
+   * @default false
+   */
+  focused?: boolean;
+  /**
+   * Whether the choices behind it are showing.
+   * @default false
+   */
+  active?: boolean;
+  /**
+   * Whether it cannot be pressed.
+   * @default false
+   */
+  disabled?: boolean;
+}
+
+/**
+ * A setting written as its value.
+ *
+ * Its height is a control's, so it stands level with the tab track beside it,
+ * and its width floors at the button size — which is what keeps a setting
+ * reading `95%` at forty pixels under a fingertip instead of shrinking to the
+ * width of three characters.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param look - See {@link OverlayValueLook}.
+ * @returns The button's rules.
+ */
+export function overlayValueButtonStyle(
+  metrics: OverlayMetrics,
+  look: OverlayValueLook,
+): CSSProperties {
+  const { hovered = false, focused = false, active = false } = look;
+  const { disabled = false } = look;
+  const lit = !disabled && (hovered || active);
+  return {
+    boxSizing: 'border-box',
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: OVERLAY_VALUE_GAP,
+    minWidth: metrics.buttonSize,
+    height: metrics.controlHeight,
+    padding: `0 ${metrics.paddingX}px`,
+    border: 'none',
+    borderRadius: metrics.controlRadius + 1,
+    background: lit ? 'var(--surface-sunken)' : 'transparent',
+    color: 'var(--text)',
+    font: 'inherit',
+    fontSize: metrics.fontSize,
+    lineHeight: 1,
+    whiteSpace: 'nowrap',
+    cursor: disabled ? 'default' : 'pointer',
+    opacity: disabled ? 0.6 : 1,
+    ...focusRing(focused && !disabled),
+  };
+}
+
+/**
+ * Several settings gathered into one control.
+ *
+ * It takes the sunken ground the tab track has rather than an outline of its
+ * own, so the two things on the bar that hold more than they show are told
+ * apart from the bare glyphs by the same device. Fully rounded, because that
+ * is what says a chip holds a reading rather than that it is one more button.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param look - See {@link OverlayValueLook}.
+ * @returns The chip's rules.
+ */
+export function overlayChipStyle(
+  metrics: OverlayMetrics,
+  look: OverlayValueLook,
+): CSSProperties {
+  const { hovered = false, focused = false, active = false } = look;
+  const { disabled = false } = look;
+  const lit = !disabled && (hovered || active);
+  return {
+    boxSizing: 'border-box',
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: OVERLAY_VALUE_GAP,
+    minWidth: metrics.buttonSize,
+    height: metrics.controlHeight,
+    padding: `0 ${metrics.paddingX + 2}px`,
+    border: 'none',
+    borderRadius: metrics.controlHeight / 2,
+    background: 'var(--surface-sunken)',
+    color: 'var(--text)',
+    boxShadow: lit ? 'inset 0 0 0 1px var(--border)' : undefined,
+    font: 'inherit',
+    fontSize: metrics.fontSize,
+    lineHeight: 1,
+    whiteSpace: 'nowrap',
+    cursor: disabled ? 'default' : 'pointer',
+    opacity: disabled ? 0.6 : 1,
+    ...focusRing(focused && !disabled),
+  };
+}
+
+/**
+ * The value itself, which is what the reader is scanning for.
+ * @returns The value's rules.
+ */
+export function overlayValueTextStyle(): CSSProperties {
+  return {
+    color: 'var(--text)',
+    fontWeight: 600,
+  };
+}
+
+/**
+ * The key word in front of a value.
+ *
+ * The caption's grey at the caption's weight, so a reader scanning the bar for
+ * how the figure is drawn reads `Species` and steps over `Colour` — and the
+ * pair still reads as one control rather than as a label and a button.
+ * @returns The key word's rules.
+ */
+export function overlayValueKeyStyle(): CSSProperties {
+  return {
+    color: 'var(--text-muted)',
+    fontWeight: 500,
+  };
+}
+
+/**
+ * The hairline between two settings inside a chip.
+ *
+ * Short of the chip's full height, so it separates the two readings without
+ * cutting the chip in half.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The separator's rules.
+ */
+export function overlayChipSeparatorStyle(
+  metrics: OverlayMetrics,
+): CSSProperties {
+  return {
+    width: 1,
+    height: Math.max(10, metrics.controlHeight - 14),
+    background: 'var(--border)',
+    margin: `0 ${OVERLAY_VALUE_GAP}px`,
+  };
+}
+
+/**
+ * The caret saying there is more behind the words.
+ *
+ * Faint, because it is the one part of these controls the reader never needs
+ * to read — it says that the value can be changed, and the value is what they
+ * came to see.
+ * @returns The caret's rules.
+ */
+export function overlayCaretStyle(): CSSProperties {
+  return {
+    display: 'inline-flex',
+    color: 'var(--text-faint)',
+  };
+}
+
+/** What is left between the swatches, the words and the caret. */
+const OVERLAY_VALUE_GAP = 4;
+
+/**
+ * The ring around the control the keyboard is on.
+ *
+ * Offset by a pixel so it reads as a ring around the control rather than as
+ * the outline these controls spend the rest of their life not having. It falls
+ * back to the text colour on a page that never declared an accent, since a
+ * focus ring nobody can see is the one accessibility fault a keyboard reader
+ * cannot work around.
+ * @param focused - Whether the keyboard is on it.
+ * @returns The outline rules, or nothing.
+ */
+function focusRing(focused: boolean): CSSProperties {
+  if (!focused) return {};
+  return {
+    outline: '2px solid var(--accent, var(--text))',
+    outlineOffset: 1,
+  };
+}

package/src/projection/core/embeddingResult.ts

@@ -0,0 +1,119 @@
+import type { MatrixLike } from '../../chart/core/matrix.ts';
+import { rowMatrix } from '../../chart/core/matrix.ts';
+
+import type {
+  ProjectionAxis,
+  ProjectionMarker,
+  ProjectionResult,
+} from './projectionResult.ts';
+
+/** How a {@link ProjectionResult} is built from coordinates alone. */
+export interface EmbeddingResultOptions {
+  /**
+   * What each axis is called.
+   * @default the axes numbered `Dimension 1` upward
+   */
+  names?: readonly string[];
+  /**
+   * What the method is called in the headings.
+   * @default 'Embedding'
+   */
+  method?: string;
+  /**
+   * Reference points drawn over the map.
+   * @default undefined
+   */
+  markers?: readonly ProjectionMarker[];
+  /**
+   * How many leading rows the model was built from, the rest having been
+   * placed into it afterwards — a `getEmbedding()` followed by a `transform()`
+   * gives exactly that order.
+   * @default undefined — every row built the model
+   */
+  fittedCount?: number;
+  /**
+   * Whether the coordinates are copied on the way in.
+   *
+   * They are, because the library that produces most of them hands out the
+   * array it is still working on. Every published `umap-js`, 1.0.0 through
+   * 1.4.0, returns its live embedding from `getEmbedding()` without a copy,
+   * and its `transform()` writes back into that same array whenever the batch
+   * being placed is the same size as the training set — so a viewer holding
+   * the reference would quietly redraw coordinates that had moved under it,
+   * with nothing anywhere reporting a fault. The copy costs one pass over
+   * `rows × columns`, and an embedding has two or three columns by
+   * definition, which is what makes the safe default affordable here and not
+   * on the principal-component path.
+   *
+   * Pass `false` for a progressive layout that is being animated: during
+   * fitting the live array is the point, and a copy would freeze the picture
+   * on its first frame.
+   * @default true
+   */
+  snapshot?: boolean;
+}
+
+/**
+ * Coordinates from any method as the viewer reads them.
+ *
+ * This is the door every method that is not a principal component analysis
+ * comes through. No axis carries a share and there are no loadings, so the
+ * viewer offers exactly the tabs the coordinates can fill — which for a
+ * two-dimensional UMAP is the map alone.
+ * @param coordinates - One row per sample, one column per axis.
+ * @param options - See {@link EmbeddingResultOptions}.
+ * @returns The result.
+ */
+export function embeddingResult(
+  coordinates: ReadonlyArray<ArrayLike<number>> | MatrixLike,
+  options: EmbeddingResultOptions = {},
+): ProjectionResult {
+  const {
+    names,
+    method = 'Embedding',
+    markers,
+    fittedCount,
+    snapshot = true,
+  } = options;
+  // A matrix is told from a list of rows by the one method a matrix has.
+  const read = isMatrix(coordinates) ? coordinates : rowMatrix(coordinates);
+  const scores = snapshot ? copyMatrix(read) : read;
+
+  const axes: ProjectionAxis[] = [];
+  for (let index = 0; index < scores.columns; index++) {
+    axes.push({ name: names?.[index] ?? `Dimension ${index + 1}` });
+  }
+  return { method, axes, scores, markers, fittedCount };
+}
+
+/**
+ * The same values, in a buffer nothing else holds.
+ * @param source - The matrix to read.
+ * @returns A matrix over a private copy of every value.
+ */
+function copyMatrix(source: MatrixLike): MatrixLike {
+  const { rows, columns } = source;
+  const values = new Float64Array(rows * columns);
+  for (let row = 0; row < rows; row++) {
+    const offset = row * columns;
+    for (let column = 0; column < columns; column++) {
+      values[offset + column] = source.get(row, column);
+    }
+  }
+  return {
+    rows,
+    columns,
+    get(row: number, column: number): number {
+      if (row < 0 || row >= rows || column < 0 || column >= columns) {
+        return Number.NaN;
+      }
+      return values[row * columns + column] as number;
+    },
+  };
+}
+
+function isMatrix(
+  coordinates: ReadonlyArray<ArrayLike<number>> | MatrixLike,
+): coordinates is MatrixLike {
+  return typeof (coordinates as MatrixLike).get === 'function';
+}

package/src/projection/core/explainedShares.ts

@@ -0,0 +1,105 @@
+import { chartSeriesColor } from '../../chart/core/chartPalette.ts';
+
+import type { ProjectionAxis } from './projectionResult.ts';
+
+/** One bar of the "how much each explains" tab. */
+export interface ComponentShare {
+  /** The number written on the axis, counting from one. */
+  number: number;
+  /** What it is called, e.g. `PC 3`. */
+  label: string;
+  /** Its colour, the same one it carries on every other tab. */
+  color: string;
+  /** Its own share, between 0 and 1. */
+  share: number;
+  /** Everything up to and including it, between 0 and 1. */
+  cumulative: number;
+  /**
+   * The variance of its scores, for the fine print of a hover card.
+   * @default undefined
+   */
+  eigenvalue?: number;
+}
+
+/** Everything the "how much each explains" tab draws. */
+export interface ExplainedShares {
+  /** One entry per component, largest first. */
+  components: readonly ComponentShare[];
+  /** The cumulative share the marker aims at; `0` draws no marker. */
+  target: number;
+  /**
+   * The number, counting from one, of the first component reaching the target,
+   * or `null` when none of them does.
+   */
+  reachesTargetAt: number | null;
+}
+
+/** How {@link explainedShares} builds its bars. */
+export interface ExplainedSharesOptions {
+  /**
+   * The cumulative share the marker aims at; `0` draws none.
+   * @default 0.95
+   */
+  target?: number;
+}
+
+/**
+ * The bars of the "how much each explains" tab.
+ *
+ * The running total is accumulated here rather than read from the model, so a
+ * result from any method reaches the tab the same way, and so the last value
+ * is a real 1 rather than the 1.0000000000000002 a floating-point sum returns.
+ * @param axes - The axes, in order; every one must carry a share.
+ * @param options - See {@link ExplainedSharesOptions}.
+ * @returns The bars.
+ */
+export function explainedShares(
+  axes: readonly ProjectionAxis[],
+  options: ExplainedSharesOptions = {},
+): ExplainedShares {
+  const { target = DEFAULT_TARGET } = options;
+  const aim = Number.isFinite(target) ? Math.min(1, Math.max(0, target)) : 0;
+
+  const components: ComponentShare[] = [];
+  let running = 0;
+  for (let index = 0; index < axes.length; index++) {
+    const axis = axes[index];
+    if (axis === undefined) continue;
+    // An axis that publishes no share stands at zero rather than stopping the
+    // tab: the tab is only offered when every axis has one, so this is the
+    // shape a caller reaches by asking for it anyway.
+    const share = Number.isFinite(axis.share)
+      ? Math.max(0, axis.share ?? 0)
+      : 0;
+    running += share;
+    components.push({
+      number: index + 1,
+      label: axis.name,
+      color: chartSeriesColor(index, 'component'),
+      share,
+      cumulative: running,
+      eigenvalue: axis.eigenvalue,
+    });
+  }
+
+  const last = components.at(-1);
+  if (last !== undefined && Math.abs(running - 1) < ROUNDING) {
+    last.cumulative = 1;
+  }
+
+  let reachesTargetAt: number | null = null;
+  if (aim > 0) {
+    for (const component of components) {
+      if (component.cumulative >= aim) {
+        reachesTargetAt = component.number;
+        break;
+      }
+    }
+  }
+  return { components, target: aim, reachesTargetAt };
+}
+
+const DEFAULT_TARGET = 0.95;
+
+/** How far off 1 a whole model's shares may land and still be a whole model. */
+const ROUNDING = 1e-9;

package/src/projection/core/index.ts

@@ -0,0 +1,81 @@
+/**
+ * A dimension-reduction run in the one shape the viewer reads, whatever
+ * produced it.
+ *
+ * `pcaResult` is the door for a fitted `ml-pca` model and `embeddingResult`
+ * the door for everything else — UMAP, t-SNE, a k-means table, coordinates
+ * from a file. Neither imports the library that made them: a model is
+ * described structurally, so this package depends on none of them.
+ *
+ * A result carries only what its method can honestly say. An embedding
+ * publishes no share of the variance and no weights, and it is that absence,
+ * rather than a flag anyone has to remember to set, that leaves the viewer
+ * showing the map alone instead of three empty tabs.
+ */
+
+export type { EmbeddingResultOptions } from './embeddingResult.ts';
+export { embeddingResult } from './embeddingResult.ts';
+export type {
+  ComponentShare,
+  ExplainedShares,
+  ExplainedSharesOptions,
+} from './explainedShares.ts';
+export { explainedShares } from './explainedShares.ts';
+export type {
+  LoadingProfile,
+  LoadingProfiles,
+  LoadingProfilesOptions,
+} from './loadingProfiles.ts';
+export { loadingProfiles } from './loadingProfiles.ts';
+export type { PcaLike } from './pcaLike.ts';
+export type { PcaResultOptions } from './pcaResult.ts';
+export { pcaResult } from './pcaResult.ts';
+export type { ProjectionCopy } from './projectionCopy.ts';
+export {
+  PROJECTION_COPY,
+  fillCopy,
+  mergeProjectionCopy,
+} from './projectionCopy.ts';
+export type { ProjectionCopyPatch } from './projectionCopyPatch.ts';
+export type {
+  ProjectionColorBy,
+  ProjectionOptionId,
+  ProjectionOptions,
+  ProjectionVariablesView,
+} from './projectionOptions.ts';
+export {
+  DEFAULT_PROJECTION_OPTIONS,
+  resolveProjectionOptions,
+} from './projectionOptions.ts';
+export type {
+  ProjectionAxis,
+  ProjectionLoadings,
+  ProjectionMarker,
+  ProjectionResult,
+} from './projectionResult.ts';
+export type {
+  ProjectionField,
+  ProjectionSamples,
+  ResolvedProjectionGroups,
+} from './projectionSamples.ts';
+export { resolveProjectionGroups } from './projectionSamples.ts';
+export type {
+  ProjectionBarWords,
+  ProjectionHelp,
+  ProjectionHelpExample,
+} from './projectionStrings.ts';
+export { PROJECTION_HELP } from './projectionStrings.ts';
+export type { ProjectionTab } from './projectionTabs.ts';
+export { projectionTabs } from './projectionTabs.ts';
+export type {
+  ContinuousVariableAxis,
+  NamedVariableAxis,
+  PeaksVariableAxis,
+  VariableAxis,
+} from './variableAxis.ts';
+export {
+  variableCount,
+  variableDecimals,
+  variableLabel,
+  variablePositions,
+} from './variableAxis.ts';