@pond-ts/charts 0.57.0 → 0.58.0

package/dist/decimate.d.ts

@@ -45,7 +45,7 @@
  * `xScale` and breaks its subpath on `NaN`) — decimation is a pre-pass that
  * shrinks the point count, not a second renderer.
  */
-import type { ChartSeries, BandSeries, OhlcSeries, BoxSeries, BarSeries } from './data.js';
+import type { ChartSeries, BandSeries, OhlcSeries, BoxSeries, BarSeries, StackedBarSeries } from './data.js';
 import type { Scale } from './line.js';
 /**
  * A line layer's M4-decimation control (`<LineChart decimate>`). **Default
@@ -305,6 +305,83 @@ export interface BarColumnEnvelope {
  * `resolveBarBaseline`), so the union is honest about the zero line.
  */
 export declare function decimateBars(cs: BarSeries, xScale: Scale, ctx: CanvasRenderingContext2D, baseline: number, k?: number, visibleCount?: number): BarColumnEnvelope | null;
+/**
+ * Decimate a heat-map grid to **one cell per pixel column per row**, each the
+ * **mean** of the source cells that fall in it ([PND-HEATMAP]).
+ *
+ * **Why the mean, and why a heat map can decimate where a coloured bar cannot.**
+ * {@link decimateBars} deliberately gives up when `binFills` is set: its
+ * reduction is a *geometric* union (`[min, max]` per column), and one rect
+ * spanning many differently-coloured bars has no honest colour. A heat map is
+ * not in that bind, because its reduction is not geometric. Cells do not form a
+ * silhouette — they **composite**: each one covers its own patch of the column,
+ * so what the eye receives from a column holding N cells is their area-weighted
+ * average. Taking the mean of the *values* and letting the existing ramp colour
+ * it is therefore not a statistical choice imposed on the reader; it is what the
+ * full-resolution draw already resolves to at this size. Banding the mean also
+ * keeps the result **inside the ramp**, so it stays a colour the legend defines
+ * (averaging the colours instead would invent off-ramp shades, and would need
+ * linear-light care to avoid the usual downsampling darkening).
+ *
+ * What this **replaces** is worse than it: undecimated, sub-pixel cells are
+ * widened to `minWidth` about their midpoints, so they overlap and later draws
+ * overpaint earlier ones. The column already showed one cell out of N — chosen
+ * by loop order. The mean is both cheaper and more honest than that.
+ *
+ * **What it loses:** a lone extreme cell among N averages away, exactly as it
+ * would in any image downsample. A reader hunting rare spikes should bin the
+ * *series* coarsely with `aggregate` and a reducer that says so (`max`), which
+ * is the tool that makes the claim explicit and is unaffected by this.
+ *
+ * Gates on the **visible** cell columns (`visibleCount`), like the bar path.
+ * Returns `null` when decimation doesn't apply — below the density threshold, a
+ * domainless or non-invertible scale, or no canvas width — and the caller then
+ * draws every visible cell. The result carries **no `marks`**: a pixel column
+ * aggregates many source bins and so has no stable per-bin identity, which is
+ * also why the caller suppresses the live-cell outline while decimated and
+ * keeps hit-testing against the source grid ({@link decimateBars} does the same).
+ */
+export declare function decimateHeat(ss: StackedBarSeries, binScale: Scale, ctx: CanvasRenderingContext2D, k?: number, vStart?: number, vEnd?: number, 
+/**
+ * The bin axis' extent, when it is **not** the x axis. A horizontal heat map
+ * puts its bins on y, where the shared helpers do not apply: `scaleRangeWidth`
+ * reads `range()[last]`, which is `0` for the usual inverted y range, and
+ * `deviceBucketCount` reads the canvas' *width*. Omitted ⇒ the x-axis
+ * defaults, which is every other caller.
+ */
+axis?: {
+    deviceCount: number;
+    spanCss: number;
+}): StackedBarSeries | null;
+/**
+ * The **y half** of heat-map decimation: collapse runs of `stride` rows into one,
+ * each the mean of the rows it covers ([PND-HEATMAP]).
+ *
+ * The x half ({@link decimateHeat}) is not enough on its own, and a gene
+ * expression matrix is the case that proves it: 10,000 genes x 8 samples is
+ * **16.7 rows per pixel row** and only 8 bins, so the column decimator declines
+ * and every one of the 80,000 cells is drawn to show ~4,800 distinguishable
+ * ones. Whichever axis is oversampled, the argument is the same — rows sharing a
+ * pixel row composite, so what the eye receives is their mean.
+ *
+ * **A fixed integer stride, not a pixel-edge walk.** Source rows are *unit
+ * slots* (`[g, g+1]`, which is what lets `binCategories` label them), so they
+ * are already uniform in row-index space; a run of `stride` of them is exactly
+ * `[r·stride, (r+1)·stride]`. That keeps the y coordinate space **unchanged** —
+ * which is load-bearing, because `<YAxis>` scales over `[0, G]` and explicit
+ * `{ at, label }` ticks are in those units. Rewriting the row bands the way the
+ * x half rewrites bin spans would silently slide every axis label.
+ *
+ * Returns `null` below the gate (`stride < k` — fewer than `k` rows per device
+ * row, where drawing every row is honest and the reduction would not pay), so
+ * the caller draws the source rows. The final run is short when `rows` is not a
+ * multiple of `stride`; it averages what is there.
+ */
+export declare function decimateHeatRows(values: Float64Array, bins: number, rows: number, deviceRows: number, k?: number): {
+    values: Float64Array;
+    rows: number;
+    stride: number;
+} | null;
 /**
  * Decimate a **uniform** scatter to one representative mark per occupied
  * **pixel cell** ([PND-MARKDEC] scatter half) — the marks analog of

package/dist/decimate.js

@@ -607,6 +607,163 @@ export function decimateBars(cs, xScale, ctx, baseline, k = 2, visibleCount = cs
     }
     return { begin, end, lo, hi, length: W };
 }
+/**
+ * Decimate a heat-map grid to **one cell per pixel column per row**, each the
+ * **mean** of the source cells that fall in it ([PND-HEATMAP]).
+ *
+ * **Why the mean, and why a heat map can decimate where a coloured bar cannot.**
+ * {@link decimateBars} deliberately gives up when `binFills` is set: its
+ * reduction is a *geometric* union (`[min, max]` per column), and one rect
+ * spanning many differently-coloured bars has no honest colour. A heat map is
+ * not in that bind, because its reduction is not geometric. Cells do not form a
+ * silhouette — they **composite**: each one covers its own patch of the column,
+ * so what the eye receives from a column holding N cells is their area-weighted
+ * average. Taking the mean of the *values* and letting the existing ramp colour
+ * it is therefore not a statistical choice imposed on the reader; it is what the
+ * full-resolution draw already resolves to at this size. Banding the mean also
+ * keeps the result **inside the ramp**, so it stays a colour the legend defines
+ * (averaging the colours instead would invent off-ramp shades, and would need
+ * linear-light care to avoid the usual downsampling darkening).
+ *
+ * What this **replaces** is worse than it: undecimated, sub-pixel cells are
+ * widened to `minWidth` about their midpoints, so they overlap and later draws
+ * overpaint earlier ones. The column already showed one cell out of N — chosen
+ * by loop order. The mean is both cheaper and more honest than that.
+ *
+ * **What it loses:** a lone extreme cell among N averages away, exactly as it
+ * would in any image downsample. A reader hunting rare spikes should bin the
+ * *series* coarsely with `aggregate` and a reducer that says so (`max`), which
+ * is the tool that makes the claim explicit and is unaffected by this.
+ *
+ * Gates on the **visible** cell columns (`visibleCount`), like the bar path.
+ * Returns `null` when decimation doesn't apply — below the density threshold, a
+ * domainless or non-invertible scale, or no canvas width — and the caller then
+ * draws every visible cell. The result carries **no `marks`**: a pixel column
+ * aggregates many source bins and so has no stable per-bin identity, which is
+ * also why the caller suppresses the live-cell outline while decimated and
+ * keeps hit-testing against the source grid ({@link decimateBars} does the same).
+ */
+export function decimateHeat(ss, binScale, ctx, k = 2, vStart = 0, vEnd = ss.length, 
+/**
+ * The bin axis' extent, when it is **not** the x axis. A horizontal heat map
+ * puts its bins on y, where the shared helpers do not apply: `scaleRangeWidth`
+ * reads `range()[last]`, which is `0` for the usual inverted y range, and
+ * `deviceBucketCount` reads the canvas' *width*. Omitted ⇒ the x-axis
+ * defaults, which is every other caller.
+ */
+axis) {
+    const visibleCount = vEnd - vStart;
+    if (axis === undefined
+        ? !shouldDecimateCount(visibleCount, ctx, k)
+        : visibleCount < k * axis.deviceCount)
+        return null;
+    const dom = scaleDomain(binScale);
+    if (dom === null || dom[1] <= dom[0])
+        return null;
+    const invert = scaleInvert(binScale);
+    const plotWidthCss = axis?.spanCss ?? scaleRangeWidth(binScale);
+    if (invert === null || plotWidthCss === null || plotWidthCss <= 0)
+        return null;
+    const W = axis?.deviceCount ?? deviceBucketCount(ctx);
+    if (W <= 0)
+        return null;
+    const raw = pixelEdges(invert, plotWidthCss, W);
+    // `pixelEdges` walks pixels ascending, so on an **inverted** axis — the usual
+    // y range `[h, 0]`, which a horizontal heat map's bin axis uses — the key-space
+    // edges come back descending. The sweep below and the emitted `begin`/`end`
+    // both want ascending key order, and the draw maps back through the scale
+    // anyway, so normalize here rather than special-casing two directions.
+    const edges = raw[0] <= raw[W] ? raw : raw.slice().reverse();
+    const G = ss.groups.length;
+    const sum = new Float64Array(W * G);
+    const count = new Float64Array(W * G);
+    // `ss.begin` is ascending and so are `edges`, so the column advances
+    // monotonically — one O(V + W) sweep rather than a search per bin.
+    let col = 0;
+    for (let b = vStart; b < vEnd; b += 1) {
+        const key = ss.begin[b];
+        while (col < W - 1 && key >= edges[col + 1])
+            col += 1;
+        const src = b * G;
+        const dst = col * G;
+        for (let g = 0; g < G; g += 1) {
+            const v = ss.values[src + g];
+            // A hole contributes nothing rather than dragging the mean to zero; a
+            // column of nothing but holes stays a hole.
+            if (!Number.isFinite(v))
+                continue;
+            sum[dst + g] += v;
+            count[dst + g] += 1;
+        }
+    }
+    const begin = new Float64Array(W);
+    const end = new Float64Array(W);
+    const values = new Float64Array(W * G);
+    for (let c = 0; c < W; c += 1) {
+        begin[c] = edges[c];
+        end[c] = edges[c + 1];
+        const dst = c * G;
+        for (let g = 0; g < G; g += 1) {
+            const n = count[dst + g];
+            values[dst + g] = n > 0 ? sum[dst + g] / n : NaN;
+        }
+    }
+    return { begin, end, values, groups: ss.groups, length: W };
+}
+/**
+ * The **y half** of heat-map decimation: collapse runs of `stride` rows into one,
+ * each the mean of the rows it covers ([PND-HEATMAP]).
+ *
+ * The x half ({@link decimateHeat}) is not enough on its own, and a gene
+ * expression matrix is the case that proves it: 10,000 genes x 8 samples is
+ * **16.7 rows per pixel row** and only 8 bins, so the column decimator declines
+ * and every one of the 80,000 cells is drawn to show ~4,800 distinguishable
+ * ones. Whichever axis is oversampled, the argument is the same — rows sharing a
+ * pixel row composite, so what the eye receives is their mean.
+ *
+ * **A fixed integer stride, not a pixel-edge walk.** Source rows are *unit
+ * slots* (`[g, g+1]`, which is what lets `binCategories` label them), so they
+ * are already uniform in row-index space; a run of `stride` of them is exactly
+ * `[r·stride, (r+1)·stride]`. That keeps the y coordinate space **unchanged** —
+ * which is load-bearing, because `<YAxis>` scales over `[0, G]` and explicit
+ * `{ at, label }` ticks are in those units. Rewriting the row bands the way the
+ * x half rewrites bin spans would silently slide every axis label.
+ *
+ * Returns `null` below the gate (`stride < k` — fewer than `k` rows per device
+ * row, where drawing every row is honest and the reduction would not pay), so
+ * the caller draws the source rows. The final run is short when `rows` is not a
+ * multiple of `stride`; it averages what is there.
+ */
+export function decimateHeatRows(values, bins, rows, deviceRows, k = 2) {
+    if (!(deviceRows > 0) || !(rows > 0))
+        return null;
+    const stride = Math.ceil(rows / deviceRows);
+    if (stride < k)
+        return null;
+    const out = Math.ceil(rows / stride);
+    const reduced = new Float64Array(bins * out);
+    for (let b = 0; b < bins; b += 1) {
+        const src = b * rows;
+        const dst = b * out;
+        for (let r = 0; r < out; r += 1) {
+            const g0 = r * stride;
+            const g1 = Math.min(g0 + stride, rows);
+            let sum = 0;
+            let n = 0;
+            for (let g = g0; g < g1; g += 1) {
+                const v = values[src + g];
+                // A hole contributes nothing rather than pulling the mean toward zero;
+                // a run of nothing but holes stays a hole.
+                if (!Number.isFinite(v))
+                    continue;
+                sum += v;
+                n += 1;
+            }
+            reduced[dst + r] = n > 0 ? sum / n : NaN;
+        }
+    }
+    return { values: reduced, rows: out, stride };
+}
 /**
  * Decimate a **uniform** scatter to one representative mark per occupied
  * **pixel cell** ([PND-MARKDEC] scatter half) — the marks analog of

package/dist/heat.d.ts

@@ -0,0 +1,163 @@
+import type { StackedBarSeries } from './data.js';
+import type { Scale } from './line.js';
+import type { Orientation, StackMark } from './bars.js';
+import type { SpanSelection } from './context.js';
+import type { HeatStates } from './theme.js';
+import { type DecimateOption } from './decimate.js';
+/**
+ * Heat-map geometry: a grid of cells, each filled by the colour its **value**
+ * maps to. Bins run along x, the series' **columns** run down y, and colour
+ * carries the aggregate.
+ *
+ * **Why this reuses {@link StackedBarSeries}.** That type is already exactly a
+ * heat map's data: `[begin, end]` spans per bin, a named second dimension in
+ * `groups`, and a row-major `length × groups.length` grid of `values`. So a heat
+ * map needs **no reader of its own** — `stacksFromColumns(series, columns)`
+ * produces all four shapes pond can express today:
+ *
+ * | source | columns | x axis |
+ * | --- | --- | --- |
+ * | `TimeSeries` | one | time intervals — a stripe |
+ * | `TimeSeries` | many | time intervals — a grid |
+ * | `ValueSeries` | one | value intervals — a bin stripe |
+ * | `ValueSeries` | many | value intervals — a grid |
+ *
+ * The stripe is just `groups.length === 1`, so there is one draw path, not two.
+ *
+ * **What that buys on x.** Because the spans are the ordinary bin spans, the
+ * whole of pond's binning machinery applies unchanged — `aggregate` over a
+ * trading calendar with sessions, `Sequence.calendar` day/week/month buckets,
+ * `byColumn` value bands. The heat map inherits all of it by not having an
+ * opinion.
+ *
+ * **What it costs on y.** The y dimension **must be columns**. A month-of-year
+ * grid means building a column per month; a per-city grid means a column per
+ * city (`pivotByGroup`'s long→wide output, or `partitionBy` reshaped). That is
+ * a real constraint, and a deliberate one: it keeps the second dimension in the
+ * data model, where pond's own reshaping operators can produce it, instead of
+ * inventing a chart-level pivot.
+ */
+/** Cell styling. Colour is data and comes from the caller's ramp, so this is
+ *  only the geometry and the live-cell treatment. */
+/**
+ * How value maps onto the ramp's bands.
+ *
+ * `'linear'` splits the domain into equal-width bands. `'log'` splits it into
+ * equal-*ratio* bands, which is what a quantity spanning orders of magnitude
+ * needs: US measles incidence runs from ~2,900 per 100k before the vaccine to
+ * under 1 after it, and linear banding over eight colours puts everything below
+ * ~360 in one band — the whole post-1965 record, which is the half the chart
+ * exists to show.
+ */
+export type HeatScale = 'linear' | 'log';
+/** How a cell with no value is drawn. */
+export type HeatNoData = 'blank' | 'hatch';
+export interface HeatStyle {
+    /** Alpha for a resting cell. A live cell pops to 1, as bars do. */
+    readonly opacity: number;
+    /** Outline colour for the selected cell. */
+    readonly highlight: string;
+    /** Selected-cell stroke width in px. */
+    readonly outlineWidth: number;
+    /** Px inset around each cell, in both axes. `0` tiles them flush. */
+    readonly gap: number;
+    /** Px floor on a cell's width, so a thin bin stays visible. */
+    readonly minWidth: number;
+    /** Stroke for the `'hatch'` no-data fill — the theme's grid colour, so it
+     *  reads as chart furniture rather than as a value. */
+    readonly gridColor: string;
+    /**
+     * The **interaction states** ({@link HeatStates}), from `theme.heat`. Unset
+     * ⇒ the pre-states treatment exactly: a live cell gets one outline of its
+     * own in {@link highlight}, `outlineWidth` for hover and twice that for
+     * selection, and nothing recedes.
+     */
+    readonly states?: HeatStates;
+}
+/**
+ * Map a value onto a **banded** ramp: `colors` split `[lo, hi]` into equal
+ * steps and a value takes the colour of the band it falls in.
+ *
+ * Banded rather than interpolated on purpose. It is what the climate-stripes
+ * card does today (its `anomalyStep` buckets into the ramp's length, which this
+ * replaces), it is the conventional reading for stripes and calendar heat maps,
+ * and a banded scale is honest about resolution in a way a smooth gradient is
+ * not — you can count the steps and read a cell against a legend. With nine or
+ * more stops it is visually indistinguishable from a gradient anyway.
+ *
+ * A non-finite value, or an empty ramp, yields `undefined` — the caller decides
+ * whether that is a skipped cell or a fallback fill.
+ */
+export declare function bandedColor(value: number, colors: readonly string[], lo: number, hi: number, scale?: HeatScale): string | undefined;
+/**
+ * The `[min, max]` of the finite values across **every** cell — the colour
+ * domain when the caller does not pin one. `null` when nothing is finite.
+ *
+ * Deliberately **not** widened to include `0`, unlike `barExtent`: a bar's
+ * height is measured from a baseline so zero must be in the domain, but a
+ * cell's colour is measured against the data's own range. Widening would waste
+ * half the ramp on an all-positive grid.
+ *
+ * Note this spans the **whole grid**, not each row — every row is read against
+ * one scale, which is what makes rows comparable to each other.
+ */
+export declare function heatValueExtent(ss: StackedBarSeries): [number, number] | null;
+/**
+ * The pixel rect of the cell at bin `b`, row `g` — `[x0, x1, yTop, yBottom]`,
+ * ascending on both axes — or `null` for a gap (non-finite value), which draws
+ * nothing and owns no hit region so a hole in the record reads as a hole.
+ *
+ * x comes from the bin's own span via {@link barSpanPx}, shared with bars so
+ * cells and bars tile identically. y is the row's **unit slot** `[g, g+1]`
+ * through the y scale, which is why the layer reports `yExtent` as `[0, G]` and
+ * labels rows via `binCategories` at each slot centre.
+ *
+ * **Row order follows the y scale**, so with the usual inverted pixel range row
+ * `0` sits at the *bottom*. That matches the existing band-axis convention
+ * (a horizontal histogram's first bin is its lowest), and a caller who wants
+ * the first column at the top reverses the column list.
+ */
+export declare function cellRect(ss: StackedBarSeries, b: number, g: number, xScale: Scale, yScale: Scale, gapPx: number, minWidthPx: number, orientation?: Orientation): [x0: number, x1: number, yTop: number, yBottom: number] | null;
+/**
+ * Fill one rectangle per cell, coloured by `colorAt(b, g)`. A gap is skipped.
+ *
+ * A live cell keeps its **own** colour. The colour is never swapped for a
+ * highlight, because that colour *is* the datum — replacing it would erase the
+ * reading the chart exists to give.
+ *
+ * That rules out the bar layers' usual affordance too. A bar says "live" by
+ * popping from `opacity` to 1, which on a heat map is both invisible (a ramp is
+ * normally drawn at full opacity already) and, where it isn't, actively
+ * misleading — dimming a cell shifts where the reader places it on the colour
+ * scale. So a live cell is marked by an **outline** instead: `outlineWidth` for
+ * hover, twice that for selection, both in `style.highlight`. The alpha pop is
+ * kept as well, so a theme that does draw cells translucent still behaves like
+ * its bars.
+ *
+ * Hover and selection share one colour deliberately — whether they should
+ * diverge is the open question in #577, and this layer should not pre-empt it.
+ *
+ * Both `selection` and `hovered` are **sets**: `ContainerFrame.selected` has
+ * been one since [PND-MULTISEL] and `hovered` since RFC A4.3, so **every** cell
+ * a member names lights — a pinned group of cells, or a drag-sweep hovering
+ * several at once, all read back rather than only the set's first member. A cell
+ * in **both** sets reads as selected (selected outranks hovered, the precedence
+ * `drawBars` / `drawStacks` / `drawBox` share) and takes one outline, never two.
+ *
+ * O(visible × G) after viewport culling on the bin axis, plus O(|set|) per
+ * visible **bin** (not per cell — see {@link binLabelsInto}) and only when a set
+ * names this layer at all, so a resting draw costs exactly what it did.
+ */
+export declare function drawHeat(ctx: CanvasRenderingContext2D, ss: StackedBarSeries, xScale: Scale, yScale: Scale, style: HeatStyle, colorOf: (value: number) => string | undefined, seriesId: string | undefined, selection?: readonly StackMark[], hovered?: readonly StackMark[], decimate?: DecimateOption, orientation?: Orientation, noData?: HeatNoData, spans?: readonly SpanSelection[]): void;
+/**
+ * Hit-test plot-pixel `(px, py)` against the grid — the first cell whose rect
+ * contains the point, or `null`. Returns `[bin, row, begin, rowName, value]`.
+ *
+ * The **value** is the whole point of the layer. A constant-height bar carries
+ * none, which is why the climate-stripes card looks its number up out-of-band;
+ * a cell answers directly, and so can the cursor.
+ *
+ * O(N × G), as `stackAt` is: bin and row counts are view-scale, clicks are rare.
+ */
+export declare function heatAt(ss: StackedBarSeries, px: number, py: number, xScale: Scale, yScale: Scale, gapPx: number, minWidthPx: number, orientation?: Orientation): [bin: number, row: number, begin: number, name: string, value: number] | null;
+//# sourceMappingURL=heat.d.ts.map