@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/math/breadcrumbs.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Breadcrumbs for a drill-down: the trail of names from a hierarchy's root
+ * to the focused node, laid out left to right, with text widths from a
+ * `measure` callback. A trail may be a `{ from, to, t }` transition: shared
+ * crumbs stay put, others fade with their end's weight, so it scrubs.
+ */
+/**
+ * A focus path (names below the root: `[]` is the root, `["src", "lib"]`
+ * is "lib" inside "src"), or a scrubbable `{ from, to, t }` transition
+ * between two, either end possibly itself a transition. What
+ * {@link useDrillDown} produces and both a hierarchy chart's `focus` and
+ * {@link Breadcrumbs} take.
+ *
+ * @category Charts
+ */
+export type HierarchyPathSpec = readonly string[] | {
+    from: HierarchyPathSpec;
+    to: HierarchyPathSpec;
+    t: number;
+};
+/** Whether a path spec is a transition rather than a plain path. */
+export declare function isPathTransition(spec: HierarchyPathSpec): spec is Exclude<HierarchyPathSpec, readonly string[]>;
+/**
+ * One path of a (possibly nested) transition with its share of the blend.
+ *
+ * @category Math & helpers
+ */
+export interface WeightedPath {
+    path: readonly string[];
+    /** 0..1; the weights of one spec sum to 1. */
+    weight: number;
+}
+/** Whether two paths name the same node. */
+export declare function samePath(a: readonly string[], b: readonly string[]): boolean;
+/**
+ * A path spec as the paths it blends, each with its weight (equal paths
+ * merged, zero weights dropped, in first-seen order).
+ *
+ * @category Math & helpers
+ */
+export declare function flattenPathSpec(spec: HierarchyPathSpec): WeightedPath[];
+/**
+ * Where a path spec is heading: `to`'s path (recursively), or the plain path.
+ *
+ * @category Math & helpers
+ */
+export declare function pathTarget(spec: HierarchyPathSpec): readonly string[];
+/**
+ * One crumb of a laid-out trail. Offsets are from the trail's anchor, in
+ * the unit `measure` returned.
+ *
+ * @category Math & helpers
+ */
+export interface BreadcrumbItem {
+    /** Stable identity: the crumb's path, JSON-encoded (`"…"` for the ellipsis). */
+    key: string;
+    /** The crumb's own path below the root (`[]` for the root crumb); for the ellipsis, the deepest crumb it hides. */
+    path: string[];
+    /** The text shown (the root's name for the root crumb). */
+    name: string;
+    /** 0 for the root crumb, +1 per level (the ellipsis is 1). */
+    depth: number;
+    /** Left edge of the crumb's text. */
+    x: number;
+    /** Width of the crumb's text. */
+    width: number;
+    /** Centre of the separator drawn before this crumb (unused at depth 0). */
+    separatorX: number;
+    /** Presence, 0..1: the summed weight of the paths that show it. */
+    weight: number;
+    /** How much this crumb is the focused (last) one, 0..1, as a fraction of its own weight. */
+    current: number;
+    /** Whether this is the ellipsis standing for the crumbs collapsed out of the middle. */
+    ellipsis?: boolean;
+    /** For the ellipsis: the names it stands for, root side first (of its heaviest path). */
+    hidden?: string[];
+}
+/**
+ * The trail's "back" control, laid out before the root crumb.
+ *
+ * @category Math & helpers
+ */
+export interface BreadcrumbBack {
+    /** Left edge of the control. */
+    x: number;
+    /** Its width, as given. */
+    width: number;
+    /** Presence, 0..1: the weight of the paths below the root (none at the root). */
+    weight: number;
+    /** Where it goes: the parent of the path the spec is heading for; null when heading for the root. */
+    path: string[] | null;
+}
+/** @category Math */
+export interface BreadcrumbLayoutOptions {
+    /** The root crumb's text. */
+    root: string;
+    /** Width of a crumb's text. */
+    measure: (text: string) => number;
+    /** Width of the separator's text. */
+    separatorWidth: number;
+    /** Space each side of a separator. */
+    gap: number;
+    /** Where the anchor is on the trail. @default "left" */
+    align?: "left" | "center" | "right";
+    /**
+     * The widest a trail may be, back control included. Wider paths keep the
+     * root and as many last crumbs as fit, collapsing the rest into one
+     * ellipsis; root, ellipsis and last crumb always show. Omitted, never collapses.
+     */
+    maxWidth?: number;
+    /** The ellipsis's text. @default "…" */
+    ellipsis?: string;
+    /** Reserve room for a back control this wide before the root crumb (plus `2 × gap`). Omitted, none. */
+    backWidth?: number;
+}
+/**
+ * Lays out a path spec's crumbs: one per distinct prefix of every blended
+ * path, each placed after those before it on its own path. With
+ * `maxWidth`, paths too wide collapse their middle into an ellipsis whose
+ * `path` is the deepest crumb it hides.
+ *
+ * @category Math & helpers
+ */
+export declare function breadcrumbLayout(spec: HierarchyPathSpec, options: BreadcrumbLayoutOptions): {
+    items: BreadcrumbItem[];
+    width: number;
+    back?: BreadcrumbBack;
+};

