@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/math/eventplot.d.ts

@@ -0,0 +1,26 @@
+/** Event plot: a raster of vertical tick marks, one row per sequence (e.g. spike trains). */
+import type { Point } from "@sophistry/core/geometry";
+/** @category Math */
+export interface EventRow {
+    /** Index into the original `rows` — which band this row's ticks belong to. */
+    row: number;
+    /** One `[from, to]` drop-line pair per finite event time in this row. */
+    ticks: [Point, Point][];
+}
+/** @category Math */
+export interface EventPlotOptions {
+    /** Data-space spacing between successive rows' y. @default 1 */
+    lineOffset?: number;
+    /** Data-space height of each tick, centred on its row's y. @default 0.8 */
+    lineLength?: number;
+}
+/**
+ * One vertical tick per finite event time, grouped by row: row `i` sits at
+ * `y = i * lineOffset`, each tick at `x = t`, `lineLength` tall. Empty rows
+ * are kept.
+ *
+ * @param rows - One array of event positions (x) per row.
+ * @returns One {@link EventRow} per input row, in order.
+ * @category Math & helpers
+ */
+export declare function eventPlotRows(rows: readonly (readonly number[])[], options?: EventPlotOptions): EventRow[];

package/dist/math/facet.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Small multiples: which panel goes where, how big each is, and how a
+ * grid of panels reveals. Pure functions behind `<Facet>`, `<PairPlot>` and
+ * `<JointPlot>`.
+ */
+import type { BandKey, Bounds, Point } from "@sophistry/core/geometry";
+/** One panel's place in a facet grid. */
+export interface FacetSlot {
+    /** Reading-order index (row-major). */
+    index: number;
+    /** Grid row, from the top. */
+    row: number;
+    /** Grid column, from the left. */
+    column: number;
+    /** The panel's `row` category, when faceting by rows. */
+    rowKey?: BandKey;
+    /** The panel's `column` category, when faceting by columns. */
+    columnKey?: BandKey;
+}
+/** The grid {@link facetSlots} lays out. */
+export interface FacetSlots {
+    slots: FacetSlot[];
+    rows: number;
+    columns: number;
+}
+/**
+ * Where each panel of a facet grid goes: with both key lists a full grid;
+ * with one, a single row (`columnKeys`) or column (`rowKeys`) wrapped after
+ * `wrap` panels; with neither, one panel.
+ *
+ * @param wrap - Panels per line when faceting by one variable.
+ */
+export declare function facetSlots(rowKeys: readonly BandKey[], columnKeys: readonly BandKey[], wrap?: number): FacetSlots;
+/** Whether no panel sits directly below (or above, `"top"`) a slot: it is on the grid's outer edge there. */
+export declare function outerEdge(slot: FacetSlot, slots: readonly FacetSlot[], side: "top" | "bottom" | "left" | "right"): boolean;
+/** Room around a grid or panel, per side, in scene units. */
+export interface SideRoom {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+}
+/** Options for {@link facetGrid}. */
+export interface FacetGridOptions {
+    rows: number;
+    columns: number;
+    /** The whole footprint's width, in scene units. */
+    width: number;
+    /** The whole footprint's height. */
+    height: number;
+    /** The footprint's centre. Defaults to the origin. */
+    center?: Point;
+    /** Space between neighbouring panels' plotting areas, across a column gap. */
+    gapX: number;
+    /** Space between neighbouring panels' plotting areas, across a row gap. */
+    gapY: number;
+    /** Room kept free around the grid of plots, inside the footprint. */
+    outer?: Partial<SideRoom>;
+    /** Relative column widths. Defaults to equal. */
+    widthRatios?: readonly number[];
+    /** Relative row heights, top to bottom. Defaults to equal. */
+    heightRatios?: readonly number[];
+}
+/** One cell of a {@link facetGrid}: the plotting area of a panel. */
+export interface FacetCell {
+    center: Point;
+    width: number;
+    height: number;
+}
+/** What {@link facetGrid} returns. */
+export interface FacetGrid {
+    /** `cells[row][column]`, rows from the top. */
+    cells: FacetCell[][];
+    /** The box around every plotting area (the grid without its outer room). */
+    plots: Bounds;
+}
+/**
+ * Lays out a grid of plotting areas inside a footprint: outer room first,
+ * then the gaps, the rest shared between columns and rows by ratio. Each
+ * plot keeps at least a tenth of a unit.
+ */
+export declare function facetGrid(options: FacetGridOptions): FacetGrid;
+/**
+ * A panel's reveal from the grid's: every panel's frame half at once, then
+ * the data half staggered across panels in reading order.
+ *
+ * @param stagger - Fraction of the data half spent staggering, 0..0.95.
+ * @param frameEnd - Where a panel's frame half ends. Defaults to 0.5.
+ */
+export declare function panelProgress(progress: number, index: number, count: number, stagger?: number, frameEnd?: number): number;

