@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/math/stem.d.ts

@@ -0,0 +1,21 @@
+/** `stem(x, y)` — a drop line and a marker for each finite `(x, y)` pair. */
+import type { Point } from "@sophistry/core/geometry";
+/** @category Math */
+export interface StemPoint {
+    /** Index into the input `xs`/`ys`, matching a point to its row after non-finite pairs are dropped. */
+    index: number;
+    /** `baseline → (x, y)`, in data coordinates. */
+    drop: [Point, Point];
+    marker: Point;
+}
+/** @category Math */
+export interface StemOptions {
+    /** The y value each drop line starts from. @default 0 */
+    baseline?: number;
+}
+/**
+ * One drop line and marker per finite `(x, y)` pair, paired by index.
+ *
+ * @category Math & helpers
+ */
+export declare function stemPoints(xs: readonly number[], ys: readonly number[], options?: StemOptions): StemPoint[];

package/dist/math/symbol.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Scatter marker symbols: square, diamond, triangle, cross or star, each
+ * sized to the area of a circle of radius `r` so shapes read as equal sizes.
+ */
+import type { Point } from "@sophistry/core/geometry";
+/**
+ * The marker shapes a `Scatter` can draw.
+ *
+ * @category Math & helpers
+ */
+export type SymbolName = "circle" | "square" | "diamond" | "triangle" | "cross" | "star";
+/**
+ * The symbols in the order a series cycles through them: most distinct first.
+ *
+ * @category Math & helpers
+ */
+export declare const SYMBOLS: readonly SymbolName[];
+/**
+ * The outline (open ring) of `symbol` centred on `(cx, cy)`, with the area
+ * of a circle of radius `r`. A circle comes back as a 32-gon.
+ *
+ * @returns The vertices, counter-clockwise.
+ * @category Math & helpers
+ */
+export declare function symbolPolygon(symbol: SymbolName, cx: number, cy: number, r: number): Point[];

