insomni-plot 0.1.0-alpha.0

package/src/stats/index.ts

@@ -0,0 +1,740 @@
+export {
+  confidenceBand,
+  linearFit,
+  loessFit,
+  polyFit,
+  type ConfidenceBandOptions,
+  type ConfidenceBandPoint,
+  type LoessOptions,
+  type RegressionFit,
+} from "./regression.ts";
+
+export {
+  rollingWindow,
+  type RollingAxis,
+  type RollingPoint,
+  type RollingStatistic,
+  type RollingStatisticKind,
+  type RollingWindow,
+  type RollingWindowOptions,
+} from "./rolling-window.ts";
+
+// ---------------------------------------------------------------------------
+// Distribution statistics
+// ---------------------------------------------------------------------------
+// Pure helpers for box-plot / violin geoms. No DOM or GPU deps. Exported as a
+// public surface (`insomni-plot/core`) so users can compute stats once and
+// pass results into a custom mark, or just sanity-check geom output.
+
+export type QuantileMethod = "type-7" | "type-1";
+
+/**
+ * Quantile of an already-sorted ascending numeric array.
+ *
+ * - `"type-7"` (default): R's default — linear interpolation between order
+ *   stats with `h = (n - 1) * p`. The quantile method most users expect.
+ * - `"type-1"`: inverse-of-empirical-CDF (step function). No interpolation.
+ *
+ * Returns `NaN` for empty input. Clamps `p` to `[0, 1]`.
+ */
+export function quantile(
+  sorted: readonly number[],
+  p: number,
+  method: QuantileMethod = "type-7",
+): number {
+  const n = sorted.length;
+  if (n === 0) return Number.NaN;
+  if (n === 1) return sorted[0]!;
+  const q = p <= 0 ? 0 : p >= 1 ? 1 : p;
+
+  if (method === "type-1") {
+    const h = q * n;
+    const idx = Math.min(n - 1, Math.max(0, Math.ceil(h) - 1));
+    return sorted[idx]!;
+  }
+
+  // Type-7: linear interpolation
+  const h = (n - 1) * q;
+  const lo = Math.floor(h);
+  const hi = Math.ceil(h);
+  if (lo === hi) return sorted[lo]!;
+  const frac = h - lo;
+  return sorted[lo]! * (1 - frac) + sorted[hi]! * frac;
+}
+
+// ---------------------------------------------------------------------------
+// Box stats
+// ---------------------------------------------------------------------------
+
+export type WhiskerRule = number | "minmax";
+
+export interface BoxStats {
+  /** Sample size (after filtering non-finite). */
+  n: number;
+  /** Smallest value in the sample. */
+  min: number;
+  /** Lower whisker endpoint (clamped to data range). */
+  lowerWhisker: number;
+  q1: number;
+  median: number;
+  q3: number;
+  /** Upper whisker endpoint (clamped to data range). */
+  upperWhisker: number;
+  /** Largest value in the sample. */
+  max: number;
+  /** Q3 − Q1. */
+  iqr: number;
+  /** Values strictly outside the whiskers. Order preserves input order. */
+  outliers: number[];
+  /** Mean of the sample. Useful as an annotation; not used for box geometry. */
+  mean: number;
+}
+
+export interface BoxStatsOptions {
+  /**
+   * Whisker rule.
+   *
+   * - A number `k` (default `1.5`) — Tukey-style: whiskers extend to the most
+   *   extreme value within `k * IQR` of Q1/Q3. Anything beyond is an outlier.
+   * - `"minmax"` — whiskers extend to the data min/max; no outliers.
+   */
+  whisker?: WhiskerRule;
+  quantile?: QuantileMethod;
+}
+
+/**
+ * Compute Tukey-style box statistics. Filters non-finite inputs.
+ *
+ * Returns `null` for empty input — caller decides how to render `n=0`.
+ * For `n=1`, every quartile equals the single value and `outliers` is empty.
+ */
+export function boxStats(
+  values: readonly number[],
+  options: BoxStatsOptions = {},
+): BoxStats | null {
+  const finite: number[] = [];
+  for (const v of values) {
+    if (Number.isFinite(v)) finite.push(v);
+  }
+  if (finite.length === 0) return null;
+
+  const sorted = finite.slice().sort((a, b) => a - b);
+  const n = sorted.length;
+  const method = options.quantile ?? "type-7";
+  const q1 = quantile(sorted, 0.25, method);
+  const median = quantile(sorted, 0.5, method);
+  const q3 = quantile(sorted, 0.75, method);
+  const iqr = q3 - q1;
+  const min = sorted[0]!;
+  const max = sorted[n - 1]!;
+
+  const rule = options.whisker ?? 1.5;
+  let lowerWhisker: number;
+  let upperWhisker: number;
+  let outliers: number[] = [];
+
+  if (rule === "minmax") {
+    lowerWhisker = min;
+    upperWhisker = max;
+  } else {
+    const k = rule;
+    const lowerFence = q1 - k * iqr;
+    const upperFence = q3 + k * iqr;
+    lowerWhisker = min;
+    upperWhisker = max;
+    for (const v of sorted) {
+      if (v >= lowerFence) {
+        lowerWhisker = v;
+        break;
+      }
+    }
+    for (let i = sorted.length - 1; i >= 0; i--) {
+      const v = sorted[i]!;
+      if (v <= upperFence) {
+        upperWhisker = v;
+        break;
+      }
+    }
+    // Preserve original (input) order so e.g. labels can recover the index.
+    for (const v of finite) {
+      if (v < lowerFence || v > upperFence) outliers.push(v);
+    }
+  }
+
+  let sum = 0;
+  for (const v of finite) sum += v;
+
+  return {
+    n,
+    min,
+    lowerWhisker,
+    q1,
+    median,
+    q3,
+    upperWhisker,
+    max,
+    iqr,
+    outliers,
+    mean: sum / n,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Kernel density estimation
+// ---------------------------------------------------------------------------
+
+export type KdeKernel = "gaussian" | "epanechnikov";
+export type KdeBandwidth = number | "silverman" | "scott";
+
+export interface KdeOptions {
+  /** Number of evaluation points. Default `64`, capped to `512`. */
+  gridSize?: number;
+  /**
+   * Either a positive number (fixed bandwidth in data units) or a rule:
+   * - `"silverman"` (default) — `1.06 · scale · n^(-1/5)` with the robust
+   *   scale `min(σ, IQR/1.34)`. Less sensitive to heavy tails / skew.
+   * - `"scott"` — `1.06 · σ · n^(-1/5)` using the plain standard deviation
+   *   (no IQR robustification). Wider on skewed/heavy-tailed samples.
+   */
+  bandwidth?: KdeBandwidth;
+  kernel?: KdeKernel;
+  /**
+   * Evaluate over `[min, max]` of the sample (`true`, default) or pad outward
+   * by ~3 bandwidths so density tails reach near-zero (`false`).
+   */
+  trim?: boolean;
+  /** Override the evaluation domain. Bypasses `trim`. */
+  domain?: readonly [number, number];
+}
+
+export interface KdeResult {
+  /** Evaluation grid (length `gridSize`). */
+  x: number[];
+  /** Density at each grid point (length `gridSize`). */
+  y: number[];
+  /** Resolved bandwidth in data units. */
+  bandwidth: number;
+}
+
+const SQRT_2PI = Math.sqrt(2 * Math.PI);
+
+function stddev(values: readonly number[]): number {
+  const n = values.length;
+  if (n < 2) return 0;
+  let sum = 0;
+  for (const v of values) sum += v;
+  const mean = sum / n;
+  let sq = 0;
+  for (const v of values) {
+    const d = v - mean;
+    sq += d * d;
+  }
+  return Math.sqrt(sq / (n - 1));
+}
+
+function silverman(values: readonly number[]): number {
+  const n = values.length;
+  if (n < 2) return 0;
+  const sorted = values.slice().sort((a, b) => a - b);
+  const sd = stddev(sorted);
+  const q1 = quantile(sorted, 0.25);
+  const q3 = quantile(sorted, 0.75);
+  const iqr = q3 - q1;
+  // Robust scale per Silverman: min(σ, IQR/1.34).
+  const scale = iqr > 0 ? Math.min(sd, iqr / 1.34) : sd;
+  if (scale === 0) return 0;
+  return 1.06 * scale * Math.pow(n, -1 / 5);
+}
+
+function scott(values: readonly number[]): number {
+  const n = values.length;
+  if (n < 2) return 0;
+  // Scott's rule: plain standard deviation, no IQR robustification.
+  const sd = stddev(values);
+  if (sd === 0) return 0;
+  return 1.06 * sd * Math.pow(n, -1 / 5);
+}
+
+/**
+ * Kernel density estimate.
+ *
+ * Returns `null` for empty input. For all-equal samples falls back to a tiny
+ * bandwidth so callers don't divide by zero — the result is a narrow spike.
+ */
+export function kde(values: readonly number[], options: KdeOptions = {}): KdeResult | null {
+  const finite: number[] = [];
+  for (const v of values) {
+    if (Number.isFinite(v)) finite.push(v);
+  }
+  if (finite.length === 0) return null;
+
+  const gridSize = Math.max(2, Math.min(512, options.gridSize ?? 64));
+  const kernel: KdeKernel = options.kernel ?? "gaussian";
+  const trim = options.trim ?? true;
+
+  let bw: number;
+  const bwOpt = options.bandwidth ?? "silverman";
+  if (typeof bwOpt === "number") {
+    bw = bwOpt > 0 ? bwOpt : 1e-9;
+  } else {
+    bw = bwOpt === "scott" ? scott(finite) : silverman(finite);
+    if (bw <= 0) bw = 1e-9;
+  }
+
+  let lo: number;
+  let hi: number;
+  if (options.domain) {
+    [lo, hi] = options.domain;
+  } else {
+    lo = Number.POSITIVE_INFINITY;
+    hi = Number.NEGATIVE_INFINITY;
+    for (const v of finite) {
+      if (v < lo) lo = v;
+      if (v > hi) hi = v;
+    }
+    if (lo === hi) {
+      lo -= bw;
+      hi += bw;
+    }
+    if (!trim) {
+      lo -= 3 * bw;
+      hi += 3 * bw;
+    }
+  }
+
+  const x = Array.from<number>({ length: gridSize });
+  const y = Array.from<number>({ length: gridSize });
+  const step = (hi - lo) / (gridSize - 1);
+  const n = finite.length;
+  const invNbw = 1 / (n * bw);
+
+  if (kernel === "gaussian") {
+    const norm = invNbw / SQRT_2PI;
+    for (let i = 0; i < gridSize; i++) {
+      const xi = lo + step * i;
+      x[i] = xi;
+      let acc = 0;
+      for (let j = 0; j < n; j++) {
+        const u = (xi - finite[j]!) / bw;
+        acc += Math.exp(-0.5 * u * u);
+      }
+      y[i] = acc * norm;
+    }
+  } else {
+    // Epanechnikov: K(u) = 3/4 (1 - u²) on |u| ≤ 1.
+    const norm = invNbw * 0.75;
+    for (let i = 0; i < gridSize; i++) {
+      const xi = lo + step * i;
+      x[i] = xi;
+      let acc = 0;
+      for (let j = 0; j < n; j++) {
+        const u = (xi - finite[j]!) / bw;
+        if (u >= -1 && u <= 1) acc += 1 - u * u;
+      }
+      y[i] = acc * norm;
+    }
+  }
+
+  return { x, y, bandwidth: bw };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Group an iterable into a `Map` keyed by `key(item)`. Insertion order
+ * preserved per key; the map's key order is the order of first occurrence.
+ */
+export function groupBy<T, K>(items: Iterable<T>, key: (item: T, index: number) => K): Map<K, T[]> {
+  const out = new Map<K, T[]>();
+  let i = 0;
+  for (const item of items) {
+    const k = key(item, i++);
+    let bucket = out.get(k);
+    if (!bucket) {
+      bucket = [];
+      out.set(k, bucket);
+    }
+    bucket.push(item);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Binning (histogram support)
+// ---------------------------------------------------------------------------
+
+export type BinRule = "sturges" | "scott" | "fd" | "rice";
+export type BinClosed = "left" | "right";
+
+export interface BinBreaksOptions {
+  /** Explicit bin count. Ignored if `binwidth` or `breaks` is set. */
+  bins?: number;
+  /** Explicit bin width in data units. Beats `bins` and `rule`. */
+  binwidth?: number;
+  /** Fully explicit edge array — bypasses rules entirely. */
+  breaks?: readonly number[];
+  /**
+   * Rule used to pick a bin count when neither `bins`, `binwidth`, nor
+   * `breaks` is provided.
+   *
+   * - `"sturges"` (default) — `⌈log₂ n⌉ + 1`. R / ggplot default.
+   * - `"rice"` — `⌈2 · n^(1/3)⌉`. Slightly higher resolution.
+   * - `"scott"` — `3.49 σ n^(-1/3)` width. Good for roughly normal data.
+   * - `"fd"` — Freedman-Diaconis `2 · IQR · n^(-1/3)` width. Robust on skew.
+   */
+  rule?: BinRule;
+  /** Clip edges to this. Default = `[min, max]` of data. */
+  domain?: readonly [number, number];
+  /** Round outer edges + step to nice numbers. Default `true`. */
+  nice?: boolean;
+}
+
+export interface BinResult {
+  /** Inclusive lower edge for `closed: "left"` (the default). */
+  x0: number;
+  /** Exclusive upper edge for `closed: "left"`, except the final bin. */
+  x1: number;
+  /** Number of input values that fell in this bin. */
+  count: number;
+  /** `count / (n · width)`. Sums to 1 across all bins (∑ density · width). */
+  density: number;
+}
+
+/**
+ * How a histogram bin's `count` is converted into a y-axis value:
+ * - `"count"` / `"frequency"`: raw `count`
+ * - `"density"`: `count / (n · width)` — area sums to 1
+ * - `"proportion"`: `count / n` — values sum to 1
+ */
+export type HistogramMeasure = "count" | "density" | "proportion" | "frequency";
+
+/**
+ * Convert a `BinResult` to its measured value under `measure`. `n` is the
+ * total sample count for the histogram (or per-group total for stacked /
+ * faceted cases) — used to normalise `density` and `proportion`.
+ */
+export function histogramMeasureValue(
+  bin: BinResult,
+  n: number,
+  measure: HistogramMeasure,
+): number {
+  if (measure === "count" || measure === "frequency") return bin.count;
+  if (measure === "density") {
+    const w = bin.x1 - bin.x0;
+    return w > 0 && n > 0 ? bin.count / (n * w) : 0;
+  }
+  return n > 0 ? bin.count / n : 0;
+}
+
+export interface BinOptions extends BinBreaksOptions {
+  /**
+   * Edge-closure convention. With `"left"` (default) bins are `[x0, x1)` and
+   * the final bin includes the max as `[x_{k-1}, x_k]`. With `"right"` the
+   * first bin is `[x_0, x_1]` and the rest are `(x_i, x_{i+1}]`.
+   */
+  closed?: BinClosed;
+}
+
+const MIN_BINS = 1;
+const MAX_BINS = 1000;
+
+function clampBinCount(count: number): number {
+  if (!Number.isFinite(count) || count < MIN_BINS) return MIN_BINS;
+  if (count > MAX_BINS) return MAX_BINS;
+  return Math.floor(count);
+}
+
+function ruleBinCount(values: readonly number[], rule: BinRule, domain: [number, number]): number {
+  const n = values.length;
+  if (n < 2) return 1;
+  if (rule === "sturges") return clampBinCount(Math.ceil(Math.log2(n)) + 1);
+  if (rule === "rice") return clampBinCount(Math.ceil(2 * Math.pow(n, 1 / 3)));
+
+  const span = domain[1] - domain[0];
+  if (span <= 0) return 1;
+
+  if (rule === "scott") {
+    const sd = stddev(values);
+    if (sd <= 0) return 1;
+    const w = (3.49 * sd) / Math.cbrt(n);
+    return clampBinCount(Math.ceil(span / w));
+  }
+
+  // fd
+  const sorted = values.slice().sort((a, b) => a - b);
+  const q1 = quantile(sorted, 0.25);
+  const q3 = quantile(sorted, 0.75);
+  const iqr = q3 - q1;
+  const w = iqr > 0 ? (2 * iqr) / Math.cbrt(n) : (3.49 * stddev(values)) / Math.cbrt(n);
+  if (!(w > 0)) return 1;
+  return clampBinCount(Math.ceil(span / w));
+}
+
+function dataExtent(values: readonly number[]): [number, number] | null {
+  let lo = Number.POSITIVE_INFINITY;
+  let hi = Number.NEGATIVE_INFINITY;
+  for (const v of values) {
+    if (!Number.isFinite(v)) continue;
+    if (v < lo) lo = v;
+    if (v > hi) hi = v;
+  }
+  if (!Number.isFinite(lo) || !Number.isFinite(hi)) return null;
+  return [lo, hi];
+}
+
+function niceStep(span: number, count: number): number {
+  if (span <= 0 || count <= 0) return 1;
+  const step0 = span / count;
+  const power = Math.floor(Math.log10(step0));
+  const power10 = 10 ** power;
+  const error = step0 / power10;
+  let factor = 1;
+  if (error >= Math.sqrt(50)) factor = 10;
+  else if (error >= Math.sqrt(10)) factor = 5;
+  else if (error >= Math.sqrt(2)) factor = 2;
+  return factor * power10;
+}
+
+function buildEvenBreaks(lo: number, hi: number, count: number): number[] {
+  const out = Array.from<number>({ length: count + 1 });
+  const step = (hi - lo) / count;
+  for (let i = 0; i <= count; i++) out[i] = lo + step * i;
+  // Pin endpoints exactly to avoid float drift at the upper edge.
+  out[0] = lo;
+  out[count] = hi;
+  return out;
+}
+
+function buildNiceBreaks(lo: number, hi: number, count: number): number[] {
+  if (lo === hi) return [lo - 0.5, hi + 0.5];
+  const step = niceStep(hi - lo, count);
+  if (step <= 0) return buildEvenBreaks(lo, hi, count);
+  const start = Math.floor(lo / step) * step;
+  const end = Math.ceil(hi / step) * step;
+  const n = Math.max(1, Math.round((end - start) / step));
+  const out = Array.from<number>({ length: n + 1 });
+  for (let i = 0; i <= n; i++) out[i] = start + step * i;
+  return out;
+}
+
+/**
+ * Compute bin edges for the given data. Returns an array of length
+ * `binCount + 1` describing the boundaries of each bin from left to right.
+ *
+ * Resolution order (highest precedence first): explicit `breaks` → `binwidth`
+ * → `bins` → `rule` (default `"sturges"`).
+ *
+ * Returns `[]` for empty / all-non-finite input.
+ */
+export function binBreaks(values: readonly number[], options: BinBreaksOptions = {}): number[] {
+  if (options.breaks && options.breaks.length >= 2) {
+    return [...options.breaks];
+  }
+
+  const finite: number[] = [];
+  for (const v of values) {
+    if (Number.isFinite(v)) finite.push(v);
+  }
+  if (finite.length === 0) return [];
+
+  const dataDomain = dataExtent(finite)!;
+  const domain: [number, number] = options.domain
+    ? [options.domain[0], options.domain[1]]
+    : dataDomain;
+  let [lo, hi] = domain;
+  if (lo === hi) {
+    // Degenerate domain — produce a single bin around the value.
+    return [lo - 0.5, hi + 0.5];
+  }
+  if (lo > hi) [lo, hi] = [hi, lo];
+
+  const nice = options.nice ?? true;
+
+  if (typeof options.binwidth === "number" && options.binwidth > 0) {
+    const w = options.binwidth;
+    const start = nice ? Math.floor(lo / w) * w : lo;
+    const end = nice ? Math.ceil(hi / w) * w : hi;
+    const span = end - start;
+    const n = clampBinCount(Math.max(1, Math.round(span / w)));
+    const out = Array.from<number>({ length: n + 1 });
+    for (let i = 0; i <= n; i++) out[i] = start + w * i;
+    return out;
+  }
+
+  let count: number;
+  if (typeof options.bins === "number" && options.bins > 0) {
+    count = clampBinCount(options.bins);
+  } else {
+    const rule = options.rule ?? "sturges";
+    count = ruleBinCount(finite, rule, [lo, hi]);
+  }
+
+  return nice ? buildNiceBreaks(lo, hi, count) : buildEvenBreaks(lo, hi, count);
+}
+
+/**
+ * Bin a numeric sample into a sorted array of `BinResult`. Filters non-finite.
+ *
+ * Bins are half-open `[x0, x1)` by default (`closed: "left"`); the last bin
+ * is closed on both ends so the maximum value is counted. With
+ * `closed: "right"` the first bin is closed on both ends and the rest are
+ * `(x0, x1]`.
+ *
+ * Values strictly outside the resolved domain are dropped.
+ */
+export function bin(values: readonly number[], options: BinOptions = {}): BinResult[] {
+  const finite: number[] = [];
+  for (const v of values) {
+    if (Number.isFinite(v)) finite.push(v);
+  }
+  const breaks = binBreaks(finite, options);
+  return assignBins(finite, breaks, options.closed ?? "left");
+}
+
+/**
+ * Assign already-resolved values into known bin edges. Useful when the caller
+ * has computed `breaks` once across multiple groups (so per-group histograms
+ * align horizontally).
+ */
+export function binWithBreaks(
+  values: readonly number[],
+  breaks: readonly number[],
+  closed: BinClosed = "left",
+): BinResult[] {
+  const finite: number[] = [];
+  for (const v of values) {
+    if (Number.isFinite(v)) finite.push(v);
+  }
+  return assignBins(finite, breaks, closed);
+}
+
+function assignBins(
+  finite: readonly number[],
+  breaks: readonly number[],
+  closed: BinClosed,
+): BinResult[] {
+  if (breaks.length < 2) return [];
+  const k = breaks.length - 1;
+  const counts = Array.from({ length: k }, () => 0);
+  const lo = breaks[0]!;
+  const hi = breaks[k]!;
+  const n = finite.length;
+
+  for (let i = 0; i < n; i++) {
+    const v = finite[i]!;
+    if (v < lo || v > hi) continue;
+    const idx = locateBin(v, breaks, closed);
+    if (idx >= 0) counts[idx]!++;
+  }
+
+  let totalIn = 0;
+  for (const c of counts) totalIn += c;
+
+  const out: BinResult[] = Array.from({ length: k });
+  for (let i = 0; i < k; i++) {
+    const x0 = breaks[i]!;
+    const x1 = breaks[i + 1]!;
+    const w = x1 - x0;
+    const c = counts[i]!;
+    const density = totalIn > 0 && w > 0 ? c / (totalIn * w) : 0;
+    out[i] = { x0, x1, count: c, density };
+  }
+  return out;
+}
+
+/**
+ * Find the bin index for `v`. Binary search; returns -1 if out of range.
+ * Encodes the half-open / closed-end convention.
+ */
+function locateBin(v: number, breaks: readonly number[], closed: BinClosed): number {
+  const k = breaks.length - 1;
+  // Boundary handling for the closed-on-both-ends bin (last for "left",
+  // first for "right").
+  if (closed === "left") {
+    if (v === breaks[k]!) return k - 1;
+  } else {
+    if (v === breaks[0]!) return 0;
+  }
+  // Binary search for the rightmost edge <= v (left) or < v (right).
+  let lo = 0;
+  let hi = k;
+  while (lo < hi) {
+    const mid = (lo + hi) >>> 1;
+    const edge = breaks[mid + 1]!;
+    const goRight = closed === "left" ? v >= edge : v > edge;
+    if (goRight) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo < k ? lo : -1;
+}
+
+export interface BinByOptions extends BinOptions {
+  /**
+   * Use one shared edge array for every group (default `true`) so per-group
+   * histograms align horizontally for stack/dodge/overlay. With `false`, each
+   * group computes its own breaks against its own data.
+   */
+  sharedBreaks?: boolean;
+}
+
+export interface BinByResult<K> {
+  breaks: number[];
+  groups: Map<K, BinResult[]>;
+}
+
+/**
+ * Bin a flat numeric array partitioned by key. Group iteration order matches
+ * first-occurrence order in the input.
+ */
+export function binBy<K>(
+  values: readonly number[],
+  keys: readonly K[],
+  options: BinByOptions = {},
+): BinByResult<K> {
+  const groups = new Map<K, number[]>();
+  for (let i = 0; i < values.length; i++) {
+    const v = values[i]!;
+    if (!Number.isFinite(v)) continue;
+    const k = keys[i] as K;
+    let bucket = groups.get(k);
+    if (!bucket) {
+      bucket = [];
+      groups.set(k, bucket);
+    }
+    bucket.push(v);
+  }
+
+  const shared = options.sharedBreaks ?? true;
+  const closed = options.closed ?? "left";
+  const breaks = shared ? binBreaks(values, options) : [];
+
+  const out = new Map<K, BinResult[]>();
+  for (const [k, bucket] of groups) {
+    const groupBreaks = shared ? breaks : binBreaks(bucket, options);
+    out.set(k, assignBins(bucket, groupBreaks, closed));
+  }
+
+  return { breaks, groups: out };
+}
+
+/**
+ * Deterministic uniform jitter offsets in `[-width/2, +width/2]`. Same
+ * `(seed, count)` pair always produces the same sequence — important so that
+ * jittered overlay points don't dance between renders.
+ */
+export function jitter(seed: number, count: number, width: number): number[] {
+  // Mulberry32 — small, fast, good enough for visual jitter.
+  let state = seed | 0 || 1;
+  const out = Array.from<number>({ length: count });
+  for (let i = 0; i < count; i++) {
+    state = (state + 0x6d2b79f5) | 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    const r = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    out[i] = (r - 0.5) * width;
+  }
+  return out;
+}