insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/aggregate.test.ts

@@ -0,0 +1,554 @@
+// @vitest-environment jsdom
+import { createFrame } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+
+import { resolveAes } from "../aes.ts";
+import { buildPositionScale, type ScaleBundle } from "../scales.ts";
+import { themeDefault } from "../theme.ts";
+import { aggregate } from "./aggregate.ts";
+import type { CompileContext } from "./types.ts";
+
+interface Row {
+  x: number;
+  y: number;
+  accepted: boolean;
+}
+
+const RANGE_X: readonly [number, number] = [0, 100];
+const RANGE_Y: readonly [number, number] = [200, 0];
+
+function makeCtx<T extends Row>(rows: readonly T[]): CompileContext<T> {
+  const xAes = resolveAes<T, unknown>("x");
+  const yAes = resolveAes<T, unknown>("y");
+  // Pin the visible domain to a known span so bin maths is deterministic
+  // (otherwise auto-inferred extents can shift bin anchoring).
+  const xScale = buildPositionScale(xAes, rows, RANGE_X, { domain: [0, 100] });
+  const yScale = buildPositionScale(yAes, rows, RANGE_Y, { domain: [0, 100] });
+  const scales: ScaleBundle = { x: xScale, y: yScale };
+  return {
+    data: rows,
+    scales,
+    plot: createFrame({ x: 0, y: 0, width: 100, height: 200 }),
+    theme: themeDefault,
+    atlas: undefined,
+  };
+}
+
+// Captures the rects a bar mark emits via `layer.pushRect`, so baseline
+// geometry can be asserted without a real GPU layer.
+function fakeRectLayer(): {
+  rects: Array<{ x: number; y: number; width: number; height: number }>;
+  layer: { pushRect: (shape: { x: number; y: number; width: number; height: number }) => void };
+} {
+  const rects: Array<{ x: number; y: number; width: number; height: number }> = [];
+  return {
+    rects,
+    layer: {
+      pushRect(shape) {
+        rects.push(shape);
+      },
+    },
+  };
+}
+
+// Uniform synthetic dataset: 100 rows spread evenly across x ∈ [0, 100).
+function uniform(count: number): Row[] {
+  const out: Row[] = Array.from({ length: count });
+  for (let i = 0; i < count; i++) {
+    out[i] = { x: (i / count) * 100, y: i, accepted: true };
+  }
+  return out;
+}
+
+describe("aggregate geom", () => {
+  test("bin counts match analytic expectation for a uniform distribution", () => {
+    const rows = uniform(100);
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "count", dissolveAt: 0 },
+    );
+    const builders = geom.compile(ctx);
+    expect(builders.length).toBe(1);
+    // 100 points across 10 bins of width 10 → 10 non-empty bins.
+    expect(builders[0]!.length).toBe(10);
+  });
+
+  test("explicit auto bin size targets ~7 px per bin", () => {
+    // 100 px range, target 7 px per bin → ~14 bins of ~7.14 domain units.
+    const rows = uniform(200);
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: "auto", summary: "count", dissolveAt: 0 },
+    );
+    const builders = geom.compile(ctx);
+    // 100 / 7.14 = 14.0 — accept 13 / 14 / 15 to absorb rounding.
+    expect(builders[0]!.length).toBeGreaterThanOrEqual(13);
+    expect(builders[0]!.length).toBeLessThanOrEqual(15);
+  });
+
+  test("dissolve threshold flips to raw geom when avg/bin drops below cutoff", () => {
+    // 4 rows across 10 bins (width 10) → 4 non-empty bins, avg/bin = 0.4
+    // which is below default dissolveAt of 1.2 → render raw.
+    const sparse: Row[] = [
+      { x: 5, y: 5, accepted: true },
+      { x: 35, y: 35, accepted: true },
+      { x: 60, y: 60, accepted: true },
+      { x: 95, y: 95, accepted: true },
+    ];
+    const ctx = makeCtx(sparse);
+    const geom = aggregate<Row>({ x: (d) => d.x, y: (d) => d.y }, { binSize: 10, summary: "mean" });
+    const builders = geom.compile(ctx);
+    // Raw path → one builder, length === raw row count (4).
+    expect(builders.length).toBe(1);
+    expect(builders[0]!.length).toBe(4);
+  });
+
+  test("low dissolveAt holds the aggregate path even on sparse data", () => {
+    const sparse: Row[] = [
+      { x: 5, y: 5, accepted: true },
+      { x: 35, y: 35, accepted: true },
+      { x: 60, y: 60, accepted: true },
+      { x: 95, y: 95, accepted: true },
+    ];
+    const ctx = makeCtx(sparse);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "mean", dissolveAt: 0 },
+    );
+    const builders = geom.compile(ctx);
+    // 10 bins covering [0, 100], 4 with data → 4 bin points emitted.
+    expect(builders[0]!.length).toBe(4);
+  });
+
+  test("filter removes rows from both bin contents and bin emission", () => {
+    // 100 rows but only every 5th is accepted → 20 rows passing the filter.
+    const rows = uniform(100).map((r, i) => ({ ...r, accepted: i % 5 === 0 }));
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      {
+        binSize: 25, // 4 bins across [0, 100]
+        summary: "count",
+        filter: (d) => d.accepted,
+        dissolveAt: 0,
+      },
+    );
+    const builders = geom.compile(ctx);
+    // 20 accepted points across 4 bins → 4 non-empty bins emitted; the count
+    // summary should yield 5 per bin.
+    expect(builders[0]!.length).toBe(4);
+  });
+
+  test("supports point inner geom (default)", () => {
+    const rows = uniform(40);
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "mean", dissolveAt: 0 },
+    );
+    expect(geom.kind).toBe("point");
+    expect(geom.compile(ctx).length).toBeGreaterThan(0);
+  });
+
+  test("supports line inner geom", () => {
+    const rows = uniform(40);
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "mean", geom: "line", dissolveAt: 0 },
+    );
+    expect(geom.kind).toBe("line");
+    expect(geom.compile(ctx).length).toBeGreaterThan(0);
+  });
+
+  test("supports bar inner geom", () => {
+    const rows = uniform(40);
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "count", geom: "bar", dissolveAt: 0 },
+    );
+    expect(geom.kind).toBe("bar");
+    expect(geom.compile(ctx).length).toBeGreaterThan(0);
+  });
+
+  test("bar baseline uses the y range floor on a log axis (not yScale(0))", () => {
+    // Log y axis: domain [10, 1000], range [200, 0]. `yScale(0)` is garbage
+    // here — logTransform(0)=0 normalizes to t=-0.5 → interpolate(200,0,-0.5)
+    // = 300px, i.e. *off the bottom* of the 200px plot. The bars must instead
+    // sit on the range floor (range[0] = 200, paired with domain min 10, the
+    // endpoint nearest zero).
+    //
+    // Rows all carry y∈[10,1000] so the binned means land inside the domain.
+    interface LRow {
+      x: number;
+      y: number;
+    }
+    const rows: LRow[] = Array.from({ length: 40 }, (_, i) => ({
+      x: (i / 40) * 100,
+      y: 10 + (i % 10) * 99, // 10..901, comfortably inside [10, 1000]
+    }));
+    const xAes = resolveAes<LRow, unknown>("x");
+    const yAes = resolveAes<LRow, unknown>("y");
+    const xScale = buildPositionScale(xAes, rows, RANGE_X, { domain: [0, 100] });
+    const yScale = buildPositionScale(yAes, rows, RANGE_Y, {
+      type: "log",
+      domain: [10, 1000],
+    });
+    const ctx: CompileContext<LRow> = {
+      data: rows,
+      scales: { x: xScale, y: yScale },
+      plot: createFrame({ x: 0, y: 0, width: 100, height: 200 }),
+      theme: themeDefault,
+      atlas: undefined,
+    };
+
+    // Sanity: on a log axis the bug's baseline (yScale(0)) is non-finite —
+    // log(0) = -∞ — so feeding it to bar geometry yields NaN rects. The
+    // assertions below confirm the fix uses the range floor instead.
+    expect(Number.isFinite(yScale.fn(0))).toBe(false);
+
+    const geom = aggregate<LRow>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "mean", geom: "bar", dissolveAt: 0 },
+    );
+    const builders = geom.compile(ctx);
+    expect(builders.length).toBe(1);
+
+    const { rects, layer } = fakeRectLayer();
+    for (const b of builders) b.addTo(layer as never);
+    expect(rects.length).toBeGreaterThan(0);
+
+    // Every bar's bottom edge (y + height) must rest on the range floor (200),
+    // NOT the clamped yScale(0)=300. Tops vary with each bin's mean.
+    for (const r of rects) {
+      expect(r.y + r.height).toBeCloseTo(200, 3);
+      // And the top must be a sane in-plot pixel (0..200), never beyond.
+      expect(r.y).toBeGreaterThanOrEqual(0);
+      expect(r.y).toBeLessThanOrEqual(200);
+    }
+  });
+
+  test("bar baseline stays at yScale(0) when 0 is within the domain", () => {
+    // Control: a linear y axis spanning zero must keep the existing behavior —
+    // the baseline is yScale(0), the bars' floor.
+    const rows = uniform(40);
+    const ctx = makeCtx(rows); // y domain [0, 100], range [200, 0] → yScale(0)=200
+    expect(ctx.scales.y.fn(0)).toBeCloseTo(200, 3);
+
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "mean", geom: "bar", dissolveAt: 0 },
+    );
+    const builders = geom.compile(ctx);
+    const { rects, layer } = fakeRectLayer();
+    for (const b of builders) b.addTo(layer as never);
+    expect(rects.length).toBeGreaterThan(0);
+    for (const r of rects) {
+      expect(r.y + r.height).toBeCloseTo(200, 3);
+    }
+  });
+
+  test("aggregates Date-valued x with binSize in ms", () => {
+    interface TRow {
+      ts: Date;
+      v: number;
+    }
+    // 10 days, one row per day at midnight UTC. Pick a base aligned to a
+    // multiple of `binSize` so the floor-to-bin anchor lands on day 0.
+    const day = 86_400_000;
+    const binMs = 2 * day;
+    const base = Math.floor(Date.UTC(2024, 0, 1) / binMs) * binMs;
+    const rows: TRow[] = Array.from(
+      { length: 10 },
+      (_, i) => ({ ts: new Date(base + i * day), v: i }) as TRow,
+    );
+    const xAes = resolveAes<TRow, unknown>("ts");
+    const yAes = resolveAes<TRow, unknown>("v");
+    const xScale = buildPositionScale(xAes, rows, RANGE_X, {
+      type: "time",
+      domain: [new Date(base), new Date(base + 10 * day)],
+    });
+    const yScale = buildPositionScale(yAes, rows, RANGE_Y, { domain: [0, 10] });
+    const ctx: CompileContext<TRow> = {
+      data: rows,
+      scales: { x: xScale, y: yScale },
+      plot: createFrame({ x: 0, y: 0, width: 100, height: 200 }),
+      theme: themeDefault,
+      atlas: undefined,
+    };
+    const geom = aggregate<TRow>(
+      { x: (d) => d.ts, y: (d) => d.v },
+      { binSize: binMs, summary: "mean", dissolveAt: 0 },
+    );
+    const builders = geom.compile(ctx);
+    // 10 days / 2-day bins → 5 non-empty bins.
+    expect(builders[0]!.length).toBe(5);
+  });
+
+  test("custom function summary fires with full bin view", () => {
+    const rows = uniform(40);
+    const ctx = makeCtx(rows);
+    let sawNonEmpty = false;
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      {
+        binSize: 25,
+        summary: (bin) => {
+          if (bin.count > 0 && bin.items.length === bin.count) sawNonEmpty = true;
+          return bin.values.reduce((s, v) => s + v, 0);
+        },
+        dissolveAt: 0,
+      },
+    );
+    const builders = geom.compile(ctx);
+    expect(builders[0]!.length).toBe(4);
+    expect(sawNonEmpty).toBe(true);
+  });
+
+  test("empty data returns no builders", () => {
+    const ctx = makeCtx([] as Row[]);
+    const geom = aggregate<Row>({ x: (d) => d.x, y: (d) => d.y }, { binSize: 10 });
+    expect(geom.compile(ctx).length).toBe(0);
+  });
+
+  test("filter dropping every row yields no builders", () => {
+    const rows = uniform(20);
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, filter: () => false },
+    );
+    expect(geom.compile(ctx).length).toBe(0);
+  });
+
+  test("binBy: 'y' flips bin axis and aggregates x", () => {
+    const rows = uniform(40);
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, binBy: "y", summary: "mean", dissolveAt: 0 },
+    );
+    const builders = geom.compile(ctx);
+    expect(builders[0]!.length).toBeGreaterThan(0);
+  });
+
+  test("end-to-end via plot().toSVG() does not throw", async () => {
+    const { plot } = await import("../chart.ts");
+    const rows = uniform(80);
+    expect(() =>
+      plot({ data: rows, width: 320, height: 200 })
+        .layer(
+          aggregate<Row>(
+            { x: (d) => d.x, y: (d) => d.y },
+            { binSize: 10, summary: "mean", dissolveAt: 0 },
+          ),
+        )
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  // ---------------------------------------------------------------------------
+  // Bundle summaries — mean+ci / median+iqr / quantile triple
+  // ---------------------------------------------------------------------------
+
+  test("mean+ci produces interval marks with z*stderr half-width", () => {
+    // Build bins where each contains constant-spaced values so the mean/CI
+    // are analytically tractable. Two rows per bin at ±d from the mean ⇒
+    // sample stddev = d*sqrt(2/(n-1)) = d, stderr = d/sqrt(2). For 95% CI
+    // (z≈1.96) the half-width is z*d/sqrt(2) ≈ 1.3859 * d.
+    //
+    // We use d = 10 across two bins (x∈[0,10) and x∈[10,20)) and check that
+    // the interval geom emits the expected number of line builders (1
+    // builder containing 1 spine + 2 caps per bin = 6 line segments).
+    const rows: Row[] = [
+      { x: 1, y: 90, accepted: true },
+      { x: 2, y: 110, accepted: true },
+      { x: 11, y: 40, accepted: true },
+      { x: 12, y: 60, accepted: true },
+    ];
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "mean+ci", geom: "interval", ciLevel: 0.95 },
+    );
+    expect(geom.kind).toBe("interval");
+    const builders = geom.compile(ctx);
+    // interval emits one builder; length = spines + caps = 1 + 2 per bin.
+    expect(builders.length).toBe(1);
+    expect(builders[0]!.length).toBe(6);
+  });
+
+  test("mean+ci collapses to a point when count<2 per bin", () => {
+    // One row per bin → stderr undefined; impl clamps to lo=hi=center.
+    const rows: Row[] = [
+      { x: 5, y: 50, accepted: true },
+      { x: 15, y: 60, accepted: true },
+    ];
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "mean+ci", geom: "interval" },
+    );
+    const builders = geom.compile(ctx);
+    // Two bins × (spine + 2 caps) = 6.
+    expect(builders[0]!.length).toBe(6);
+  });
+
+  test("median+iqr emits an interval with [Q1, Q3] bounds", () => {
+    // Five rows in a single bin at y = 10, 20, 30, 40, 50 →
+    // median = 30, Q1 = 20, Q3 = 40 (R type-7).
+    const rows: Row[] = [
+      { x: 1, y: 10, accepted: true },
+      { x: 2, y: 20, accepted: true },
+      { x: 3, y: 30, accepted: true },
+      { x: 4, y: 40, accepted: true },
+      { x: 5, y: 50, accepted: true },
+    ];
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "median+iqr", geom: "interval" },
+    );
+    const builders = geom.compile(ctx);
+    // One bin → 1 spine + 2 caps = 3 segments.
+    expect(builders[0]!.length).toBe(3);
+  });
+
+  test("median+iqr without caps drops the cap segments", () => {
+    const rows: Row[] = [
+      { x: 1, y: 10, accepted: true },
+      { x: 2, y: 20, accepted: true },
+      { x: 3, y: 30, accepted: true },
+    ];
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "median+iqr", geom: "interval", caps: false },
+    );
+    const builders = geom.compile(ctx);
+    // 1 spine, 0 caps.
+    expect(builders[0]!.length).toBe(1);
+  });
+
+  test("quantile triple summary picks the requested order statistics", () => {
+    // 10 rows in a single bin, y = 1..10. For quantiles [0.1, 0.5, 0.9]
+    // with R type-7 interpolation: q0.1 = 1.9, q0.5 = 5.5, q0.9 = 9.1.
+    const rows: Row[] = Array.from({ length: 10 }, (_, i) => ({
+      x: i % 10, // all in [0, 10) → single bin of size 10
+      y: i + 1,
+      accepted: true,
+    }));
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      {
+        binSize: 10,
+        summary: { quantiles: [0.1, 0.5, 0.9] },
+        geom: "interval",
+        caps: false,
+      },
+    );
+    const builders = geom.compile(ctx);
+    // 1 spine, no caps.
+    expect(builders[0]!.length).toBe(1);
+  });
+
+  test("ribbon inner emits one area builder with bin-center vertices", () => {
+    // Three contiguous bins. Ribbon stitches them into a single area mark
+    // — areaMark returns one builder per (sub-)segment, and with no NaN
+    // discontinuities the entire band is one piece.
+    const rows: Row[] = [
+      { x: 1, y: 10, accepted: true },
+      { x: 2, y: 30, accepted: true },
+      { x: 11, y: 20, accepted: true },
+      { x: 12, y: 40, accepted: true },
+      { x: 21, y: 30, accepted: true },
+      { x: 22, y: 50, accepted: true },
+    ];
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      { binSize: 10, summary: "mean+ci", geom: "ribbon" },
+    );
+    expect(geom.kind).toBe("area");
+    const builders = geom.compile(ctx);
+    expect(builders.length).toBeGreaterThan(0);
+  });
+
+  test("throws when bundle summary is paired with a scalar inner geom", () => {
+    expect(() =>
+      aggregate<Row>({ x: (d) => d.x, y: (d) => d.y }, { summary: "mean+ci", geom: "point" }),
+    ).toThrowError(/bundle summary requires geom/);
+  });
+
+  test("throws when a bundle inner geom gets a scalar summary kind", () => {
+    expect(() =>
+      aggregate<Row>({ x: (d) => d.x, y: (d) => d.y }, { summary: "mean", geom: "interval" }),
+    ).toThrowError(/requires a bundle summary/);
+  });
+
+  test("throws on ribbon + binBy: 'y' (horizontal ribbons not supported)", () => {
+    expect(() =>
+      aggregate<Row>(
+        { x: (d) => d.x, y: (d) => d.y },
+        { summary: "mean+ci", geom: "ribbon", binBy: "y" },
+      ),
+    ).toThrowError(/only supports binBy: "x"/);
+  });
+
+  test("custom function summary returning {center,lo,hi} feeds interval", () => {
+    // Function form is disambiguated by inner-geom kind, not by typing.
+    const rows: Row[] = [
+      { x: 1, y: 5, accepted: true },
+      { x: 2, y: 15, accepted: true },
+      { x: 11, y: 25, accepted: true },
+      { x: 12, y: 35, accepted: true },
+    ];
+    const ctx = makeCtx(rows);
+    const geom = aggregate<Row>(
+      { x: (d) => d.x, y: (d) => d.y },
+      {
+        binSize: 10,
+        summary: (bin) => {
+          // emit min/max as the bundle range; mean as center.
+          let mn = Number.POSITIVE_INFINITY;
+          let mx = Number.NEGATIVE_INFINITY;
+          let s = 0;
+          for (const v of bin.values) {
+            if (v < mn) mn = v;
+            if (v > mx) mx = v;
+            s += v;
+          }
+          return { center: s / bin.count, lo: mn, hi: mx };
+        },
+        geom: "interval",
+        caps: false,
+      },
+    );
+    const builders = geom.compile(ctx);
+    // Two bins × 1 spine each (caps off) = 2 segments.
+    expect(builders[0]!.length).toBe(2);
+  });
+
+  test("end-to-end via plot().toSVG() does not throw for interval bundle", async () => {
+    const { plot } = await import("../chart.ts");
+    const rows: Row[] = Array.from({ length: 60 }, (_, i) => ({
+      x: i,
+      y: 50 + Math.sin(i / 5) * 20,
+      accepted: true,
+    }));
+    expect(() =>
+      plot({ data: rows, width: 320, height: 200 })
+        .layer(
+          aggregate<Row>(
+            { x: (d) => d.x, y: (d) => d.y },
+            { binSize: 6, summary: "median+iqr", geom: "interval" },
+          ),
+        )
+        .toSVG(),
+    ).not.toThrow();
+  });
+});