react-cheminfo 0.8.0 → 0.10.0

package/src/chart/core/chartPalette.ts

@@ -0,0 +1,71 @@
+/**
+ * What a colour is standing for, which decides where in the palette it is
+ * read from.
+ *
+ * - `group` — a species, a batch, a cluster: something a sample belongs to.
+ * - `component` — an axis of the embedding: PC 1, PC 2.
+ *
+ * The two roles read the palette in different orders, so that the first four
+ * groups and the first four components never share a hue. That is what stops a
+ * reader who learnt "blue is setosa" on one tab from reading "blue is PC 1"
+ * on the next as though it meant the same thing.
+ */
+export type ChartColorRole = 'group' | 'component';
+
+/**
+ * Eight hues that stay apart under deuteranopia, protanopia and tritanopia,
+ * and that keep their order when a figure is printed in grey.
+ *
+ * Okabe and Ito's set with black dropped and yellow held back to seventh,
+ * because yellow disappears as a one-and-a-half pixel line on a white ground;
+ * the eighth is a neutral dark, for the series past the ones anybody reads.
+ */
+export const CHART_SERIES_COLORS: readonly string[] = [
+  '#0072b2', // blue
+  '#d55e00', // vermillion
+  '#009e73', // bluish green
+  '#cc79a7', // reddish purple
+  '#e69f00', // orange
+  '#56b4e9', // sky blue
+  '#f0e442', // yellow
+  '#4d4d4d', // neutral dark
+];
+
+/**
+ * The colour of the nth series of a role, cycling once the palette runs out.
+ *
+ * A caller appending a series must never repeat a colour already on the chart,
+ * so pass the count of series already drawn rather than a stable identifier.
+ * @param index - Which series, from 0. A negative or non-finite index gives the first colour.
+ * @param role - What the colour stands for. Defaults to `'group'`.
+ * @returns The colour, as a six-digit hex string.
+ */
+export function chartSeriesColor(
+  index: number,
+  role: ChartColorRole = 'group',
+): string {
+  const order = role === 'component' ? COMPONENT_ORDER : GROUP_ORDER;
+  const step = Number.isFinite(index) && index > 0 ? Math.floor(index) : 0;
+  const position = order[step % order.length] ?? 0;
+  return CHART_SERIES_COLORS[position] ?? DEFAULT_SERIES_COLOR;
+}
+
+/**
+ * Where each group in turn reads the palette.
+ *
+ * Blue, vermillion, green and purple first: the four that hold their distance
+ * from one another under every deficiency at once, and the four a legend of a
+ * three or four species dataset will actually be read with. Yellow and the
+ * neutral come next and the two colours the components have claimed come last,
+ * so a chart has to reach eight groups before the roles collide.
+ */
+const GROUP_ORDER: readonly number[] = [0, 1, 2, 3, 6, 7, 4, 5];
+
+/**
+ * Where each component in turn reads the palette: the same eight colours
+ * entered from the two the groups leave alone longest, orange and sky blue.
+ */
+const COMPONENT_ORDER: readonly number[] = [4, 5, 7, 6, 0, 1, 2, 3];
+
+/** The blue a first group takes, and the answer when the palette is read past its end. */
+const DEFAULT_SERIES_COLOR = '#0072b2';

package/src/chart/core/chartScale.ts

