react-cheminfo 0.9.0 → 0.10.0

package/src/chart/core/chartBins.ts

@@ -0,0 +1,96 @@
+import type { ChartExtent } from './chartExtent.ts';
+import type { MatrixLike } from './matrix.ts';
+
+/** Counts over one shared set of bin edges, optionally split by series. */
+export interface ChartBins {
+  /** `bins + 1` edges, ascending. */
+  edges: Float64Array;
+  /** `series * bins` counts, laid out one series after another. */
+  counts: Uint32Array;
+  /** How many series the counts hold; `1` when nothing was split. */
+  series: number;
+  /** How many bins each series has. */
+  bins: number;
+  /** The largest count in any one bin of any one series, for scaling the draw. */
+  peak: number;
+}
+
+/**
+ * How one column is spread, split by group over one shared set of edges.
+ *
+ * `xHistogram` from `ml-spectra-processing` is the published helper for a
+ * single series, but it accumulates every value into one series and takes a
+ * flat array where we hold a matrix column; hence this one, which reads the
+ * matrix in place in a single pass.
+ * @param matrix - The matrix to read.
+ * @param column - Which column to bin.
+ * @param range - The edges' two ends, normally the column's shared axis domain.
+ * @param bins - How many bins to cut it into, at least one.
+ * @param groups - One group index per row, or `null` for a single series.
+ * @param series - How many groups there are; ignored when `groups` is `null`.
+ * @returns The counts. A row whose value is not finite, is outside `range`, or carries a group outside `0..series - 1` is left out rather than clamped into an end bin, because a clamped outlier reads as a real peak at the edge.
+ */
+export function chartBinCounts(
+  matrix: MatrixLike,
+  column: number,
+  range: ChartExtent,
+  bins: number,
+  groups: ArrayLike<number> | null,
+  series: number,
+): ChartBins {
+  const binCount = wholeAtLeastOne(bins);
+  const seriesCount = groups === null ? 1 : wholeAtLeastOne(series);
+  const min = Number.isFinite(range.min) ? range.min : 0;
+  const max =
+    Number.isFinite(range.max) && range.max > min ? range.max : min + 1;
+  const span = max - min;
+
+  const edges = new Float64Array(binCount + 1);
+  for (let index = 0; index < binCount; index++) {
+    edges[index] = min + (span * index) / binCount;
+  }
+  edges[binCount] = max;
+
+  const counts = new Uint32Array(seriesCount * binCount);
+  for (let row = 0; row < matrix.rows; row++) {
+    const value = matrix.get(row, column);
+    if (!Number.isFinite(value) || value < min || value > max) continue;
+
+    const group = groupOf(groups, row, seriesCount);
+    if (group < 0) continue;
+
+    // The value that is exactly `max` sits on the closing edge, which belongs
+    // to the last bin rather than to a bin past the end of the axis.
+    const bin = Math.min(
+      binCount - 1,
+      Math.floor(((value - min) / span) * binCount),
+    );
+    const slot = group * binCount + bin;
+    counts[slot] = (counts[slot] ?? 0) + 1;
+  }
+
+  let peak = 0;
+  for (const count of counts) {
+    if (count > peak) peak = count;
+  }
+
+  return { edges, counts, series: seriesCount, bins: binCount, peak };
+}
+
+function wholeAtLeastOne(count: number): number {
+  if (!Number.isFinite(count)) return 1;
+  return Math.max(1, Math.floor(count));
+}
+
+function groupOf(
+  groups: ArrayLike<number> | null,
+  row: number,
+  seriesCount: number,
+): number {
+  if (groups === null) return 0;
+  const raw = groups[row];
+  if (raw === undefined || !Number.isFinite(raw)) return -1;
+  const group = Math.trunc(raw);
+  if (group < 0 || group >= seriesCount) return -1;
+  return group;
+}

package/src/chart/core/chartExtent.ts