package/dist/math/tree.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Node-link tree layouts (the tidy tree and the cluster dendrogram) over a
+ * nested tree of plain objects, plus the polyline of one link. Every node is
+ * kept. Coordinates are in the layout's box: `x` along the breadth axis
+ * (`[0, width]`), `y` along the depth axis (root at 0, deepest at `height`).
+ */
+import type { Point } from "@sophistry/core/geometry";
+import type { HierarchyNodeInfo, HierarchyOptions } from "./hierarchy.js";
+/**
+ * Node-link layout: `"tidy"` places each level at its own depth with parents
+ * centred over their children; `"cluster"` is a dendrogram, every leaf at
+ * the far depth.
+ *
+ * @category Math & helpers
+ */
+export type TreeLayoutKind = "tidy" | "cluster";
+/** @category Math */
+export interface TreeLayoutOptions<T> extends HierarchyOptions<T> {
+    /** Which layout; see {@link TreeLayoutKind}. @default "tidy" */
+    layout?: TreeLayoutKind;
+    /** Extent of the breadth axis (`x`, siblings side by side). @default 1 */
+    width?: number;
+    /** Extent of the depth axis (`y`, root at 0). @default 1 */
+    height?: number;
+    /**
+     * Gap between neighbours with different parents, relative to the sibling
+     * gap (1); 1 spaces every neighbour evenly.
+     * @default 2
+     */
+    separation?: number;
+    /** A leaf's value; geometry does not depend on it. Omitted, every node's value is its leaf count. */
+    value?: (datum: T, index: number) => number;
+    /** Order siblings by descending value. @default false */
+    sort?: boolean;
+    /**
+     * A node's height above the leaves (a dendrogram's merge distance),
+     * placing it along the depth axis instead of its depth: the greatest
+     * distance at `y = 0`, 0 at `y = height`. A parent's missing or too-small
+     * distance is raised to its tallest child's.
+     */
+    distance?: (datum: T, index: number) => number;
+    /**
+     * Lay out for a radial tree, dividing neighbour gaps by depth. Pair with
+     * `width = 2π` and {@link radialTreePoint}.
+     * @default false
+     */
+    radial?: boolean;
+}
+/**
+ * One laid-out tree node: {@link HierarchyNodeInfo} plus its position.
+ *
+ * @category Math & helpers
+ */
+export interface TreeNode<T> extends HierarchyNodeInfo<T> {
+    /** Position along the breadth axis, in `[0, width]`. */
+    x: number;
+    /** Position along the depth axis: 0 for the root, up to `height`. */
+    y: number;
+    /** The leaf's value, or the sum of a parent's leaves (the leaf count without `value`); may be 0. */
+    value: number;
+    /** The node's height above the leaves: its raised `distance` when given, else its height in levels. */
+    distance: number;
+}
+/**
+ * How a parent-child link is drawn: `"curve"`, a cubic leaving and reaching
+ * along the depth axis; `"elbow"`, a right-angled dendrogram bracket.
+ *
+ * @category Math & helpers
+ */
+export type TreeLinkShape = "curve" | "elbow";
+/** @category Math */
+export interface TreeLinkOptions {
+    /** Points sampled along a `"curve"` link, ends included. @default 24 */
+    samples?: number;
+}
+/**
+ * A node-link tree layout: the tidy tree (`layout: "tidy"`) or the
+ * dendrogram (`"cluster"`). The outermost nodes keep half a gap from the
+ * edges, so a lone root sits at `width / 2`. Not the graph `treeLayout` in
+ * `@sophistry/core/geometry`.
+ *
+ * @returns Every node in pre-order, or `[]` when the box is empty.
+ * @throws {Error} If the tree contains a cycle.
+ * @category Math & helpers
+ */
+export declare function hierarchyTreeLayout<T>(root: T, options?: TreeLayoutOptions<T>): TreeNode<T>[];
+/**
+ * The polyline of one tree link from `parent` to `child`, in layout
+ * coordinates; drawn by arc length it grows out of the parent.
+ *
+ * @returns `samples` points along a curve, or two or three for an elbow.
+ * @category Math & helpers
+ */
+export declare function treeLink(parent: Point, child: Point, shape: TreeLinkShape, options?: TreeLinkOptions): Point[];
+/**
+ * A radial tree point in Cartesian coordinates, y up: `angle` in radians
+ * clockwise from 12 o'clock (a node's `x` laid out with `width = 2π`), and
+ * `radius` from `center` (a node's `y`).
+ *
+ * @category Math & helpers
+ */
+export declare function radialTreePoint(angle: number, radius: number, center?: Point): Point;
+/** @category Math */
+export interface RadialTreeLinkOptions extends TreeLinkOptions {
+    /** The tree's centre. Defaults to the origin. */
+    center?: Point;
+    /** Points per radian along an elbow's arc. @default 24 */
+    arcDensity?: number;
+}
+/**
+ * The Cartesian polyline of one radial tree link, from `parent` to `child`
+ * in layout coordinates (`x` angle, `y` radius). `"curve"` is the cubic in
+ * polar coordinates; `"elbow"` runs round the parent's circle, then out.
+ *
+ * @category Math & helpers
+ */
+export declare function radialTreeLink(parent: Point, child: Point, shape: TreeLinkShape, options?: RadialTreeLinkOptions): Point[];