@@ -0,0 +1,72 @@
+/**
+ * A data-to-pixel mapping, held as the two numbers a multiply-add needs.
+ *
+ * Deliberately not a callable: a chart converts one value per point per axis,
+ * so a closure would be one non-inlinable call per mark. The two fields are
+ * built once per axis per render and the inner loop writes the arithmetic out
+ * as `offset + value * factor`.
+ */
+export interface ChartScale {
+  /** The pixel the data value `0` lands on. */
+  readonly offset: number;
+  /** Pixels per unit of data. Negative for a y axis, which grows upward. */
+  readonly factor: number;
+}
+
+/**
+ * The mapping that puts `domainMin` at `rangeMin` and `domainMax` at `rangeMax`.
+ *
+ * For a y axis pass the plot's bottom as `rangeMin` and its top as `rangeMax`,
+ * which is what makes `factor` negative and what makes an ellipse projected
+ * through it come out the right way up with no separate flip.
+ * @param domainMin - The data value at the low end of the range.
+ * @param domainMax - The data value at the high end.
+ * @param rangeMin - The pixel `domainMin` maps to.
+ * @param rangeMax - The pixel `domainMax` maps to.
+ * @returns The mapping. A zero-width or non-finite domain gives a `factor` of
+ * zero, which pins every value to the middle of the range so that a constant
+ * column still draws instead of vanishing.
+ */
+export function chartScale(
+  domainMin: number,
+  domainMax: number,
+  rangeMin: number,
+  rangeMax: number,
+): ChartScale {
+  const span = domainMax - domainMin;
+  const reach = rangeMax - rangeMin;
+  if (span === 0 || !Number.isFinite(span) || !Number.isFinite(reach)) {
+    const middle = (rangeMin + rangeMax) / 2;
+    return { offset: Number.isFinite(middle) ? middle : 0, factor: 0 };
+  }
+  const factor = reach / span;
+  return { offset: rangeMin - domainMin * factor, factor };
+}
+
+/**
+ * Where one data value falls, in pixels.
+ *
+ * For a single conversion — a tick, a pointer, a group's mean. Inside a loop
+ * over points, write the multiply-add directly.
+ * @param scale - The mapping.
+ * @param value - The data value.
+ * @returns The pixel.
+ */
+export function chartPixel(scale: ChartScale, value: number): number {
+  if (scale.factor === 0) return scale.offset;
+  return scale.offset + value * scale.factor;
+}
+
+/**
+ * What data value a pixel stands for — the pointer's direction.
+ * @param scale - The mapping.
+ * @param pixel - The pixel.
+ * @returns The data value, or `offset` when the scale is flat. Zero comes
+ * back unsigned, so a readout at the origin of an inverted axis never reads
+ * `-0`.
+ */
+export function chartValue(scale: ChartScale, pixel: number): number {
+  if (scale.factor === 0) return scale.offset;
+  const value = (pixel - scale.offset) / scale.factor;
+  return value === 0 ? 0 : value;
+}

package/src/chart/core/chartViewport.ts