package/dist/math/bubble.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Bubble sizing: values to marker radii with area, not radius, proportional
+ * to value (a viewer reads area).
+ */
+/**
+ * One radius per input value, parallel to `values`.
+ *
+ * @category Math & helpers
+ */
+export type BubbleRadii = number[];
+/** @category Math */
+export interface BubbleRadiusOptions {
+    /** Radius for a value of 0. @default 0 */
+    minRadius?: number;
+    /** Radius for `maxValue`. @default 1 */
+    maxRadius?: number;
+    /** The value that maps to `maxRadius`. Defaults to the greatest finite value in `values`. */
+    maxValue?: number;
+}
+/**
+ * Values to marker radii with area proportional to value:
+ * `minRadius + (maxRadius - minRadius) * sqrt(value / maxValue)`. When every
+ * value is 0, every radius is `minRadius`.
+ *
+ * @param values - One per marker; non-finite or negative entries clamp to 0.
+ * @returns One radius per value, in `minRadius`/`maxRadius`'s units.
+ * @category Math & helpers
+ */
+export declare function bubbleRadiusScale(values: readonly number[], options?: BubbleRadiusOptions): BubbleRadii;
+/**
+ * Reference values for a size key over `[0, maxValue]`: at most `count`
+ * round numbers above zero, the largest kept.
+ *
+ * @param count - Defaults to 3.
+ * @returns Ascending values in `(0, maxValue]`; empty when `maxValue` is not positive.
+ * @category Math & helpers
+ */
+export declare function bubbleLegendValues(maxValue: number, count?: number): number[];

package/dist/math/bullet.d.ts