package/dist/math/tricontour.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Contour lines, filled bands and flat pseudocolour over an unstructured
+ * triangulation (values at scattered points rather than on a grid). The
+ * mesh is the Delaunay triangulation or the caller's own triangles; over
+ * each triangle the field is linear. Level conventions match the grid
+ * versions: a count of line levels sits strictly inside the data's range, a
+ * count of band boundaries spans it inclusively.
+ */
+import type { Point } from "@sophistry/core/geometry";
+import type { ContourLine } from "./contour.js";
+import type { ContourBand } from "./contourf.js";
+/**
+ * Three indices into the point arrays, one triangle.
+ *
+ * @category Math & helpers
+ */
+export type TriangleIndices = readonly [number, number, number];
+/** @category Math */
+export interface TriangulationOptions {
+    /** The triangles, as index triples into the point arrays, either winding. Omitted, the points are Delaunay-triangulated. */
+    triangles?: readonly TriangleIndices[];
+}
+/**
+ * One face of a pseudocolour mesh.
+ *
+ * @category Math & helpers
+ */
+export interface TripcolorFace {
+    /** The triangle's corners, as indices into the point arrays, counter-clockwise. */
+    indices: [number, number, number];
+    /** The corners in data units, counter-clockwise. */
+    points: Point[];
+    /** The mean of the corners' values: the face's colour value. */
+    value: number;
+}
+/**
+ * The triangles a tri-chart draws: the caller's own, checked and turned
+ * counter-clockwise, or the Delaunay triangulation of the points. Triangles
+ * with a non-finite corner or no area are dropped.
+ *
+ * @returns Counter-clockwise index triples into `xs`/`ys`.
+ * @throws {RangeError} If an explicit triangle names a point that does not exist.
+ * @category Math & helpers
+ */
+export declare function triangulate(xs: readonly number[], ys: readonly number[], options?: TriangulationOptions): [number, number, number][];
+/**
+ * Iso-lines of a field sampled at scattered points, by marching triangles.
+ *
+ * @param zs - The value at each point; triangles touching a non-finite value are skipped.
+ * @param levels - Explicit levels, or a count of evenly spaced ones strictly inside the data's range.
+ * @returns Polylines tagged with their level, in level order.
+ * @throws {RangeError} If an explicit triangle names a point that does not exist.
+ * @category Math & helpers
+ */
+export declare function tricontourLines(xs: readonly number[], ys: readonly number[], zs: readonly number[], levels: readonly number[] | number, options?: TriangulationOptions): ContourLine[];
+/**
+ * Filled bands of a field sampled at scattered points: each triangle clipped
+ * to every band between consecutive boundaries.
+ *
+ * @param zs - The value at each point; triangles touching a non-finite value are skipped.
+ * @param levels - Explicit boundaries, or a count spanning the data (`N` make `N - 1` bands).
+ * @returns One {@link ContourBand} per band, its polygons counter-clockwise, one per contributing triangle.
+ * @throws {RangeError} If an explicit triangle names a point that does not exist.
+ * @category Math & helpers
+ */
+export declare function tricontourBands(xs: readonly number[], ys: readonly number[], zs: readonly number[], levels: readonly number[] | number, options?: TriangulationOptions): ContourBand[];
+/**
+ * Flat-shaded pseudocolour faces over scattered points: one per triangle,
+ * valued at the mean of its corners.
+ *
+ * @param zs - The value at each point; triangles touching a non-finite value are skipped.
+ * @returns One face per drawable triangle, in triangulation order.
+ * @throws {RangeError} If an explicit triangle names a point that does not exist.
+ * @category Math & helpers
+ */
+export declare function tripcolorFaces(xs: readonly number[], ys: readonly number[], zs: readonly number[], options?: TriangulationOptions): TripcolorFace[];

package/dist/math/violin.d.ts

@@ -0,0 +1,99 @@
+/** Violin geometry: a mirrored Gaussian kernel-density silhouette per group. */
+import type { Point } from "@sophistry/core/geometry";
+/** @category Math */
+export interface KdePoint {
+    x: number;
+    density: number;
+}
+/** @category Math */
+export interface GaussianKdeOptions {
+    /** Kernel bandwidth. Defaults to Silverman's rule of thumb. */
+    bandwidth?: number;
+    /** How many evenly spaced points to sample the density at. @default 80 */
+    samples?: number;
+    /**
+     * The span to sample over. Defaults to the finite extent of `values`, padded by `3 * bandwidth`
+     * each side.
+     */
+    domain?: [number, number];
+}
+/** @category Math */
+export interface ViolinRingOptions {
+    /** Kernel bandwidth. Defaults to Silverman's rule of thumb. */
+    bandwidth?: number;
+    /** How many evenly spaced points to sample the density at. @default 80 */
+    samples?: number;
+    /** How far the silhouette reaches from `center` at its widest. @default 0.4 */
+    scale?: number;
+}
+/**
+ * `GaussianKdeOptions.samples`'s default.
+ *
+ * @category Math & helpers
+ */
+export declare const DEFAULT_SAMPLES = 80;
+/**
+ * `ViolinRingOptions.scale`'s default.
+ *
+ * @category Math & helpers
+ */
+export declare const DEFAULT_VIOLIN_SCALE = 0.4;
+/**
+ * Gaussian kernel density estimate of `values`, sampled at `samples` evenly
+ * spaced points across `domain`.
+ *
+ * @param values - Raw samples; non-finite entries are dropped.
+ * @returns `{ x, density }` points ascending in `x`; `[]` for empty input.
+ * @category Math & helpers
+ */
+export declare function gaussianKde(values: readonly number[], options?: GaussianKdeOptions): KdePoint[];
+/**
+ * One violin's outline: a mirrored KDE silhouette as one open ring, upright
+ * (y the data value, x around `center`). Each violin is normalized to its
+ * own max density, so every one reaches `scale` at its widest: shapes
+ * compare across groups, absolute densities don't.
+ *
+ * @param center - The slot centre the violin mirrors around, in x data units.
+ * @returns The ring in data coordinates; `[]` with fewer than 2 finite values.
+ * @category Math & helpers
+ */
+export declare function violinRing(values: readonly number[], center: number, options?: ViolinRingOptions): Point[];
+/**
+ * One violin's half-silhouette before placement: the sampled heights
+ * (ascending) and the width at each as a share of the widest. Keyed
+ * transitions blend these ({@link blendViolinProfiles}) so every frame is a
+ * valid violin.
+ *
+ * @category Math & helpers
+ */
+export interface ViolinProfile {
+    /** Where the density was sampled, in data units, ascending. */
+    readonly ys: readonly number[];
+    /** The width at each of `ys`, as a share of the widest (0..1). */
+    readonly widths: readonly number[];
+}
+/**
+ * The profile {@link violinRing} mirrors: the KDE of `values` divided by its
+ * largest density.
+ *
+ * @returns The profile, or null with fewer than 2 finite values or no usable density.
+ * @category Math & helpers
+ */
+export declare function violinProfile(values: readonly number[], options?: Pick<ViolinRingOptions, "bandwidth" | "samples">): ViolinProfile | null;
+/**
+ * A profile mirrored about `center` and scaled to reach `scale` at its
+ * widest: {@link violinRing}'s ring, point for point.
+ *
+ * @category Math & helpers
+ */
+export declare function violinProfileRing(profile: ViolinProfile, center: number, scale: number): Point[];
+/**
+ * Two violin profiles blended at `t` on the union of their heights (each 0
+ * beyond its own), so every frame is a valid outline. A missing (null) end
+ * is a violin of zero width, so a violin grows out of or shrinks into its
+ * centre line.
+ *
+ * @returns The blended profile; null only when both ends are.
+ * @category Math & helpers
+ */
+export declare function blendViolinProfiles(a: ViolinProfile | null, b: ViolinProfile | null, t: number): ViolinProfile | null;