@@ -0,0 +1,211 @@
+/**
+ * The frame a chart is zoomed into, and the arithmetic that moves it.
+ *
+ * A zoom here is a domain and never a transform: the frame hands the two axes
+ * a narrower range and everything downstream — the ticks, the outlines, the
+ * hit tests, the labels — is computed from it exactly as it is computed
+ * unzoomed. Nothing has to be told a zoom happened, which is the whole reason
+ * it is done this way, and it is why all of it is arithmetic that can be
+ * checked without rendering anything.
+ */
+
+/** The range each axis of a chart covers, when it is not covering all of it. */
+export interface ChartViewport {
+  /** What the horizontal axis covers, ascending. */
+  readonly x: readonly [number, number];
+  /** What the vertical axis covers. */
+  readonly y: readonly [number, number];
+}
+
+/**
+ * The smallest share of an axis's full range a viewport may cover, which caps
+ * how far in the reader can go. Five hundred times is past the point where the
+ * dots left on screen still stand for anything.
+ */
+export const CHART_SMALLEST_ZOOM = 0.002;
+
+/** How much one pixel of wheel travel zooms by, as a share. */
+export const CHART_WHEEL_SPEED = 0.0015;
+
+/** Pixels a wheel notch is worth where the browser reports lines. */
+export const CHART_WHEEL_LINE = 16;
+
+/** Pixels it is worth where the browser reports pages. */
+export const CHART_WHEEL_PAGE = 400;
+
+/** The most one wheel event may zoom by, so a stray burst cannot jump. */
+export const CHART_WHEEL_LARGEST = 4;
+
+/**
+ * The viewport a zoom about one point leaves behind.
+ *
+ * The point under the anchor stays where it is, which is what makes the
+ * gesture read as pulling the picture rather than nudging a slider: the reader
+ * aims at the crowd they want and it grows around the pointer.
+ * @param full - What the axes cover unzoomed, which the result never leaves.
+ * @param current - The viewport now, or `null` when the chart is showing all of it.
+ * @param anchorX - The horizontal value to hold still, in data units.
+ * @param anchorY - The vertical one.
+ * @param factor - How much wider the frame becomes; below one it narrows.
+ * @returns The new viewport, or `null` once it covers everything again — so a
+ * reader who zooms back out gets the unzoomed chart back rather than a frame
+ * that merely looks like it.
+ */
+export function chartZoomViewport(
+  full: ChartViewport,
+  current: ChartViewport | null,
+  anchorX: number,
+  anchorY: number,
+  factor: number,
+): ChartViewport | null {
+  const scale = Number.isFinite(factor) && factor > 0 ? factor : 1;
+  const x = chartZoomDomain(full.x, current?.x ?? full.x, anchorX, scale);
+  const y = chartZoomDomain(full.y, current?.y ?? full.y, anchorY, scale);
+  if (sameDomain(x, full.x) && sameDomain(y, full.y)) return null;
+  return { x, y };
+}
+
+/**
+ * A frame the reader asked for, made to fit: never narrower than the zoom cap,
+ * never reaching outside the data, and never wider than the whole of it.
+ *
+ * It is what "zoom to selection" goes through, so a lasso around one sample
+ * lands at the same depth as a wheel held down over it rather than at the
+ * bottom of a well.
+ * @param full - What the axes cover unzoomed.
+ * @param wanted - The frame asked for.
+ * @returns The frame that will be drawn, or `null` when it covers everything.
+ */
+export function chartClampViewport(
+  full: ChartViewport,
+  wanted: ChartViewport,
+): ChartViewport | null {
+  return chartZoomViewport(
+    full,
+    wanted,
+    middleOf(wanted.x),
+    middleOf(wanted.y),
+    1,
+  );
+}
+
+/**
+ * One axis zoomed about one value, clamped to its full range.
+ *
+ * A frame that would reach past an end is slid back inside rather than
+ * squashed, so the reader keeps the magnification they asked for and the cloud
+ * cannot be pushed off the edge and lost.
+ * @param full - What the axis covers unzoomed.
+ * @param current - What it covers now.
+ * @param anchor - The value to hold still, in data units.
+ * @param factor - How much wider the range becomes.
+ * @returns The new range, ascending, or `full` when the zoom has reached back out to it.
+ */
+export function chartZoomDomain(
+  full: readonly [number, number],
+  current: readonly [number, number],
+  anchor: number,
+  factor: number,
+): readonly [number, number] {
+  const bounds = ascending(full);
+  const reach = bounds[1] - bounds[0];
+  if (!(reach > 0) || !Number.isFinite(reach)) return full;
+
+  const shown = ascending(current);
+  const span = fittedSpan((shown[1] - shown[0]) * factor, reach);
+  if (span === reach) return full;
+
+  const share = anchorShare(anchor, shown);
+  const wanted = Number.isFinite(anchor) ? anchor - share * span : shown[0];
+  const start = Math.min(
+    Math.max(wanted, bounds[0]),
+    Math.max(bounds[1] - span, bounds[0]),
+  );
+  return [start, start + span];
+}
+
+/**
+ * How much a wheel event zooms by.
+ *
+ * The travel is normalised first, because the same notch of the same wheel
+ * arrives as pixels in one browser and as lines in another, and a zoom that
+ * moves three times as fast in Firefox is a fault the reader blames on the
+ * figure. One event is capped: a trackpad flick can deliver a whole page of
+ * travel at once, and landing four hundred times out is not recoverable by
+ * feel.
+ * @param delta - The event's `deltaY`; positive scrolls away and zooms out.
+ * @param mode - Its `deltaMode`: 0 pixels, 1 lines, 2 pages. Defaults to `0`.
+ * @param speed - Share zoomed per pixel of travel. Defaults to {@link CHART_WHEEL_SPEED}.
+ * @returns The factor to hand {@link chartZoomViewport}; `1` for an event that says nothing.
+ */
+export function chartWheelFactor(
+  delta: number,
+  mode = 0,
+  speed = CHART_WHEEL_SPEED,
+): number {
+  if (!Number.isFinite(delta) || delta === 0) return 1;
+  const pixels = delta * wheelPixels(mode);
+  const rate = Number.isFinite(speed) && speed > 0 ? speed : CHART_WHEEL_SPEED;
+  const factor = Math.exp(pixels * rate);
+  if (!Number.isFinite(factor)) return delta > 0 ? CHART_WHEEL_LARGEST : 1;
+  return Math.min(
+    CHART_WHEEL_LARGEST,
+    Math.max(1 / CHART_WHEEL_LARGEST, factor),
+  );
+}
+
+function wheelPixels(mode: number): number {
+  if (mode === 1) return CHART_WHEEL_LINE;
+  if (mode === 2) return CHART_WHEEL_PAGE;
+  return 1;
+}
+
+/**
+ * The span a frame ends up with: at least the zoom cap, at most the whole
+ * range.
+ * @param span - The span asked for.
+ * @param reach - The full range's span.
+ * @returns The span to draw. A span of nothing is drawn at the cap, since
+ * framing one sample means going as far in as the chart goes rather than
+ * giving up and showing everything; one that is not a number does show
+ * everything, because nothing better can be said about it.
+ */
+function fittedSpan(span: number, reach: number): number {
+  const smallest = reach * CHART_SMALLEST_ZOOM;
+  if (!Number.isFinite(span)) return reach;
+  if (span <= 0) return smallest;
+  if (span >= reach) return reach;
+  return Math.max(span, smallest);
+}
+
+/**
+ * Where the anchor sits across the frame it is anchoring, from 0 to 1.
+ * @param anchor - The value held still.
+ * @param shown - The frame it sits in, ascending.
+ * @returns The share; the middle of a frame with no width, which is the only
+ * place an anchor can be said to sit on one.
+ */
+function anchorShare(anchor: number, shown: readonly [number, number]): number {
+  const span = shown[1] - shown[0];
+  if (!(span > 0) || !Number.isFinite(span)) return 0.5;
+  const share = (anchor - shown[0]) / span;
+  if (!Number.isFinite(share)) return 0.5;
+  return Math.min(1, Math.max(0, share));
+}
+
+function middleOf(domain: readonly [number, number]): number {
+  return (domain[0] + domain[1]) / 2;
+}
+
+function sameDomain(
+  one: readonly [number, number],
+  other: readonly [number, number],
+): boolean {
+  return one[0] === other[0] && one[1] === other[1];
+}
+
+function ascending(
+  domain: readonly [number, number],
+): readonly [number, number] {
+  return domain[0] <= domain[1] ? domain : [domain[1], domain[0]];
+}