package/dist/math/fillBetween.d.ts

@@ -0,0 +1,28 @@
+/** The region between two series over shared `x` values: a confidence band or min/max envelope. */
+import type { CurveKind, CurvePath, Point } from "@sophistry/core/geometry";
+/**
+ * One ring per continuous run, returned closed (first point repeated), as
+ * the reveal walks it back to its start.
+ *
+ * @category Math & helpers
+ */
+export type FillBetweenRings = Point[][];
+/**
+ * One closed ring per continuous run of `(x, y1, y2)`, split wherever a value
+ * is non-finite, so a gap shades as two regions.
+ *
+ * @param y1 - One boundary, parallel to `xs`.
+ * @param y2 - The other boundary, parallel to `xs`.
+ * @returns Closed rings, one per run of at least 2 finite points.
+ * @category Math & helpers
+ */
+export declare function fillBetweenRings(xs: readonly number[], y1: readonly number[], y2: readonly number[]): FillBetweenRings;
+/**
+ * One of {@link fillBetweenRings}' rings (in any units) as a closed curve,
+ * each boundary curved on its own so a boundary shared by adjacent bands is
+ * the same curve in both. A ring of another shape is closed straight.
+ *
+ * @param ring - `n` upper points, `n` lower points reversed, the first repeated.
+ * @category Math & helpers
+ */
+export declare function fillBetweenCurve(ring: readonly Point[], curve: CurveKind): CurvePath;

package/dist/math/gauge.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Gauge geometry: where a value sits on a gauge's arc, and how threshold
+ * bands divide it. Angles are radians from +x, counter-clockwise positive;
+ * a gauge reads clockwise, so its default `endAngle` is less than its
+ * `startAngle`.
+ */
+/**
+ * The default gauge start, 210° from +x: with {@link GAUGE_END_ANGLE}, a 240°
+ * arc opening downward, symmetric about 12 o'clock.
+ *
+ * @category Math & helpers
+ */
+export declare const GAUGE_START_ANGLE: number;
+/**
+ * The default gauge end: 120° clockwise of 12 o'clock (−30° from +x).
+ *
+ * @category Math & helpers
+ */
+export declare const GAUGE_END_ANGLE: number;
+/**
+ * Where `value` sits between `min` and `max`, clamped to 0..1. A non-finite
+ * value, or `max <= min`, reads as 0.
+ *
+ * @category Math & helpers
+ */
+export declare function gaugeFraction(value: number, min: number, max: number): number;
+/**
+ * The angle at `fraction` (not clamped) of the way along a gauge's arc.
+ *
+ * @param startAngle - Defaults to {@link GAUGE_START_ANGLE}.
+ * @param endAngle - Defaults to {@link GAUGE_END_ANGLE}.
+ * @category Math & helpers
+ */
+export declare function gaugeAngle(fraction: number, startAngle?: number, endAngle?: number): number;
+/**
+ * One resolved threshold band of a gauge.
+ *
+ * @category Math & helpers
+ */
+export interface GaugeBandSpan {
+    /** Position in the input `bands` array. */
+    index: number;
+    /** Where the band starts, in data units (the previous band's end, or `min`). */
+    from: number;
+    /** Where the band ends, in data units, clamped to `[min, max]`. */
+    to: number;
+    /** `from` as a fraction of the arc, 0..1. */
+    startFraction: number;
+    /** `to` as a fraction of the arc, 0..1. */
+    endFraction: number;
+}
+/**
+ * Resolves threshold bands, each given by where it ends, into arc spans:
+ * band `i` runs from band `i - 1`'s end (or `min`) to its `to`, clamped to
+ * `[min, max]`; `to: Infinity` runs to the end. Out-of-order bands keep zero
+ * width so `index` stays aligned.
+ *
+ * @returns One {@link GaugeBandSpan} per band, or `[]` when `max <= min`.
+ * @category Math & helpers
+ */
+export declare function gaugeBands(bands: readonly {
+    readonly to: number;
+}[], min: number, max: number): GaugeBandSpan[];
+/**
+ * Which band `value` falls in: the first non-empty band ending at or past
+ * it, so a value on a threshold belongs to the band it closes.
+ *
+ * @returns The band's `index`, or -1 when none reaches the value or it is not finite.
+ * @category Math & helpers
+ */
+export declare function gaugeBandIndex(value: number, spans: readonly GaugeBandSpan[]): number;