package/dist/math/waffle.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Waffle chart math: share out a fixed number of unit cells between
+ * categories so the counts sum exactly, and place each cell on the grid.
+ * `<Waffle>` is the caller that draws them.
+ */
+/**
+ * Rounds each value's share of `total` to whole numbers summing to exactly
+ * `total` (largest remainder): shares round down, and leftover units go to
+ * the largest fractional parts, ties to the earlier entry. Negative and
+ * non-finite values count as 0.
+ *
+ * @param total - The whole to share out; rounded down to an integer.
+ * @returns One non-negative integer count per value, summing to `total` (all 0 when nothing is positive).
+ * @category Math & helpers
+ */
+export declare function largestRemainder(values: readonly number[], total: number): number[];
+/** @category Math */
+export interface WaffleOptions {
+    /** Rows of cells. @default 10 */
+    rows?: number;
+    /** Columns of cells. @default 10 */
+    columns?: number;
+}
+/**
+ * One unit cell of a waffle chart.
+ *
+ * @category Math & helpers
+ */
+export interface WaffleCell {
+    /** Place in fill order, 0-based: the bottom-left cell is 0. */
+    rank: number;
+    /** Row, counted up from the bottom (0 is the bottom row). */
+    row: number;
+    /** Column, counted from the left. */
+    column: number;
+    /** Index of the value this cell counts towards, or -1 for an empty cell. */
+    category: number;
+}
+/**
+ * Every cell of a `rows × columns` waffle in fill order, assigned to
+ * categories by {@link largestRemainder}. Cells fill row by row from the
+ * bottom-left, each category one contiguous run in data order.
+ *
+ * @param values - One value per category; negative and non-finite count as 0.
+ * @returns `rows × columns` cells by `rank`; all empty (`category: -1`) when no value is positive.
+ * @category Math & helpers
+ */
+export declare function waffleCells(values: readonly number[], options?: WaffleOptions): WaffleCell[];

package/dist/math/waterfall.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Waterfall steps: a running total broken into the changes that built it.
+ */
+/**
+ * One bar of a waterfall: where it starts and ends in data units, and what
+ * kind of step it is.
+ *
+ * @category Math & helpers
+ */
+export interface WaterfallStep {
+    /** The running total before this step (0 for a total bar). */
+    base: number;
+    /** The running total after this step. */
+    end: number;
+    /** The change itself, `end - base`. */
+    delta: number;
+    /** `"up"` or `"down"` for a change, `"total"` for a bar standing on zero. */
+    kind: "up" | "down" | "total";
+}
+/**
+ * Turns changes into floating bars, each starting where the running total
+ * stood. An entry flagged as a total is drawn from zero to the running total
+ * (its own value ignored). Non-finite changes count as 0.
+ *
+ * @param totals - Which entries are subtotal/total bars. Defaults to none.
+ * @category Math & helpers
+ */
+export declare function waterfallSteps(deltas: readonly number[], totals?: readonly boolean[]): WaterfallStep[];