package/src/chart/core/index.ts

@@ -0,0 +1,58 @@
+/**
+ * The arithmetic a figure is drawn from: a matrix read where it stands, the
+ * two numbers that turn a value into a pixel, round tick values, and the
+ * colours a series takes.
+ *
+ * None of it knows what a chart is. That is deliberate — the same scale places
+ * a principal component, a wavenumber and a cluster centre, and a site that
+ * only wants round numbers for its own canvas can have them without loading
+ * React.
+ */
+
+export type {
+  ChartAxisScale,
+  ChartAxisScaleOptions,
+} from './chartAxisScale.ts';
+export {
+  chartAxisScale,
+  chartExponentSuffix,
+  chartNiceDomain,
+  chartTickDecimals,
+  chartTickLabel,
+} from './chartAxisScale.ts';
+export type { ChartBand, ChartBandOptions } from './chartBand.ts';
+export { chartBand, chartBandCenter, chartBandIndexAt } from './chartBand.ts';
+export type { ChartBins } from './chartBins.ts';
+export { chartBinCounts } from './chartBins.ts';
+export type {
+  ChartColumnExtentOptions,
+  ChartExtent,
+  ChartValuesExtentOptions,
+} from './chartExtent.ts';
+export {
+  EMPTY_EXTENT,
+  chartColumnExtent,
+  chartMergeExtents,
+  chartPadExtent,
+  chartValuesExtent,
+} from './chartExtent.ts';
+export type { ChartAxisTitleOptions } from './chartLabels.ts';
+export { chartAxisTitle, chartShare } from './chartLabels.ts';
+export type { ChartColorRole } from './chartPalette.ts';
+export { CHART_SERIES_COLORS, chartSeriesColor } from './chartPalette.ts';
+export type { ChartScale } from './chartScale.ts';
+export { chartPixel, chartScale, chartValue } from './chartScale.ts';
+export type { ChartViewport } from './chartViewport.ts';
+export {
+  CHART_SMALLEST_ZOOM,
+  CHART_WHEEL_LARGEST,
+  CHART_WHEEL_LINE,
+  CHART_WHEEL_PAGE,
+  CHART_WHEEL_SPEED,
+  chartClampViewport,
+  chartWheelFactor,
+  chartZoomDomain,
+  chartZoomViewport,
+} from './chartViewport.ts';
+export type { MatrixLike } from './matrix.ts';
+export { mappedMatrix, rowMatrix, stackedMatrix } from './matrix.ts';