@@ -0,0 +1,110 @@
+/** Bullet-chart geometry: one row's scale, qualitative bands, measure bar and target marker, as data values and as fractions of the row. */
+import type { Range } from "@sophistry/core/geometry";
+/**
+ * Options for {@link bulletDomain}.
+ *
+ * @category Math & helpers
+ */
+export interface BulletDomainOptions {
+    /**
+     * The scale's start, in data units. Defaults to 0, or below the smallest value when one is
+     * negative.
+     */
+    min?: number;
+    /**
+     * The scale's end, in data units. Defaults to the largest value (0 when every value is
+     * negative).
+     */
+    max?: number;
+    /** Round default ends out to tick values; an explicit `min`/`max` is kept. @default true */
+    nice?: boolean;
+    /** Roughly how many ticks the scale should offer. @default 5 */
+    targetTicks?: number;
+}
+/**
+ * The scale one bullet (or several sharing a scale) spans: from 0, or the
+ * smallest value when negative, to the largest, rounded out to ticks.
+ * Non-finite values are ignored; with nothing to fit it reads `0..1`.
+ *
+ * @param values - Everything the scale must show: values, targets, thresholds.
+ * @returns `[min, max, step]`, with `step` the tick spacing.
+ * @category Math & helpers
+ */
+export declare function bulletDomain(values: readonly number[], options?: BulletDomainOptions): Range;
+/**
+ * A stretch of a bullet's scale, in data units and as fractions of its
+ * length (0 at the scale's start, 1 at its end).
+ *
+ * @category Math & helpers
+ */
+export interface BulletSpan {
+    /** Start, in data units. */
+    from: number;
+    /** End, in data units. */
+    to: number;
+    /** `from` as a fraction of the scale, 0..1. */
+    startFraction: number;
+    /** `to` as a fraction of the scale, 0..1. */
+    endFraction: number;
+}
+/**
+ * One qualitative band of a bullet: a {@link BulletSpan} and its place in the
+ * input `ranges`.
+ *
+ * @category Math & helpers
+ */
+export interface BulletBand extends BulletSpan {
+    /** Position in the input `ranges` array: 0 is the worst band. */
+    index: number;
+}
+/**
+ * Options for {@link bulletRow}.
+ *
+ * @category Math & helpers
+ */
+export interface BulletRowOptions extends BulletDomainOptions {
+    /** The comparative measure the value is judged against, in data units. */
+    target?: number;
+    /**
+     * Qualitative thresholds in ascending order, each where a band ends:
+     * `[150, 225, 300]` is poor to 150, satisfactory to 225, good beyond. The
+     * last band runs on to the scale's end.
+     */
+    ranges?: readonly number[];
+    /** Use this scale as is, ignoring `min`, `max`, `nice` and `targetTicks`, so several bullets share one ({@link bulletDomain}). */
+    domain?: Range;
+}
+/**
+ * One bullet's resolved geometry.
+ *
+ * @category Math & helpers
+ */
+export interface BulletRowGeometry {
+    /** The scale, `[min, max, step]`. */
+    domain: Range;
+    /** Tick values along the scale, ascending. */
+    ticks: number[];
+    /** One band per input threshold, in input order (worst first). */
+    bands: BulletBand[];
+    /** Where the measure bar starts: 0, or the scale end nearest it when the scale has no zero. */
+    baseline: number;
+    /** Whether the scale contains zero, so the bar can grow from it (otherwise it fades in). */
+    zero: boolean;
+    /** The measure bar from `baseline` to the value (clamped to the scale), or null for a non-finite value. */
+    measure: BulletSpan | null;
+    /** The target (clamped to the scale) and its fraction, or null when there is none. */
+    target: {
+        value: number;
+        fraction: number;
+    } | null;
+}
+/**
+ * Resolves one bullet: scale (covering value, target and thresholds), ticks,
+ * bands, measure bar and target marker, clamped to the scale. Non-finite
+ * inputs drop their part; a bad threshold leaves an empty band so `index`
+ * stays aligned.
+ *
+ * @param value - The featured measure, in data units.
+ * @category Math & helpers
+ */
+export declare function bulletRow(value: number, options?: BulletRowOptions): BulletRowGeometry;

