react-cheminfo 0.9.0 → 0.10.0

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);
+    },
+  };
+}

package/src/chart/ui/ChartAxis.tsx

@@ -0,0 +1,232 @@
+import type { ReactElement, SVGProps } from 'react';
+
+import type { ChartAxisScale } from '../core/chartAxisScale.ts';
+import { chartExponentSuffix } from '../core/chartAxisScale.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+import { chartPixel } from '../core/chartScale.ts';
+
+import type { ChartPlotArea } from './ChartFrame.tsx';
+import {
+  CHART_AXIS_LINE_STYLE,
+  CHART_AXIS_TITLE_STYLE,
+  CHART_GRID_STYLE,
+  CHART_TICK_LABEL_INSET,
+  CHART_TICK_LABEL_OFFSET,
+  CHART_TICK_LABEL_STYLE,
+  CHART_TICK_LENGTH,
+  CHART_TICK_MARK_STYLE,
+  CHART_TICK_ROOM,
+  CHART_TITLE_OFFSET,
+  CHART_ZERO_RULE_STYLE,
+} from './chartStyles.ts';
+
+/** What {@link ChartAxis} draws. */
+export interface ChartAxisProps {
+  /** Which edge of the plot the axis is written along. */
+  orientation: 'bottom' | 'left';
+  /** The niced axis, from `chartAxisScale`. */
+  scale: ChartAxisScale;
+  /** Data to pixels along this axis's own direction. */
+  pixels: ChartScale;
+  /** The rectangle the data is drawn in. */
+  plot: ChartPlotArea;
+  /**
+   * What the axis measures, built with `chartAxisTitle`. Whatever power of ten
+   * the labels were divided by is appended here, never by the caller.
+   * @default '' — the axis carries no title
+   */
+  label?: string;
+  /**
+   * Which half is drawn. The two halves straddle the data: a frame draws the
+   * `grid` half before it and the `axis` half after, so a rule never lies over
+   * a mark and a tick is never buried under one.
+   * @default 'both'
+   */
+  layer?: 'grid' | 'axis' | 'both';
+  /**
+   * Whether the plot is ruled at every tick.
+   * @default true
+   */
+  showGrid?: boolean;
+  /**
+   * Whether the tick marks and their labels are drawn.
+   * @default true
+   */
+  showTicks?: boolean;
+}
+
+/**
+ * One axis of a figure: its rules, its line, its ticks and its title.
+ *
+ * A domain that straddles zero always gets a rule there, whatever the grid is
+ * doing, because it is the one line that says which side of nothing a value
+ * fell on — and it is drawn between the grid and the axis in weight so it
+ * reads as a landmark rather than as a second frame.
+ * @param props - See {@link ChartAxisProps}.
+ * @returns The axis.
+ */
+export function ChartAxis(props: ChartAxisProps): ReactElement {
+  const {
+    orientation,
+    scale,
+    pixels,
+    plot,
+    label = '',
+    layer = 'both',
+    showGrid = true,
+    showTicks = true,
+  } = props;
+
+  const horizontal = orientation === 'bottom';
+  const crossesZero = scale.domain[0] < 0 && scale.domain[1] > 0;
+  const title = `${label}${chartExponentSuffix(scale.exponent)}`;
+
+  return (
+    <g className={`chart-axis chart-axis-${orientation}`}>
+      {layer === 'axis'
+        ? null
+        : gridRules(horizontal, scale, pixels, plot, showGrid, crossesZero)}
+      {layer === 'grid'
+        ? null
+        : axisMarks(horizontal, scale, pixels, plot, showTicks, title)}
+    </g>
+  );
+}
+
+function gridRules(
+  horizontal: boolean,
+  scale: ChartAxisScale,
+  pixels: ChartScale,
+  plot: ChartPlotArea,
+  showGrid: boolean,
+  crossesZero: boolean,
+): ReactElement[] {
+  const rules: ReactElement[] = [];
+  if (showGrid) {
+    for (const value of scale.values) {
+      // The zero rule stands in for its own grid line rather than doubling it.
+      if (crossesZero && value === 0) continue;
+      rules.push(
+        <line
+          key={`grid-${value}`}
+          {...ruleGeometry(horizontal, chartPixel(pixels, value), plot)}
+          style={CHART_GRID_STYLE}
+        />,
+      );
+    }
+  }
+  if (crossesZero) {
+    rules.push(
+      <line
+        key="zero"
+        data-chart-rule="zero"
+        {...ruleGeometry(horizontal, chartPixel(pixels, 0), plot)}
+        style={CHART_ZERO_RULE_STYLE}
+      />,
+    );
+  }
+  return rules;
+}
+
+function axisMarks(
+  horizontal: boolean,
+  scale: ChartAxisScale,
+  pixels: ChartScale,
+  plot: ChartPlotArea,
+  showTicks: boolean,
+  title: string,
+): ReactElement[] {
+  const marks: ReactElement[] = [
+    <line
+      key="line"
+      {...(horizontal
+        ? { x1: plot.left, x2: plot.right, y1: plot.bottom, y2: plot.bottom }
+        : { x1: plot.left, x2: plot.left, y1: plot.top, y2: plot.bottom })}
+      style={CHART_AXIS_LINE_STYLE}
+    />,
+  ];
+  if (showTicks) {
+    for (let index = 0; index < scale.values.length; index++) {
+      const value = scale.values[index];
+      const text = scale.labels[index];
+      if (value === undefined || text === undefined) continue;
+      marks.push(tickMark(horizontal, chartPixel(pixels, value), text, plot));
+    }
+  }
+  if (title !== '') marks.push(axisTitle(horizontal, plot, showTicks, title));
+  return marks;
+}
+
+function tickMark(
+  horizontal: boolean,
+  at: number,
+  text: string,
+  plot: ChartPlotArea,
+): ReactElement {
+  const mark = horizontal
+    ? { x1: at, x2: at, y1: plot.bottom, y2: plot.bottom + CHART_TICK_LENGTH }
+    : { x1: plot.left - CHART_TICK_LENGTH, x2: plot.left, y1: at, y2: at };
+  const caption: SVGProps<SVGTextElement> = horizontal
+    ? { x: at, y: plot.bottom + CHART_TICK_LABEL_OFFSET, textAnchor: 'middle' }
+    : {
+        x: plot.left - CHART_TICK_LABEL_INSET,
+        y: at,
+        textAnchor: 'end',
+        dominantBaseline: 'middle',
+      };
+  return (
+    <g key={`tick-${at}`}>
+      <line {...mark} style={CHART_TICK_MARK_STYLE} />
+      <text {...caption} style={CHART_TICK_LABEL_STYLE}>
+        {text}
+      </text>
+    </g>
+  );
+}
+
+function axisTitle(
+  horizontal: boolean,
+  plot: ChartPlotArea,
+  showTicks: boolean,
+  title: string,
+): ReactElement {
+  if (horizontal) {
+    const room = showTicks ? CHART_TICK_ROOM.bottom : 0;
+    return (
+      <text
+        key="title"
+        x={(plot.left + plot.right) / 2}
+        y={plot.bottom + room + CHART_TITLE_OFFSET}
+        textAnchor="middle"
+        style={CHART_AXIS_TITLE_STYLE}
+      >
+        {title}
+      </text>
+    );
+  }
+  const room = showTicks ? CHART_TICK_ROOM.left : 0;
+  const x = plot.left - room - CHART_TICK_LENGTH;
+  const y = (plot.top + plot.bottom) / 2;
+  return (
+    <text
+      key="title"
+      x={x}
+      y={y}
+      textAnchor="middle"
+      transform={`rotate(-90 ${x} ${y})`}
+      style={CHART_AXIS_TITLE_STYLE}
+    >
+      {title}
+    </text>
+  );
+}
+
+function ruleGeometry(
+  horizontal: boolean,
+  at: number,
+  plot: ChartPlotArea,
+): { x1: number; x2: number; y1: number; y2: number } {
+  return horizontal
+    ? { x1: at, x2: at, y1: plot.top, y2: plot.bottom }
+    : { x1: plot.left, x2: plot.right, y1: at, y2: at };
+}