package/src/chart/core/matrix.ts

@@ -0,0 +1,100 @@
+/**
+ * Read-only view of a numeric matrix, satisfied by `ml-matrix`'s `Matrix`
+ * without a cast.
+ *
+ * Only `get` is required, because it is the cheapest read there is — 1.25 ns a
+ * cell against 12.2 ns through `to2DArray()`, which reallocates every row on
+ * every call. Nothing in this package ever copies a matrix out.
+ */
+export interface MatrixLike {
+  /** Number of rows. */
+  readonly rows: number;
+  /** Number of columns. */
+  readonly columns: number;
+  /**
+   * The value at a position.
+   * @param rowIndex - Which row, from 0.
+   * @param columnIndex - Which column, from 0.
+   * @returns The value, or `NaN` when either index is outside the matrix.
+   */
+  get: (rowIndex: number, columnIndex: number) => number;
+}
+
+/**
+ * A plain array of rows read as a matrix.
+ *
+ * The door every method that is not `ml-pca` comes through: a UMAP embedding
+ * or a k-means table is `number[][]`, and this gives it the one shape the rest
+ * of the package reads, with no copy and no dependency.
+ * @param rows - One array per row; the width is taken from the first.
+ * @returns The matrix view. An empty input gives a zero by zero matrix.
+ */
+export function rowMatrix(rows: ReadonlyArray<ArrayLike<number>>): MatrixLike {
+  const first = rows[0];
+  const columns = first === undefined ? 0 : first.length;
+  return {
+    rows: rows.length,
+    columns,
+    get(rowIndex: number, columnIndex: number): number {
+      if (columnIndex < 0 || columnIndex >= columns) return Number.NaN;
+      const row = rows[rowIndex];
+      if (row === undefined) return Number.NaN;
+      const value = row[columnIndex];
+      return value === undefined ? Number.NaN : value;
+    },
+  };
+}
+
+/**
+ * A matrix whose values pass through a function on the way out.
+ *
+ * It exists for the sign convention: a principal component's direction is
+ * arbitrary, so the scores of a flipped component have to be negated, and
+ * negating them in place would mean allocating a copy of the whole score
+ * matrix to change one column's sign.
+ * @param source - The matrix to read.
+ * @param transform - Applied to every value, given its position.
+ * @returns The mapped view, which holds a reference to `source` rather than a copy.
+ */
+export function mappedMatrix(
+  source: MatrixLike,
+  transform: (value: number, rowIndex: number, columnIndex: number) => number,
+): MatrixLike {
+  return {
+    rows: source.rows,
+    columns: source.columns,
+    get(rowIndex: number, columnIndex: number): number {
+      return transform(
+        source.get(rowIndex, columnIndex),
+        rowIndex,
+        columnIndex,
+      );
+    },
+  };
+}
+
+/**
+ * Two matrices of the same width read as one, the second below the first.
+ *
+ * It is how a set of samples a model was fitted on and a set placed into it
+ * afterwards reach a plot as one table, without either being copied: the rows
+ * of a projection and the rows of a later projection through the same model
+ * are two separate matrices that everything downstream wants to read as one.
+ * @param top - The upper matrix, whose width the result takes.
+ * @param bottom - The lower matrix; a column it does not reach reads as `NaN`.
+ * @returns The stacked view, holding a reference to both rather than a copy.
+ */
+export function stackedMatrix(top: MatrixLike, bottom: MatrixLike): MatrixLike {
+  const rows = top.rows + bottom.rows;
+  const { columns } = top;
+  return {
+    rows,
+    columns,
+    get(rowIndex: number, columnIndex: number): number {
+      if (rowIndex < 0 || rowIndex >= rows) return Number.NaN;
+      if (columnIndex < 0 || columnIndex >= columns) return Number.NaN;
+      if (rowIndex < top.rows) return top.get(rowIndex, columnIndex);
+      return bottom.get(rowIndex - top.rows, columnIndex);
+    },
+  };
+}