@@ -0,0 +1,203 @@
+import type { MatrixLike } from './matrix.ts';
+
+/** The two ends of a range. */
+export interface ChartExtent {
+  /** The smallest value. */
+  min: number;
+  /** The largest. */
+  max: number;
+}
+
+/** How far into a run of numbers to read, and what to widen. */
+export interface ChartValuesExtentOptions {
+  /**
+   * How many values to read, for a series longer than the slots it is drawn
+   * in.
+   * @default every value
+   */
+  limit?: number;
+  /**
+   * A range to widen rather than start afresh, so several runs can be covered
+   * without an array of ranges being built to merge.
+   * @default undefined — the range starts empty
+   */
+  into?: ChartExtent;
+}
+
+/** How a column's range is read and widened. */
+export interface ChartColumnExtentOptions {
+  /**
+   * Share of the span added at each end, so points do not touch the frame.
+   * @default 0.05
+   */
+  padding?: number;
+  /**
+   * Whether to stretch the range to include zero, which a bar chart must and a
+   * scatter need not.
+   * @default false
+   */
+  includeZero?: boolean;
+  /**
+   * Whether to make the range symmetric about zero, so the origin sits in the
+   * middle — what a scores or a loadings axis usually wants.
+   * @default false
+   */
+  symmetric?: boolean;
+  /**
+   * Which rows to read, for a range over one group only.
+   * @default undefined — every row is read
+   */
+  indices?: ArrayLike<number>;
+}
+
+/**
+ * The range of one column of a matrix.
+ *
+ * The matrix is read in place through `get`: no column is copied out, and a
+ * value that is not finite is skipped rather than poisoning the range with a
+ * `NaN`.
+ *
+ * The padding goes on before the stretch to zero, so a bar chart's baseline
+ * lands on zero exactly rather than a twentieth of a span below it, where the
+ * bars would float clear of the line they are measured from.
+ * @param matrix - The matrix to read.
+ * @param column - Which column.
+ * @param options - See {@link ChartColumnExtentOptions}.
+ * @returns The range, widened as asked. A column with no finite value at all gives `{ min: 0, max: 1 }`, which draws an honest empty axis.
+ */
+export function chartColumnExtent(
+  matrix: MatrixLike,
+  column: number,
+  options: ChartColumnExtentOptions = {},
+): ChartExtent {
+  const {
+    padding = DEFAULT_PADDING,
+    includeZero = false,
+    symmetric = false,
+    indices,
+  } = options;
+
+  const seen = readColumn(matrix, column, indices);
+  if (seen === null) return { min: 0, max: 1 };
+
+  const padded = chartPadExtent(seen, padding);
+  const grounded = includeZero
+    ? { min: Math.min(padded.min, 0), max: Math.max(padded.max, 0) }
+    : padded;
+  if (!symmetric) return grounded;
+
+  const reach = Math.max(Math.abs(grounded.min), Math.abs(grounded.max));
+  return { min: -reach, max: reach };
+}
+
+/**
+ * A range widened by a share of its span.
+ * @param extent - The range.
+ * @param padding - Share added at each end. Defaults to `0.05`.
+ * @returns The widened range, its two ends in order. A zero-width one is opened by 5% of its own value, or to -1..1 when that value is zero, because an axis whose ends are the same number has nowhere to put a tick.
+ */
+export function chartPadExtent(
+  extent: ChartExtent,
+  padding: number = DEFAULT_PADDING,
+): ChartExtent {
+  const { min, max } = extent;
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return { min: 0, max: 1 };
+
+  const low = Math.min(min, max);
+  const high = Math.max(min, max);
+  const span = high - low;
+  if (span === 0) {
+    const opening = low === 0 ? 1 : Math.abs(low) * DEFAULT_PADDING;
+    return { min: low - opening, max: high + opening };
+  }
+
+  const share = Number.isFinite(padding) && padding > 0 ? padding : 0;
+  const room = span * share;
+  return { min: low - room, max: high + room };
+}
+
+/**
+ * The range covering several — the shared scale a row or a column of a pair
+ * grid draws against.
+ * @param extents - The ranges to cover.
+ * @returns The covering range, or `{ min: 0, max: 1 }` when none was given.
+ */
+export function chartMergeExtents(
+  extents: readonly ChartExtent[],
+): ChartExtent {
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  for (const extent of extents) {
+    if (Number.isFinite(extent.min) && extent.min < min) min = extent.min;
+    if (Number.isFinite(extent.max) && extent.max > max) max = extent.max;
+  }
+  if (min > max) return { min: 0, max: 1 };
+  return { min, max };
+}
+
+/**
+ * A range covering nothing, which every scan starts from.
+ *
+ * `min` above `max` is what says it is empty, and it is deliberate: a range
+ * that started at zero would report a run of nothing as a run of zeroes, and
+ * an axis would be drawn around a value the data never held.
+ */
+export const EMPTY_EXTENT: ChartExtent = {
+  min: Number.POSITIVE_INFINITY,
+  max: Number.NEGATIVE_INFINITY,
+};
+
+/**
+ * The range of a run of numbers, skipping anything that is not finite.
+ *
+ * The one scan every chart starts from, and the reason it is here rather than
+ * written out per chart: a copy that forgets the finiteness guard poisons a
+ * whole axis with one `NaN`, and a copy that forgets `limit` reads a series
+ * past the slots it is drawn in.
+ *
+ * `ml-spectra-processing`'s `xMinMaxValues` answers the same question, but
+ * this package draws in a browser and does not depend on it; a shared six-line
+ * scan is cheaper than the package for the one thing needed from it.
+ * @param values - The numbers to read, in place — nothing is copied.
+ * @param options - See {@link ChartValuesExtentOptions}.
+ * @returns The range. A run with no finite value at all gives an empty range —
+ * `min` above `max` — which `chartPadExtent` and the callers here read as
+ * nothing to draw rather than as a range around zero.
+ */
+export function chartValuesExtent(
+  values: ArrayLike<number>,
+  options: ChartValuesExtentOptions = {},
+): ChartExtent {
+  const { limit = values.length, into = EMPTY_EXTENT } = options;
+  let { min, max } = into;
+  const count = Math.min(limit, values.length);
+  for (let index = 0; index < count; index++) {
+    const value = values[index];
+    if (value === undefined || !Number.isFinite(value)) continue;
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  return { min, max };
+}
+
+const DEFAULT_PADDING = 0.05;
+
+function readColumn(
+  matrix: MatrixLike,
+  column: number,
+  indices: ArrayLike<number> | undefined,
+): ChartExtent | null {
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  const count = indices === undefined ? matrix.rows : indices.length;
+  for (let step = 0; step < count; step++) {
+    const row = indices === undefined ? step : indices[step];
+    if (row === undefined) continue;
+    const value = matrix.get(row, column);
+    if (!Number.isFinite(value)) continue;
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  if (min > max) return null;
+  return { min, max };
+}

package/src/chart/core/chartLabels.ts

@@ -0,0 +1,68 @@
+/** How an axis title is written. */
+export interface ChartAxisTitleOptions {
+  /**
+   * The share of the differences the axis accounts for, between 0 and 1 — a
+   * fraction, never a percentage. Left out for a method that publishes no such
+   * number, and then nothing is written after the name.
+   * @default undefined
+   */
+  share?: number;
+  /**
+   * Decimals in the percentage.
+   *
+   * One, because the share is a reading aid rather than a measurement: it is
+   * there so a reader can see that the seventh component carries 0.3 % and is
+   * not worth plotting. A second decimal claims a precision the decomposition
+   * does not have once the data has been resampled and scaled, and costs two
+   * more characters in a picker whose lines are already long.
+   * @default 1
+   */
+  digits?: number;
+}
+
+/**
+ * An axis title: `PC1 — 74.2 %`, or a bare `UMAP1` when the method publishes
+ * no share.
+ *
+ * The em dash is the package's own pattern for a name followed by a gloss —
+ * `RGB — mix the channels`, `MAX — Largest value` — so a component reads the
+ * same way here as everything else the reader has already met. Kept out of the
+ * frame so the frame draws whatever string it is handed, and so every method
+ * builds its titles the same way.
+ * @param name - What the axis is called, e.g. `PC1`.
+ * @param options - See {@link ChartAxisTitleOptions}.
+ * @returns The title.
+ */
+export function chartAxisTitle(
+  name: string,
+  options: ChartAxisTitleOptions = {},
+): string {
+  const { share, digits = DEFAULT_DIGITS } = options;
+  if (share === undefined || !Number.isFinite(share)) return name;
+  return `${name} — ${chartShare(share, digits)} %`;
+}
+
+/**
+ * A share written as a percentage, with no unit after it: `74.2`.
+ *
+ * Every figure that quotes a share goes through here, so an axis title and the
+ * sentence under the same chart cannot disagree about how precise the number
+ * is. A reader who meets `PC1 — 73.0 %` beside "accounts for 72.96%" has to
+ * work out whether those are two quantities or one, and they are one.
+ * @param share - The share, between 0 and 1 — a fraction, never a percentage.
+ * @param digits - Decimals in the result, defaulting to the one decimal every
+ * figure of the family writes.
+ * @returns The percentage, written out.
+ */
+export function chartShare(share: number, digits = DEFAULT_DIGITS): string {
+  if (!Number.isFinite(share)) return '';
+  return (share * 100).toFixed(readableDigits(digits));
+}
+
+const DEFAULT_DIGITS = 1;
+const MOST_DIGITS = 20;
+
+function readableDigits(digits: number): number {
+  if (!Number.isFinite(digits)) return DEFAULT_DIGITS;
+  return Math.min(MOST_DIGITS, Math.max(0, Math.floor(digits)));
+}

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