package/dist/math/chord.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Chord diagram layout over a square flow matrix: `matrix[i][j]` is the
+ * flow from group `i` to `j`. Each group is an arc as long as its outflow;
+ * a chord joins sub-arc `i → j` to `j → i`, each end as wide as its flow.
+ * Angles are radians from +x, y up, starting at 12 o'clock clockwise.
+ */
+import type { Point } from "@sophistry/core/geometry";
+import type { PolarSweepOptions } from "./shared/polar.js";
+/** @category Math */
+export interface ChordOptions extends PolarSweepOptions {
+    /** Gap between neighbouring groups, in radians. @default 0.04 */
+    padAngle?: number;
+    /** Order each group's sub-arcs by descending flow instead of by column. @default false */
+    sortSubgroups?: boolean;
+    /**
+     * Every non-zero `matrix[i][j]` becomes its own chord, equally wide at both
+     * ends, and a group's arc holds outflow then inflow (so receive-only groups
+     * get an arc). Off, one chord per pair with arcs sized by outflow.
+     * @default false
+     */
+    directed?: boolean;
+}
+/**
+ * One group's arc.
+ *
+ * @category Math & helpers
+ */
+export interface ChordGroup {
+    /** Row (and column) of the matrix. */
+    index: number;
+    /** Radians from +x, where the arc begins. */
+    startAngle: number;
+    /** Radians from +x, where it ends: `endAngle - startAngle` is the signed sweep. */
+    endAngle: number;
+    /** The row's total: everything leaving the group (plus, when `directed`, everything arriving). */
+    value: number;
+}
+/**
+ * One end of a chord: a sub-arc of a group.
+ *
+ * @category Math & helpers
+ */
+export interface ChordEnd {
+    /** The group the end sits on. */
+    index: number;
+    /** The group at the chord's other end. */
+    subindex: number;
+    startAngle: number;
+    endAngle: number;
+    /** The flow this end stands for: `matrix[index][subindex]` (a directed chord's target end: `matrix[subindex][index]`). */
+    value: number;
+}
+/**
+ * A chord between two groups (or a group and itself).
+ *
+ * @category Math & helpers
+ */
+export interface ChordLink {
+    /** The end with the larger flow. */
+    source: ChordEnd;
+    /** The other end. */
+    target: ChordEnd;
+}
+/** @category Math */
+export interface ChordLayout {
+    /** One arc per matrix row, in index order. */
+    groups: ChordGroup[];
+    /** One chord per pair of groups with any flow between them, by source row then column. */
+    chords: ChordLink[];
+}
+/**
+ * Lays a square flow matrix out as a chord diagram's groups and chords.
+ *
+ * @param matrix - `matrix[i][j]` is the flow from `i` to `j`; negative and non-finite entries count as 0, ragged rows are padded with 0.
+ * @returns The groups and chords; no chords and zero-length groups when there is no flow.
+ * @category Math & helpers
+ */
+export declare function chordLayout(matrix: readonly (readonly number[])[], options?: ChordOptions): ChordLayout;
+/** @category Math */
+export interface ChordRibbonOptions {
+    /** Centre. Defaults to the origin. */
+    center?: Point;
+    /** Points per radian along each end's arc. @default 24 */
+    arcDensity?: number;
+    /** Points along each curve through the middle. @default 24 */
+    curveSamples?: number;
+    /**
+     * Draw the target end as an arrowhead: the ribbon stops this far short of
+     * the circle and narrows to a point on it. For directed chords; in
+     * `radius`'s units.
+     * @default 0
+     */
+    headRadius?: number;
+}
+/**
+ * A chord's ribbon as one open ring: along the source arc, a quadratic
+ * curve through the centre to the target, along its arc (or an arrowhead
+ * with `headRadius`), and back.
+ *
+ * @param radius - Radius the ends sit on.
+ * @category Math & helpers
+ */
+export declare function chordRibbon(chord: ChordLink, radius: number, options?: ChordRibbonOptions): Point[];

