react-cheminfo 0.28.0 → 0.29.0

package/src/chart/core/axisLabels.ts

@@ -0,0 +1,117 @@
+/**
+ * How a number is written wherever a chart writes one.
+ *
+ * The axis decides, not the number: the precision comes from the tick step, and
+ * the notation from the largest tick, so every label on one axis is written the
+ * same way and a reader can run an eye down a column of them. `chartAxisScale`
+ * works both out; this is where they turn into text.
+ *
+ * It is a second way of writing the labels `chartAxisScale` already carries,
+ * and it exists because the two answer different questions. A figure lifts a
+ * common power of ten into its axis title and writes short labels under it — a
+ * chart whose axis title is fixed by the measurement cannot, so a spectrum
+ * writes the magnitude into each label instead.
+ */
+
+import type { ChartAxisScale } from './chartAxisScale.ts';
+
+/**
+ * Write a number the way an axis label or a readout wants it.
+ *
+ * The decimals come from the axis, so every label on it is written to the same
+ * precision — but a tick that happens to land on a round number then reads
+ * `500.0000` where `500` was meant, and half its width is zeros carrying
+ * nothing. They are trimmed off the end only, never out of the middle, so
+ * `500.0002` keeps every digit it needs.
+ *
+ * `toFixed` also writes `-0` for anything that rounds to zero from below, which
+ * is never what an axis means and is jarring on the one tick a chemist looks at
+ * most.
+ * @param value - The number to write.
+ * @param decimals - How many decimals to write it to, as `niceTicks` derived.
+ * @returns The label.
+ */
+export function formatNumber(value: number, decimals: number): string {
+  const text = value.toFixed(Math.min(20, Math.max(0, Math.floor(decimals))));
+  const trimmed = text.includes('.') ? text.replace(/\.?0+$/, '') : text;
+  return trimmed === '-0' ? '0' : trimmed;
+}
+
+/**
+ * The magnitude above which a number is quicker read as a power of ten.
+ *
+ * An ion count is quoted in whatever the instrument counted in, so an intensity
+ * axis written out in full reads `200000000` — nine digits a reader has to group
+ * into threes before knowing which power of ten they are looking at, and wide
+ * enough to run into the axis title printed beside them. Above this the same
+ * tick is written `2e+8`, which says the magnitude first and in four characters.
+ *
+ * A hundred thousand rather than a million because that is where a number stops
+ * being read at a glance, and because it is the threshold every intensity in the
+ * mass side is already written against — a colourbar and an axis that disagreed
+ * about how one count is spelled would read as two measurements.
+ */
+export const SCIENTIFIC_ABOVE = 1e5;
+
+/**
+ * The magnitude below which the digits that mean anything are all behind zeros.
+ *
+ * The mirror of `SCIENTIFIC_ABOVE`: `0.00002` is four characters of nothing
+ * followed by the one digit that was measured.
+ */
+export const SCIENTIFIC_BELOW = 1e-4;
+
+/**
+ * Write a number as a mantissa and a power of ten.
+ *
+ * With no precision asked for, the mantissa keeps only the digits it needs — a
+ * tick at a hundred and fifty million is `1.5e+8` and the one above it `2e+8`,
+ * rather than both being padded to the same width with zeros that say nothing.
+ * The value is rounded to a few significant digits first, because a tick is
+ * reached by multiplying a step by an index and `3 * 0.1` is `0.30000000000000004`
+ * — which the shortest form would write out in full, every digit of it noise.
+ * @param value - The number to write.
+ * @param digits - How many decimals the mantissa carries. Left out, it carries
+ * as few as tell this number from its neighbours.
+ * @returns The number in scientific notation, or `0` for zero, which has no
+ * exponent and is written the same way on any axis.
+ */
+export function formatScientific(value: number, digits?: number): string {
+  if (value === 0) return '0';
+  if (digits === undefined) {
+    return Number(value.toPrecision(SCIENTIFIC_DIGITS)).toExponential();
+  }
+  return value.toExponential(Math.min(100, Math.max(0, Math.floor(digits))));
+}
+
+/**
+ * How one axis writes every one of its labels.
+ *
+ * The notation is chosen once, from the largest tick on the axis, and then used
+ * for all of them — including the small ones and the zero. An axis is read by
+ * running an eye along it, and one whose labels changed notation partway would
+ * have to be read a label at a time instead.
+ * @param axis - The axis, as `chartAxisScale` divided it.
+ * @returns A writer for every label on that axis.
+ */
+export function axisLabeller(axis: ChartAxisScale): (value: number) => string {
+  const { values, decimals } = axis;
+  let largest = 0;
+  for (const tick of values) {
+    const magnitude = Math.abs(tick);
+    if (magnitude > largest) largest = magnitude;
+  }
+  const scientific =
+    largest >= SCIENTIFIC_ABOVE || (largest > 0 && largest < SCIENTIFIC_BELOW);
+  return scientific
+    ? (value) => formatScientific(value)
+    : (value) => formatNumber(value, decimals);
+}
+
+/**
+ * How many significant digits survive the rounding that sheds floating noise.
+ *
+ * A tick is 1, 2 or 5 times a power of ten times an index, so two digits carry
+ * every one of them and six is room to spare for a readout written this way.
+ */
+const SCIENTIFIC_DIGITS = 6;