package/dist/math/hexbin.d.ts

@@ -0,0 +1,20 @@
+/** Hexagonal binning: finite `(x, y)` pairs counted into a pointy-top hex grid. */
+import type { Point } from "@sophistry/core/geometry";
+/**
+ * One occupied hex: its centre in data units, and how many points landed in it.
+ *
+ * @category Math & helpers
+ */
+export interface HexBinCell {
+    center: Point;
+    count: number;
+}
+/**
+ * Bins finite `(x, y)` pairs (paired by index) into a pointy-top hex grid of
+ * the given `radius`, in data units.
+ *
+ * @param radius - Centre-to-corner distance of each hexagon, in data units; must be positive.
+ * @returns One {@link HexBinCell} per occupied hexagon, in no particular order.
+ * @category Math & helpers
+ */
+export declare function hexbin(xs: readonly number[], ys: readonly number[], radius: number): HexBinCell[];

package/dist/math/hierarchy.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Hierarchy layouts (treemap, partition, circle packing) over a nested tree
+ * of plain objects, flattened to plain nodes in pre-order. Coordinates are
+ * in the layout's own box with **y pointing down**: `[0, width] × [0,
+ * height]` for rectangles, `[0, size]²` for circles.
+ */
+/**
+ * How a hierarchy layout reads the tree. Accessors get the datum and its
+ * pre-order index in the input tree (root 0).
+ *
+ * @category Math & helpers
+ */
+export interface HierarchyOptions<T> {
+    /**
+     * A node's children; anything but a non-empty array makes it a leaf. Defaults to the datum's
+     * `children` property.
+     */
+    children?: (datum: T, index: number) => readonly T[] | null | undefined;
+    /**
+     * A leaf's size; negative and non-finite values count as 0. A parent is the
+     * sum of its leaves. Defaults to the datum itself when a number, else 0.
+     */
+    value?: (datum: T, index: number) => number;
+    /** A node's name, used for `path`. @default "" */
+    label?: (datum: T, index: number) => string;
+    /** Order siblings by descending value; `false` keeps data order. @default true */
+    sort?: boolean;
+}
+/**
+ * One laid-out node, common to every hierarchy layout.
+ *
+ * @category Math & helpers
+ */
+export interface HierarchyNodeInfo<T> {
+    /** The input object. */
+    datum: T;
+    /** Pre-order position in the input tree: the `i` channel functions get. */
+    index: number;
+    /** 0 for the root, +1 per generation. */
+    depth: number;
+    /** Longest distance to a leaf below: 0 for a leaf. */
+    height: number;
+    /** Whether the node has no children. */
+    leaf: boolean;
+    /** The node's label. */
+    label: string;
+    /** Labels from the root down to this node, inclusive. */
+    path: string[];
+    /** The leaf's value, or the sum of a parent's leaves; always > 0. */
+    value: number;
+    /**
+     * Position of the node's top-level ancestor among the root's children, in
+     * input order (unaffected by `sort`); -1 for the root. Charts colour by it.
+     */
+    branch: number;
+    /** Position of the parent in the returned array, -1 for the root. */
+    parent: number;
+}
+/**
+ * A laid-out rectangle, in the layout box with y pointing down.
+ *
+ * @category Math & helpers
+ */
+export interface HierarchyRect<T> extends HierarchyNodeInfo<T> {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+/**
+ * A laid-out circle, in the layout box with y pointing down.
+ *
+ * @category Math & helpers
+ */
+export interface HierarchyCircle<T> extends HierarchyNodeInfo<T> {
+    x: number;
+    y: number;
+    r: number;
+}
+/**
+ * Treemap tiling: `"squarify"` (near-square tiles), `"resquarify"` (keeps its
+ * rows when values change, for animating), `"binary"`, `"slice"` (stacked
+ * vertically), `"dice"` (side by side), `"sliceDice"` (alternating by depth).
+ *
+ * @category Math & helpers
+ */
+export type TreemapTile = "squarify" | "binary" | "slice" | "dice" | "sliceDice" | "resquarify";
+/** @category Math */
+export interface TreemapOptions<T> extends HierarchyOptions<T> {
+    /** Width of the layout box. @default 1 */
+    width?: number;
+    /** Height of the layout box. @default 1 */
+    height?: number;
+    /** Tiling method. @default "squarify" */
+    tile?: TreemapTile;
+    /** Gap between siblings, and between a parent's edge and its children. @default 0 */
+    padding?: number;
+    /** Gap at the top of every parent below the root, room for its name. Defaults to `padding`. */
+    paddingTop?: number;
+    /**
+     * Lay every parent out in these rows (from {@link treemapRows} of another
+     * tree) instead of tiling afresh, so tiles keep their neighbours across a
+     * transition. Children no row lists are squarified into what is left.
+     */
+    keepRows?: TreemapRows;
+}
+/**
+ * One row of a squarified parent: its children's labels in order, and
+ * whether it runs across the parent (`dice`) or down it.
+ *
+ * @category Math & helpers
+ */
+export interface TreemapRow {
+    dice: boolean;
+    labels: readonly string[];
+}
+/**
+ * The rows squarify chose for every parent, keyed by the parent's
+ * JSON-encoded label path. See {@link treemapRows}.
+ *
+ * @category Math & helpers
+ */
+export type TreemapRows = ReadonlyMap<string, readonly TreemapRow[]>;
+/** @category Math */
+export interface PartitionOptions<T> extends HierarchyOptions<T> {
+    /** Extent of the breadth axis (siblings side by side). @default 1 */
+    width?: number;
+    /** Extent of the depth axis (one equal band per level). @default 1 */
+    height?: number;
+}
+/** @category Math */
+export interface PackOptions<T> extends HierarchyOptions<T> {
+    /** Side of the square box; the root circle's diameter. @default 1 */
+    size?: number;
+    /** Gap between sibling circles and their parent's rim. @default 0 */
+    padding?: number;
+}
+/**
+ * A treemap: each node a rectangle with area proportional to its value,
+ * nested in its parent's; squarified by default.
+ *
+ * @returns Every node with a positive value in pre-order, or `[]` when the
+ *   total is 0 or the box is empty.
+ * @throws {Error} If the tree contains a cycle.
+ * @category Math & helpers
+ */
+export declare function treemapLayout<T>(root: T, options?: TreemapOptions<T>): HierarchyRect<T>[];
+/**
+ * The rows squarify lays a tree's parents out in, for
+ * {@link TreemapOptions.keepRows}: lay another tree out in the same rows so
+ * its tiles keep their neighbours. Takes {@link treemapLayout}'s options
+ * (`tile` is ignored).
+ *
+ * @returns Every parent's rows, children by label; empty for an empty box.
+ * @throws {Error} If the tree contains a cycle.
+ * @category Math & helpers
+ */
+export declare function treemapRows<T>(root: T, options?: TreemapOptions<T>): TreemapRows;
+/**
+ * A partition (icicle / sunburst) layout: one equal band per depth along
+ * `y` (root at 0); along `x` each node spans its children, sized by value.
+ * Use `width = 1` for a sunburst's turn fraction.
+ *
+ * @returns Every node with a positive value in pre-order, or `[]` when the
+ *   total is 0 or the box is empty.
+ * @throws {Error} If the tree contains a cycle.
+ * @category Math & helpers
+ */
+export declare function partitionLayout<T>(root: T, options?: PartitionOptions<T>): HierarchyRect<T>[];
+/**
+ * Circle packing: leaves are circles with area proportional to value,
+ * packed inside their parent's enclosing circle.
+ *
+ * @returns Every node with a positive value in pre-order, or `[]` when the
+ *   total is 0 or the size is not positive.
+ * @throws {Error} If the tree contains a cycle.
+ * @category Math & helpers
+ */
+export declare function packLayout<T>(root: T, options?: PackOptions<T>): HierarchyCircle<T>[];

package/dist/math/hierarchyJoin.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Keyed transitions between two hierarchy layouts, matched by path of
+ * names: one layout of the union tree at blend `t`, staged exit, then
+ * update (matched nodes move), then enter. Pure in `t`, so it scrubs.
+ */
+import type { HierarchyNodeInfo } from "./hierarchy.js";
+import type { JoinStaging } from "./join.js";
+/**
+ * Where a node of a joined layout came from, and how present it is.
+ *
+ * @category Math & helpers
+ */
+export interface HierarchyJoinInfo {
+    /** 0..1: fading out (exit), whole (both ends), or fading in (enter). */
+    presence: number;
+    /** The node's position in the `from` layout, or -1 when it enters. */
+    fromAt: number;
+    /** The node's position in the `to` layout, or -1 when it exits. */
+    toAt: number;
+    /** How far the update stage has got, 0..1 (for blending colours). */
+    update: number;
+}
+/**
+ * Options for {@link hierarchyJoin}.
+ *
+ * @category Math & helpers
+ */
+export interface HierarchyJoinOptions<N> {
+    /** The blend, 0..1: 0 is `from`'s layout, 1 is `to`'s. */
+    blend: number;
+    /** `"staged"`: exit, then update, then enter; `"together"`: all at once, linearly. @default "staged" */
+    staging?: JoinStaging;
+    /** The numeric fields that place a node (`["x0", "x1", "y0", "y1"]` or `["x", "y", "r"]`). */
+    fields: readonly (keyof N & string)[];
+    /**
+     * Fraction of the enter stage spent staggering entering nodes, 0..0.95, in
+     * `to`'s pre-order (parents before children).
+     * @default 0
+     */
+    enterStagger?: number;
+}
+/**
+ * Each node's identity in a layout: its path of names, repeated sibling names
+ * told apart by occurrence. The root's key is always `""`.
+ *
+ * @category Math & helpers
+ */
+export declare function hierarchyKeys<T>(nodes: readonly HierarchyNodeInfo<T>[]): string[];
+/**
+ * Two layouts of one kind (same layout function and options) joined at
+ * blend `t` into one layout of the union tree, in pre-order. Matched nodes
+ * move on the update stage (`fields` and `value` blended); nodes only in
+ * `from` fade out in place; nodes only in `to` fade in at their new place.
+ *
+ * @param from - The layout at `blend = 0`.
+ * @param to - The layout at `blend = 1`.
+ * @category Math & helpers
+ */
+export declare function hierarchyJoin<T, N extends HierarchyNodeInfo<T>>(from: readonly N[], to: readonly N[], options: HierarchyJoinOptions<N>): (N & HierarchyJoinInfo)[];

package/dist/math/histogram.d.ts

@@ -0,0 +1,36 @@
+/** Histogram binning: equal-width buckets over a value range, counted. */
+import type { Range } from "@sophistry/core/geometry";
+/** @category Math */
+export interface HistogramBins {
+    /** `binCount + 1` bin boundaries, ascending. Bin `i` covers `[edges[i], edges[i + 1])`. */
+    edges: number[];
+    /** One count per bin, parallel to the gaps between `edges`. */
+    counts: number[];
+}
+/** @category Math */
+export interface HistogramOptions {
+    /**
+     * How many equal-width buckets to split `range` into; wins over a `range` step. Defaults to the
+     * count implied by the `range` step, else 10.
+     */
+    binCount?: number;
+    /**
+     * `[min, max, step?]`. Without `binCount`, `step` is the bin width (the last
+     * edge extends to a whole step). Defaults to the finite extent of `values`.
+     */
+    range?: Range;
+}
+/**
+ * `HistogramOptions.binCount`'s default.
+ *
+ * @category Math & helpers
+ */
+export declare const DEFAULT_BIN_COUNT = 10;
+/**
+ * Bins `values` into equal-width buckets across `range`. Non-finite values
+ * are dropped; the last bin is right-inclusive so the maximum lands in it.
+ *
+ * @returns `edges` (`binCount + 1` boundaries) and `counts` (one per bin).
+ * @category Math & helpers
+ */
+export declare function histogramBins(values: readonly number[], options?: HistogramOptions): HistogramBins;

package/dist/math/histogram2d.d.ts

@@ -0,0 +1,44 @@
+/** 2D histogram: finite `(x, y)` pairs counted into a grid of equal-width cells. */
+import type { Range } from "@sophistry/core/geometry";
+/** @category Math */
+export interface Histogram2D {
+    /** `xBins + 1` x bin boundaries, ascending. */
+    xEdges: number[];
+    /** `yBins + 1` y bin boundaries, ascending. */
+    yEdges: number[];
+    /** `counts[row = yBin][col = xBin]`. */
+    counts: number[][];
+    /** Largest cell value, or 0 if there were no finite pairs. */
+    maxCount: number;
+}
+/** @category Math */
+export interface Histogram2DOptions {
+    /**
+     * How many equal-width columns to split `xRange` into; wins over an `xRange` step. Defaults to
+     * the step's count, else 10.
+     */
+    xBins?: number;
+    /**
+     * How many equal-width rows to split `yRange` into; wins over a `yRange` step. Defaults to the
+     * step's count, else 10.
+     */
+    yBins?: number;
+    /**
+     * `[min, max, step?]`; `step` is the bin width unless `xBins` is given. Defaults to the finite
+     * extent of `xs`.
+     */
+    xRange?: Range;
+    /**
+     * `[min, max, step?]`; `step` is the bin height unless `yBins` is given. Defaults to the finite
+     * extent of `ys`.
+     */
+    yRange?: Range;
+}
+/**
+ * Bins `(x, y)` pairs (paired by index; dropped unless both are finite)
+ * into an `xBins × yBins` grid over `xRange` and `yRange`.
+ *
+ * @returns Both axes' edges, the `counts[row][col]` grid and the largest count.
+ * @category Math & helpers
+ */
+export declare function histogram2d(xs: readonly number[], ys: readonly number[], options?: Histogram2DOptions): Histogram2D;

package/dist/math/imshow.d.ts

@@ -0,0 +1,26 @@
+/** Image-from-array cells: `Z` (rows × cols) laid onto equal-sized cells spanning a rectangular `extent`. */
+import { type GridCell, type GridResult } from "./shared/gridCells.js";
+/** @category Math */
+export type ImshowCell = GridCell;
+/** @category Math */
+export type ImshowResult = GridResult;
+/** @category Math */
+export interface ImshowOptions {
+    /** `[xMin, xMax, yMin, yMax]`. Defaults to `[0, ncols, 0, nrows]`. */
+    extent?: [number, number, number, number];
+    /**
+     * `"upper"` puts row 0 at the top of `extent`; `"lower"` at the bottom, like
+     * ordinary cartesian data.
+     * @default "upper"
+     */
+    origin?: "upper" | "lower";
+}
+/**
+ * Lays `Z` onto `ncols × nrows` equal cells spanning `extent` (`ncols` the
+ * longest row; ragged rows tolerated). Non-finite values pass through;
+ * `min`/`max` cover finite values only (`[0, 1]` when none).
+ *
+ * @param Z - Samples as `Z[row][col]`.
+ * @category Math & helpers
+ */
+export declare function imshowCells(Z: readonly (readonly number[])[], options?: ImshowOptions): ImshowResult;