package/dist/math/cluster.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Agglomerative hierarchical clustering: pairwise row distances, the merge
+ * tree single, complete or average linkage builds, and the leaf order a
+ * dendrogram follows. The tree feeds {@link hierarchyTreeLayout} with
+ * `distance: (n) => n.height`.
+ */
+/**
+ * How cluster distance is measured from member distances: `"single"` (the
+ * closest pair; chained clusters), `"complete"` (the farthest pair; compact
+ * clusters) or `"average"` (the mean over all pairs, UPGMA).
+ *
+ * @category Math & helpers
+ */
+export type ClusterLinkage = "single" | "complete" | "average";
+/**
+ * How far apart two rows are: `"euclidean"`, `"manhattan"` (sum of absolute
+ * differences) or `"correlation"` (`1 − r`: rows that rise and fall
+ * together are close whatever their level).
+ *
+ * @category Math & helpers
+ */
+export type ClusterMetric = "euclidean" | "manhattan" | "correlation";
+/**
+ * One node of a merge tree: a leaf (one input row) or the merge of two
+ * clusters.
+ *
+ * @category Math & helpers
+ */
+export interface ClusterNode {
+    /** The input row of a leaf; -1 for a merge. */
+    index: number;
+    /** The linkage distance at which the two children merged; 0 for a leaf. */
+    height: number;
+    /** How many rows the cluster holds. */
+    size: number;
+    /** A merge's two clusters, the one holding the lower row index first; absent on a leaf. */
+    children?: [ClusterNode, ClusterNode];
+}
+/** @category Math */
+export interface ClusterTree {
+    /** The merge tree, or `null` when there are no rows. */
+    root: ClusterNode | null;
+    /** The rows in dendrogram (left-to-right leaf) order: the order to draw them in. */
+    order: number[];
+}
+/** @category Math */
+export interface ClusterOptions {
+    /** See {@link ClusterLinkage}. @default "average" */
+    linkage?: ClusterLinkage;
+    /** See {@link ClusterMetric}. @default "euclidean" */
+    metric?: ClusterMetric;
+}
+/**
+ * The distance between every pair of rows. Non-finite entries are skipped
+ * pairwise and the sum scaled up to all columns, so a gap neither shrinks
+ * nor grows a distance; rows with no column in common get `NaN`.
+ *
+ * @param metric - Defaults to `"euclidean"`.
+ * @returns A symmetric `n × n` matrix with zeros on the diagonal.
+ * @category Math & helpers
+ */
+export declare function distanceMatrix(rows: readonly (readonly number[])[], metric?: ClusterMetric): number[][];
+/**
+ * Agglomerative clustering over a distance matrix: the two closest clusters
+ * merge until one is left. Ties merge the lowest row indices first, so it
+ * is deterministic; heights rise toward the root. A non-finite distance
+ * counts as the largest finite one. O(n³) in rows.
+ *
+ * @param linkage - Defaults to `"average"`.
+ * @returns The merge tree and the dendrogram's leaf order.
+ * @category Math & helpers
+ */
+export declare function linkageTree(distances: readonly (readonly number[])[], linkage?: ClusterLinkage): ClusterTree;
+/**
+ * Clusters rows by their values: {@link distanceMatrix} then
+ * {@link linkageTree}.
+ *
+ * @param rows - One vector per row (non-finite entries are gaps).
+ * @returns The merge tree and the rows' dendrogram order.
+ * @category Math & helpers
+ */
+export declare function clusterRows(rows: readonly (readonly number[])[], options?: ClusterOptions): ClusterTree;
+/**
+ * A merge tree's leaves, left to right: the input rows in dendrogram order.
+ *
+ * @category Math & helpers
+ */
+export declare function leafOrder(root: ClusterNode): number[];

package/dist/math/contour.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Contour lines: iso-lines of a scalar field on a regular grid, by marching
+ * squares. `x` has length `ncols`, `y` length `nrows`, and `z[row][col]` is
+ * the sample at `(x[col], y[row])`.
+ */
+import type { Point } from "@sophistry/core/geometry";
+type Pt = Point;
+/** @category Math */
+export interface ContourLine {
+    level: number;
+    points: Point[];
+}
+/**
+ * `count` evenly spaced levels strictly between `min` and `max`.
+ *
+ * @internal
+ */
+export declare function evenLevels(min: number, max: number, count: number): number[];
+/**
+ * A contour segment: its two crossing points, and the identity of each — the
+ * grid or triangle edge it lies on, or the corner when the field is exactly at
+ * the level there — so the two cells sharing an edge meet at the same key.
+ *
+ * @internal
+ */
+export interface KeyedSegment {
+    keys: [number, number];
+    points: [Pt, Pt];
+}
+/**
+ * Stitches keyed segments into connected polylines, each running in its
+ * lowest-index segment's direction; a loop repeats its first point at the end.
+ *
+ * @internal
+ */
+export declare function stitch(segments: readonly KeyedSegment[]): Point[][];
+/**
+ * Iso-lines of `z` at `levels` by marching squares, one {@link ContourLine}
+ * per connected run. Cells touching a NaN corner are skipped; saddles are
+ * resolved by the cell's mean value.
+ *
+ * @param z - Samples as `z[row][col]`, at `(x[col], y[row])`.
+ * @param levels - Explicit levels, or a count strictly between the data's min and max.
+ * @returns Polylines tagged with their level; `[]` for a grid under 2 x 2 or `x`/`y` shorter than `z`.
+ * @category Math & helpers
+ */
+export declare function contourLines(x: readonly number[], y: readonly number[], z: readonly (readonly number[])[], levels: readonly number[] | number): ContourLine[];
+export {};