package/src/chart/core/boxLayout.ts

@@ -0,0 +1,126 @@
+/**
+ * Keeping the labels above the peaks apart from one another.
+ *
+ * An annotated spectrum wants a box over every peak it explains, and an
+ * isotopologue cluster puts four of them within a few pixels. Sliding them
+ * apart is most of the job, and the leader line back to the stick is what says
+ * which peak a box belongs to — so a box a little out of place is still
+ * readable.
+ *
+ * A box slid *far* out of place is not. Spacing a crowd out marches the last of
+ * them across the whole plot, where it comes to rest over peaks it says nothing
+ * about, with a leader long enough to be read as pointing at one of them. Those
+ * are dropped, and only those: a mark still sits on every annotated peak, so
+ * the fragment is not one the chemist concludes the spectrum lacks — it is one
+ * whose picture is a zoom away.
+ */
+
+import type { NumberArray } from 'cheminfo-types';
+
+/**
+ * Slide overlapping boxes apart, keeping every one of them inside the plot.
+ *
+ * Two sweeps, and the order of the clamps is the whole behaviour. The first
+ * sweep runs left to right and pushes each box far enough past its neighbour to
+ * clear it, which piles the crowding up against the right edge; the second runs
+ * back the other way, pulling that pile inside the right bound and spacing it
+ * out leftwards again.
+ *
+ * The left bound is then applied last, after the spacing, and so beats it. A
+ * cluster too wide for the room it is in therefore ends with its leftmost boxes
+ * overlapping rather than with one of them hanging off the plot — an overlap is
+ * two labels a reader can still pick apart with the leader lines, while a box
+ * outside the plot is clipped away and reads as an annotation that was never
+ * made.
+ * @param centres - Where each box would like to be centred, in pixels; any
+ * order, and the result comes back in that same order.
+ * @param bounds - `[from, to]` in pixels that no box may extend beyond.
+ * @param width - How wide every box is.
+ * @param gap - The clear space wanted between two neighbouring boxes.
+ * @param maximumDrift - How far a box may be slid from where it wanted to be
+ * before it is dropped instead, in pixels. Defaults to two whole box steps.
+ * @returns The centre each box was actually given, `NaN` for one that was slid
+ * too far and dropped.
+ */
+export function layoutAnnotationBoxes(
+  centres: NumberArray,
+  bounds: readonly [number, number],
+  width: number,
+  gap: number,
+  maximumDrift = (width + gap) * MAXIMUM_DRIFT_STEPS,
+): Float64Array {
+  const count = centres.length;
+  const placed = new Float64Array(count);
+  if (count === 0) return placed;
+
+  const half = width / 2;
+  const minimumCentre = bounds[0] + half;
+  const maximumCentre = bounds[1] - half;
+  const step = width + gap;
+  const order = ascendingOrder(centres);
+
+  let previous = Number.NEGATIVE_INFINITY;
+  for (let position = 0; position < count; position++) {
+    const index = order[position] as number;
+    let centre = Math.min(
+      Math.max(centres[index] as number, minimumCentre),
+      maximumCentre,
+    );
+    if (centre < previous + step) centre = previous + step;
+    placed[index] = centre;
+    previous = centre;
+  }
+
+  let next = Number.POSITIVE_INFINITY;
+  for (let position = count - 1; position >= 0; position--) {
+    const index = order[position] as number;
+    let centre = placed[index] as number;
+    if (centre > maximumCentre) centre = maximumCentre;
+    if (centre > next - step) centre = next - step;
+    if (centre < minimumCentre) centre = minimumCentre;
+    placed[index] = centre;
+    next = centre;
+  }
+
+  // A picture that has been slid too far from the peak it explains is worse
+  // than no picture: it hangs over a peak it says nothing about, and the leader
+  // back to its own is long enough to be read as pointing at something else.
+  // Those are dropped rather than drawn, and the mark on the peak still says
+  // the annotation is there.
+  for (let index = 0; index < count; index++) {
+    const wanted = centres[index] as number;
+    if (Math.abs((placed[index] as number) - wanted) > maximumDrift) {
+      placed[index] = Number.NaN;
+    }
+  }
+  return placed;
+}
+
+/**
+ * How far a picture may be slid from its peak, counted in whole box steps.
+ *
+ * Two: a box may be pushed past two neighbours and still be read as belonging
+ * to the peak under it, which is what a cluster of three peaks needs. Past that
+ * the leader is longer than the box is wide and reaches across other peaks, so
+ * the picture reads as answering for one of them instead.
+ */
+export const MAXIMUM_DRIFT_STEPS = 2;
+
+/**
+ * The indices of the boxes, ordered by where they want to be.
+ *
+ * The sweeps only make sense left to right, and the caller's order is whatever
+ * the annotations came in — usually by mass, but a second producer's marks are
+ * appended rather than merged.
+ * @param centres - Where each box would like to be centred.
+ * @returns The indices, ascending by centre.
+ */
+function ascendingOrder(centres: NumberArray): Uint32Array {
+  const order = new Uint32Array(centres.length);
+  for (let index = 0; index < centres.length; index++) {
+    order[index] = index;
+  }
+  return order.toSorted(
+    (first, second) => (centres[first] as number) - (centres[second] as number),
+  );
+}