package/dist/math/contourf.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Filled contours: bands between consecutive level thresholds over a grid
+ * (`x` length `ncols`, `y` length `nrows`, `z[row][col]` at `(x[col],
+ * y[row])`). Each grid cell is clipped on its own, giving many small
+ * polygons per band that meet edge to edge without gaps.
+ */
+import type { Point } from "@sophistry/core/geometry";
+/**
+ * A clip vertex: a point plus the field value at it.
+ *
+ * @internal
+ */
+export interface Vtx {
+    x: number;
+    y: number;
+    z: number;
+}
+/** @category Math */
+export interface ContourBand {
+    loLevel: number;
+    hiLevel: number;
+    /** Closed polygon rings, in data space, one per contributing grid cell. */
+    polygons: Point[][];
+}
+/**
+ * `count` evenly spaced band boundaries spanning `[min, max]` inclusively,
+ * so every sample falls in a band.
+ *
+ * @internal
+ */
+export declare function evenBoundaries(min: number, max: number, count: number): number[];
+/**
+ * Clips a convex polygon by a half-plane of `z` (`z >= threshold` with
+ * `keepAbove`, else `z <= threshold`); new vertices sit exactly on the
+ * threshold.
+ *
+ * @internal
+ */
+export declare function clipByThreshold(poly: Vtx[], threshold: number, keepAbove: boolean): Vtx[];
+/**
+ * Fills `z` into bands between consecutive `levels`: `N` levels make `N - 1`
+ * closed bands `loLevel <= z <= hiLevel`. Cells touching a NaN corner, and
+ * constant fields, contribute nothing.
+ *
+ * @param z - Samples as `z[row][col]`, at `(x[col], y[row])`.
+ * @param levels - Explicit boundaries, or a count spanning the data.
+ * @returns One {@link ContourBand} per pair of consecutive levels.
+ * @category Math & helpers
+ */
+export declare function contourBands(x: readonly number[], y: readonly number[], z: readonly (readonly number[])[], levels: readonly number[] | number): ContourBand[];

package/dist/math/dodge.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Dodging overlapping marks apart: in data space, sub-bands within a
+ * category's band (`dodgeSpan`, grouped bars); in screen space, circles
+ * pushed off an axis until they clear each other (`beeswarmOffsets`).
+ */
+/**
+ * Sub-band `slot` of `count` within one band, as fractions `[from, to]` of
+ * the band, with `padding` of each sub-band left empty.
+ *
+ * @param padding - Fraction of each sub-band left empty, 0..1. Defaults to 0.1.
+ * @category Math & helpers
+ */
+export declare function dodgeSpan(slot: number, count: number, padding?: number): [number, number];
+/** @category Math */
+export interface BeeswarmOptions {
+    /**
+     * Which side of the axis circles may move to: `"both"` (centred on the
+     * axis), `"positive"` or `"negative"` (standing on a baseline).
+     * @default "both"
+     */
+    side?: "both" | "positive" | "negative";
+    /** Extra room left between neighbouring circles, in the same units as the radii. @default 0 */
+    gap?: number;
+}
+/**
+ * Beeswarm offsets: each circle keeps its position along the axis and moves
+ * across it just far enough to clear those placed before it (in ascending
+ * order). Deterministic, so it scrubs. Positions and radii share units
+ * (scene units).
+ *
+ * @param positions - Each circle's centre along the axis; non-finite ones get `NaN`.
+ * @param radii - One radius for every circle, or one per circle.
+ * @returns One offset across the axis per circle.
+ * @category Math & helpers
+ */
+export declare function beeswarmOffsets(positions: readonly number[], radii: number | readonly number[], options?: BeeswarmOptions): number[];

package/dist/math/ecdf.d.ts

@@ -0,0 +1,41 @@
+/** Empirical CDF: a step function rising from 0 to 1 by `1/n` at each observed value. */
+/**
+ * Step data shaped for `stairsPolyline`/`<Stairs>`: `edges.length === values.length + 1`.
+ *
+ * @category Math & helpers
+ */
+export interface EcdfSteps {
+    edges: number[];
+    values: number[];
+}
+/** @category Math */
+export interface EcdfOptions {
+    /**
+     * Padding left of the smallest value and right of the largest, in data units. Defaults to 5% of
+     * the data's span (0.5 when the span is 0).
+     */
+    pad?: number;
+}
+/**
+ * `EcdfOptions.pad`'s fraction-of-span default.
+ *
+ * @category Math & helpers
+ */
+export declare const DEFAULT_ECDF_PAD_FRACTION = 0.05;
+/**
+ * `EcdfOptions.pad`'s fallback when the data's span is 0 (every value identical).
+ *
+ * @category Math & helpers
+ */
+export declare const DEFAULT_ECDF_PAD_FALLBACK = 0.5;
+/**
+ * The step function of the empirical CDF of `values`, over the sorted unique
+ * finite values `u_1 < … < u_k`: `edges = [u_1 - pad, u_1, …, u_k, u_k + pad]`
+ * and `values = [0, F(u_1), …, F(u_k)]`, so the curve is 0 before `u_1`,
+ * jumps at each value, and ends at 1.
+ *
+ * @param values - The sample; non-finite entries are dropped.
+ * @returns `edges` and `values` for {@link stairsPolyline}; both empty when no finite value remains.
+ * @category Math & helpers
+ */
+export declare function ecdfSteps(values: readonly number[], options?: EcdfOptions): EcdfSteps;

package/dist/math/errorbar.d.ts

@@ -0,0 +1,27 @@
+/** `errorbar(x, y, yerr, xerr)` — a marker plus optional error bars for each finite `(x, y)` pair. */
+import type { Point } from "@sophistry/core/geometry";
+/**
+ * Symmetric errors as one magnitude per index, or asymmetric ones as a
+ * `[lower[], upper[]]` tuple.
+ *
+ * @category Math & helpers
+ */
+export type ErrorSpec = readonly number[] | readonly [readonly number[], readonly number[]];
+/** @category Math */
+export interface ErrorBarPoint {
+    /** Index into the input `xs`/`ys`, matching a point to its row after non-finite pairs are dropped. */
+    index: number;
+    point: Point;
+    /** `[point - lower, point + upper]` along y; omitted where `yerr` has no finite magnitude here. */
+    yBar?: [Point, Point];
+    /** `[point - lower, point + upper]` along x; omitted where `xerr` has no finite magnitude here. */
+    xBar?: [Point, Point];
+}
+/**
+ * One marker plus optional error bars per finite `(x, y)` pair.
+ *
+ * @param yerr - Vertical error magnitudes. See {@link ErrorSpec}.
+ * @param xerr - Horizontal error magnitudes. See {@link ErrorSpec}.
+ * @category Math & helpers
+ */
+export declare function errorBarPoints(xs: readonly number[], ys: readonly number[], yerr?: ErrorSpec, xerr?: ErrorSpec): ErrorBarPoint[];