package/src/chart/core/chartAxisScale.ts

@@ -12,6 +12,15 @@ const COMFORTABLE_LABEL = 6;
 const STEP_10 = Math.sqrt(50);
 const STEP_5 = Math.sqrt(10);
 const STEP_2 = Math.SQRT2;
+/**
+ * How far a fraction may sit above 1, 2 or 5 and still count as being on it.
+ *
+ * `span / count` is computed in floating point, so a window that ought to give
+ * a step of exactly one lands a hair above it — `1.0000000000000002` — and an
+ * exact comparison would take the next step up and halve the number of ticks
+ * for no visible reason.
+ */
+const STEP_EPSILON = 1e-9;
 
 /** A niced axis: its domain, its ticks, and the labels they are written with. */
 export interface ChartAxisScale {
@@ -29,6 +38,22 @@ export interface ChartAxisScale {
   readonly labels: readonly string[];
 }
 
+/**
+ * How the step is chosen when an even division lands between two nice ones.
+ *
+ * - `nearest` — take whichever of 1, 2 or 5 the division is closest to, which
+ *   puts the tick count near what was asked for from either side.
+ * - `atMost` — always take the larger, so the count asked for is a budget the
+ *   axis never exceeds.
+ *
+ * The difference is not cosmetic. A figure asking for about five ticks wants
+ * them spaced as evenly as the numbers allow, and one either way costs it
+ * nothing. An axis in a two-hundred-pixel panel has worked its count out from
+ * the room it has and the width of a label, so one tick more than it asked for
+ * is two labels touching.
+ */
+export type ChartAxisStep = 'nearest' | 'atMost';
+
 /** How an axis is divided. */
 export interface ChartAxisScaleOptions {
   /**
@@ -39,10 +64,15 @@ export interface ChartAxisScaleOptions {
   /**
    * Whether to widen the domain outward to whole steps, so the axis ends on a
    * labelled tick. Turn it off when the domain is already exact — a share that
-   * must end at 100%.
+   * must end at 100%, or a window a reader dragged out for themselves.
    * @default true
    */
   nice?: boolean;
+  /**
+   * How the step is chosen. See {@link ChartAxisStep}.
+   * @default 'nearest'
+   */
+  step?: ChartAxisStep;
 }
 
 /**
@@ -68,11 +98,34 @@ export function chartAxisScale(
   max: number,
   options: ChartAxisScaleOptions = {},
 ): ChartAxisScale {
-  const { count = DEFAULT_COUNT, nice = true } = options;
+  const { count = DEFAULT_COUNT, nice = true, step: rounding } = options;
   const wanted = tickCount(count);
+  // A window of one point is not a window: there is no step to read a
+  // precision off, so the single label is written at the precision its own
+  // magnitude asks for. Only when the domain is taken as given — a domain that
+  // is to be niced is opened instead, so that a constant column still draws an
+  // axis to stand on.
+  if (!nice && min === max && Number.isFinite(min)) {
+    const decimals = chartTickDecimals(Math.abs(min));
+    return {
+      domain: [min, min],
+      values: [min],
+      step: 0,
+      decimals,
+      exponent: 0,
+      labels: [chartTickLabel(min, decimals)],
+    };
+  }
   const opened = openDomain(min, max);
-  const domain = nice ? chartNiceDomain(opened[0], opened[1], wanted) : opened;
-  const [first, last, increment] = tickSpec(domain[0], domain[1], wanted);
+  const domain = nice
+    ? chartNiceDomain(opened[0], opened[1], wanted, rounding)
+    : opened;
+  const [first, last, increment] = tickSpec(
+    domain[0],
+    domain[1],
+    wanted,
+    rounding,
+  );
   const spacing = increment < 0 ? -1 / increment : increment;
   const step = Number.isFinite(spacing) && spacing > 0 ? spacing : 0;
   const values = step === 0 ? [] : tickValues(first, last, increment);
@@ -93,18 +146,20 @@ export function chartAxisScale(
  * @param min - One end, in either order.
  * @param max - The other end.
  * @param count - Roughly how many ticks the domain will carry. Defaults to `5`.
+ * @param rounding - How the step is chosen. See {@link ChartAxisStep}.
  * @returns The widened domain, ascending.
  */
 export function chartNiceDomain(
   min: number,
   max: number,
   count = DEFAULT_COUNT,
+  rounding: ChartAxisStep = 'nearest',
 ): [number, number] {
   const wanted = tickCount(count);
   let [start, stop] = openDomain(min, max);
   let previous = 0;
   for (let pass = 0; pass < NICE_PASSES; pass++) {
-    const [, , increment] = tickSpec(start, stop, wanted);
+    const [, , increment] = tickSpec(start, stop, wanted, rounding);
     if (increment === previous || !Number.isFinite(increment)) break;
     const low = wholeStep(start, increment, true);
     const high = wholeStep(stop, increment, false);
@@ -163,14 +218,41 @@ export function chartExponentSuffix(exponent: number): string {
 
 type TickSpec = [first: number, last: number, increment: number];
 
-function tickSpec(start: number, stop: number, count: number): TickSpec {
+/**
+ * The nice factor a division is closest to.
+ * @param error - The division's mantissa, between 1 and 10.
+ * @returns 1, 2, 5 or 10.
+ */
+function stepNearest(error: number): number {
+  if (error >= STEP_10) return 10;
+  if (error >= STEP_5) return 5;
+  if (error >= STEP_2) return 2;
+  return 1;
+}
+
+/**
+ * The smallest nice factor at or above a division, so the ticks are never
+ * closer together than asked for.
+ * @param error - The division's mantissa, between 1 and 10.
+ * @returns 1, 2, 5 or 10.
+ */
+function stepAtMost(error: number): number {
+  if (error <= 1 + STEP_EPSILON) return 1;
+  if (error <= 2 + STEP_EPSILON) return 2;
+  if (error <= 5 + STEP_EPSILON) return 5;
+  return 10;
+}
+
+function tickSpec(
+  start: number,
+  stop: number,
+  count: number,
+  rounding: ChartAxisStep = 'nearest',
+): TickSpec {
   const rawStep = (stop - start) / count;
   const power = Math.floor(Math.log10(rawStep));
   const error = rawStep / 10 ** power;
-  let factor = 1;
-  if (error >= STEP_2) factor = 2;
-  if (error >= STEP_5) factor = 5;
-  if (error >= STEP_10) factor = 10;
+  const factor = rounding === 'atMost' ? stepAtMost(error) : stepNearest(error);
   if (power < 0) {
     const divisor = 10 ** -power / factor;
     let first = Math.round(start * divisor);

package/src/chart/core/chartDomain.ts

@@ -0,0 +1,185 @@
+/**
+ * The window a chart is showing, which is the one thing every viewer built on
+ * this package holds in common.
+ *
+ * Two numbers on each axis and nothing else — no units, no labels, no notion of
+ * what is being measured. That absence is the point: a mass spectrum reads its
+ * x axis as m/z and an infrared spectrum reads the same two numbers as
+ * wavenumbers, so a window that named either would need converting at every
+ * boundary, and a zoom gesture would have to be written twice to do the same
+ * arithmetic.
+ *
+ * The y axis is called nothing more specific than y for the same reason. It
+ * carries intensity in one viewer, absorbance or percent transmittance in
+ * another, and the arithmetic that maps it to pixels cares only that it is a
+ * range of numbers.
+ */
+
+/** The window a chart is showing, in data units. */
+export interface ChartDomain {
+  /** `[min, max]` on the horizontal axis. */
+  x: [number, number];
+  /** `[min, max]` on the vertical axis, the lower bound negative in mirror mode. */
+  y: [number, number];
+}
+
+/**
+ * How the vertical axis behaves under a gesture, where the two viewers differ.
+ *
+ * A mass spectrum is drawn as sticks standing on zero, so zero has to stay in
+ * the window however it is zoomed — a window starting at a tenth of the base
+ * peak cuts every stick off at the ankles. A continuous trace has no feet: an
+ * infrared band dragged out at 20 to 60 percent transmittance is asked about at
+ * 20 to 60 percent, and forcing 100 into the window would undo the zoom that was
+ * just asked for.
+ *
+ * The baseline is also what the wheel scales about, which is not always zero:
+ * percent transmittance runs *down* from 100, and scaling it about zero would
+ * walk the whole trace off the top of the plot instead of stretching it.
+ */
+export interface YAxisRules {
+  /**
+   * The value the wheel scales about, and the line a drag is judged against.
+   * @default 0
+   */
+  baseline?: number;
+  /**
+   * Whether the baseline must stay inside the window a drag asks for — true for
+   * a stick spectrum standing on it, false for a continuous trace.
+   * @default true
+   */
+  keepBaseline?: boolean;
+  /**
+   * Whether the features hang **down** from the baseline rather than standing up
+   * out of it.
+   *
+   * This is which side of the baseline the data is on, and it decides which way
+   * "released past the baseline" points. A mass peak and an absorbance band both
+   * stand up out of a baseline at the foot of the plot, so the gesture is a drag
+   * released *below* it. Percent transmittance hangs down from 100, which sits
+   * near the *top* — so there the gesture is a drag released above it, and asking
+   * the mass question instead would make almost every drag in the plot take the
+   * value axis with it.
+   * @default false
+   */
+  pointsDown?: boolean;
+}
+
+/** What the rules come to when a viewer states none of them. */
+export const DEFAULT_Y_AXIS_RULES: Required<YAxisRules> = {
+  baseline: 0,
+  keepBaseline: true,
+  pointsDown: false,
+};
+
+/**
+ * What a drag across the plot zooms to.
+ *
+ * `xAxis` is the reading gesture and the default: the question a chemist asks of
+ * a spectrum is nearly always "what is between 1650 and 1750", never "what is
+ * between forty and sixty percent", so a drag narrows the horizontal axis and
+ * leaves the height alone unless it is released past the baseline.
+ *
+ * `box` is the tool: while it is chosen, the rectangle dragged out is the window,
+ * both axes at once. It is a mode rather than a modifier because it is used in
+ * runs — a baseline being examined is examined several times over — and a
+ * modifier held down through each of them is a worse gesture than a tool pressed
+ * once.
+ *
+ * The two are named apart from the whole of `DragMode` so that a chart offering
+ * nothing but zoom tools can say so in its own signature — which is what stops
+ * `select`, the one drag that moves no axis, from reaching a chart with no
+ * handler for it.
+ */
+export type ZoomDragMode = 'xAxis' | 'box';
+
+/**
+ * What a drag across the plot asks for.
+ *
+ * `select` is the third and it is not a zoom at all: the rectangle swept out is
+ * handed back as a range and the window is left exactly where it was. A
+ * chromatographic peak is integrated between two retention times a chemist
+ * chose, and choosing them by dragging over them is the gesture — so the answer
+ * to it is two numbers on the horizontal axis rather than a new window, and a
+ * chart that zoomed to them as well would take the neighbouring peaks off the
+ * screen the moment the boundaries were set.
+ *
+ * It is a mode rather than a modifier for the reason `ZoomDragMode` already
+ * gives — integration is done in runs — and it is kept out of `ZoomDragMode` so
+ * that a chart offering only zoom tools, which is what the infrared toolbar
+ * hands to its `zoomGestures`, cannot be handed it by a widening nobody noticed.
+ * Handed one, that chart would sweep out a rectangle and then do nothing at all.
+ */
+export type DragMode = ZoomDragMode | 'select';
+
+/** How the y axis behaves, and what a drag is taken to mean. */
+export interface ZoomRules extends YAxisRules {
+  /**
+   * What a drag asks for.
+   * @default 'xAxis'
+   */
+  drag?: DragMode;
+}
+
+/**
+ * Which gestures a chart answers, for a viewer that offers fewer than all of
+ * them.
+ *
+ * A gesture is worth having only where the axis it moves has somewhere to go,
+ * and that is a property of what is being measured rather than of the chart. An
+ * axis running between two ends the data fills — percent transmittance from 0 to
+ * 100 — has nothing for the wheel to scale: stretching it about its baseline
+ * pushes the trace off the plot and leaves an axis that no longer reads as
+ * percent. An axis open at one end — intensity, absorbance — has weak features
+ * lying against the baseline, and bringing those up is what the wheel is for.
+ *
+ * Saying it here, once, is what keeps a viewer from answering a gesture in one
+ * mode and quietly ignoring it in another: the whole set travels as one object
+ * from whatever knows the measurement into `useChartZoom`.
+ */
+export interface ZoomGestures {
+  /**
+   * What a drag across the plot asks for.
+   * @default 'xAxis'
+   */
+  drag?: DragMode;
+  /**
+   * Whether the wheel scales the value axis about its baseline.
+   *
+   * Turned off, the wheel is left entirely alone — the page scrolls under the
+   * pointer as it does anywhere else, which is what a reader expects of a chart
+   * that does not answer the gesture.
+   * @default true
+   */
+  wheel?: boolean;
+}
+
+/** What the gestures come to when a viewer states none of them. */
+export const DEFAULT_ZOOM_GESTURES: Required<ZoomGestures> = {
+  drag: 'xAxis',
+  wheel: true,
+};
+
+/**
+ * Whether two windows show the same thing, compared by their four numbers.
+ *
+ * By value and never by identity, because the fitted window is rebuilt from the
+ * spectra whenever anything about them changes — a colour, a name, a visibility
+ * — and only some of those changes move an axis. A chart that told the two
+ * apart by identity would throw the user's zoom away every time they touched
+ * the list beside it.
+ * @param current - The window in force.
+ * @param next - The window just worked out.
+ * @returns Whether both axes already run between the same bounds.
+ */
+export function sameChartDomain(
+  current: ChartDomain,
+  next: ChartDomain,
+): boolean {
+  return (
+    current.x[0] === next.x[0] &&
+    current.x[1] === next.x[1] &&
+    current.y[0] === next.y[0] &&
+    current.y[1] === next.y[1]
+  );
+}