insomni-plot 0.1.0-alpha.0

package/src/grammar/geoms/boxplot.d.ts

@@ -0,0 +1,129 @@
+import type { Color } from "insomni";
+import { type QuantileMethod, type WhiskerRule } from "../../stats/index.ts";
+import { type PointShapeKind } from "../../marks.ts";
+import type { Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+import { type CategoricalLayout } from "./_categorical.ts";
+export type PointsMode = "auto" | "always" | "none";
+export interface BoxplotChannels<T> {
+    /** Categorical band axis. */
+    x: Aes<T, string | number | Date>;
+    /**
+     * Numeric value axis (the distribution to summarize) when vertical. For
+     * horizontal layouts (`orientation: "x"`) this carries the band category, so
+     * a string is accepted; the value axis then lives on `x`.
+     */
+    y: Aes<T, string | number | Date>;
+    /**
+     * Optional grouping key. When supplied (and distinct from `x`) the layer
+     * dodges side-by-side by this channel within each band.
+     */
+    color?: Aes<T, unknown>;
+}
+/**
+ * Mean-overlay configuration. `true` → default red dot; `false` (default) →
+ * no overlay; object → fully customised.
+ */
+export interface MeanMarkerOptions {
+    shape?: PointShapeKind;
+    /** Radius in pixels. Default `3.5`. */
+    radius?: number;
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+}
+export interface BoxplotOptions {
+    /** Auto-detected from scale types when omitted (band axis = category axis). */
+    orientation?: "x" | "y";
+    /**
+     * Box width as a fraction of the bandwidth (or grouped inner bandwidth, when
+     * dodging). Default `0.6`.
+     */
+    width?: number;
+    /**
+     * Scale box widths by `√(n / nMax)` so groups with more samples render
+     * wider — matches ggplot's `varwidth = TRUE`. Default `false`.
+     */
+    varwidth?: boolean;
+    /** Whisker rule. Default `1.5` (Tukey). Pass `"minmax"` for no outliers. */
+    whisker?: WhiskerRule;
+    /** Quantile interpolation method. Default `"type-7"` (R default). */
+    quantile?: QuantileMethod;
+    /**
+     * Render notches around the median at `± 1.58 · IQR / √n` (McGill 1978's
+     * 95% CI). Useful as an informal significance test: non-overlapping
+     * notches between groups suggest medians differ. Default `false`.
+     */
+    notched?: boolean;
+    /**
+     * Notch indent as a fraction of the box width (how far the sides pull in
+     * at the median). Default `0.5`.
+     */
+    notchWidth?: number;
+    /**
+     * When to overlay raw jittered points.
+     *
+     * - `"auto"` (default) — only when `n < pointsThreshold` for the group.
+     *   Rationale: small samples are easy to mislead with a box; show the dots.
+     * - `"always"` — always overlay.
+     * - `"none"` — never overlay (still draws outliers unless `outliers: false`).
+     */
+    points?: PointsMode;
+    /** Threshold for `points: "auto"`. Default `10`. */
+    pointsThreshold?: number;
+    /** Jitter spread, fraction of the per-box width. Default `0.5`. */
+    pointJitter?: number;
+    /** Radius of overlay & outlier points. Default `2.5`. */
+    pointRadius?: number;
+    /** Override fill for jittered overlay points. Default `alphaize(stroke, 0.5)`. */
+    pointFill?: Color;
+    /** Override fill for outlier points. Default = stroke. */
+    outlierFill?: Color;
+    /** Outlier point radius. Default = `pointRadius`. */
+    outlierRadius?: number;
+    /** Seed for deterministic jitter. Default `1`. */
+    jitterSeed?: number;
+    /** Render outlier dots beyond the whiskers. Default `true`. */
+    outliers?: boolean;
+    /** Constant fill when no `color` channel. Default theme palette[0]. */
+    fill?: Color;
+    /**
+     * Override the theme's fill alpha (use `0` for outline-only boxes, e.g.
+     * to match ggplot's bottom-middle "no-fill" look). When unset the layer
+     * uses `theme.marks.fillAlpha`.
+     */
+    fillAlpha?: number;
+    /** Box stroke color. Default theme text color (light line on dark fill). */
+    stroke?: Color;
+    /** Box stroke width. Default `1`. */
+    strokeWidth?: number;
+    /** Median line color. Defaults to `stroke`. */
+    medianStroke?: Color;
+    /** Median line stroke width. Default `2`. */
+    medianStrokeWidth?: number;
+    /** Whisker line stroke width. Default = `strokeWidth`. */
+    whiskerStrokeWidth?: number;
+    /** Whisker cap width as a fraction of box width. Default `0.5`. */
+    capWidth?: number;
+    /**
+     * Mean overlay. `true` for the default red dot; `false` (default) to omit;
+     * pass an object to customize shape, radius, fill, stroke. The mean is
+     * **not** part of the box geometry — it's an annotation on top.
+     */
+    mean?: boolean | MeanMarkerOptions;
+    /** Inner-band padding for grouped (color-split) layout. Default `0.05`. */
+    groupPadding?: number;
+    /**
+     * Render an `n=<count>` label per band-axis category, just outside the
+     * plot frame. Counts are summed across dodge groups. Default `false`.
+     */
+    showCounts?: boolean;
+    /** Pixel offset of count labels from plot frame. Default `28` (vertical) / `32` (horizontal). */
+    countsOffset?: number;
+    countsFontSize?: number;
+    countsColor?: Color;
+    /** Display label for legend. */
+    label?: string;
+}
+export declare function boxplot<T>(channels: BoxplotChannels<T>, options?: BoxplotOptions): Geom<T>;
+export type { CategoricalLayout };

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

@@ -0,0 +1,299 @@
+// @vitest-environment jsdom
+import { createFrame } from "insomni";
+import { describe, expect, test } from "vite-plus/test";
+import { plot } from "../chart.ts";
+import { resolveAes } from "../aes.ts";
+import { buildPositionScale, type ScaleBundle } from "../scales.ts";
+import { themeDefault } from "../theme.ts";
+import { boxplot } from "./boxplot.ts";
+import { emphasisKeyFor, geomEmphasisBase } from "./emphasis.ts";
+import type { CompileContext } from "./types.ts";
+
+// A fake Layer that records the emphasisKey of every primitive pushed, across
+// all the push kinds a box composites (rect / polyline / circle / polygon).
+function makeKeyCapture() {
+  const keys: (number | undefined)[] = [];
+  const record = (s: { emphasisKey?: number }) => keys.push(s.emphasisKey);
+  const layer = {
+    pushRect: record,
+    pushCircle: record,
+    pushEllipse: record,
+    pushSegment: record,
+    pushLine: record,
+    pushPolyline: record,
+    pushPolygon: record,
+    pushText: () => layer,
+    pushString: () => layer,
+  };
+  return { layer, keys };
+}
+
+interface Obs {
+  group: string;
+  value: number;
+  color?: string;
+}
+
+// ============ Fixtures ============
+const fixture = {
+  // Three categories, ~10 observations each, seeded so tests are deterministic.
+  threeGroups: (): Obs[] => {
+    const out: Obs[] = [];
+    const seeds = { A: 0.1, B: 0.5, C: 0.9 };
+    let r = 0;
+    const rand = () => {
+      r = (r * 9301 + 49297) % 233280;
+      return r / 233280;
+    };
+    for (const [name, mu] of Object.entries(seeds)) {
+      for (let i = 0; i < 12; i++) {
+        out.push({ group: name, value: mu + (rand() - 0.5) * 0.3 });
+      }
+    }
+    return out;
+  },
+  withOutliers: (): Obs[] =>
+    [1, 2, 2, 3, 3, 3, 4, 4, 5, 12, 18].map((v) => ({ group: "A", value: v })),
+  smallSample: (): Obs[] => [1, 2, 3].map((v) => ({ group: "A", value: v })),
+  dodged: (): Obs[] => {
+    const out: Obs[] = [];
+    for (const grp of ["A", "B"]) {
+      for (const col of ["x", "y"]) {
+        for (let i = 0; i < 10; i++) {
+          out.push({ group: grp, color: col, value: i + (col === "x" ? 0 : 5) });
+        }
+      }
+    }
+    return out;
+  },
+};
+
+// ============ Tests ============
+describe("boxplot()", () => {
+  test("renders to SVG with a band x-axis and numeric y", () => {
+    const svg = plot({ data: fixture.threeGroups(), width: 400, height: 300 })
+      .layer(boxplot({ x: "group", y: "value" }))
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+    // Three groups, no outliers expected with this jitter range.
+    // We assert the SVG produced something non-trivial by checking the body dim.
+    expect(svg.getAttribute("width")).toBe("400");
+  });
+
+  test("renders outlier points beyond 1.5*IQR by default", () => {
+    const svg = plot({ data: fixture.withOutliers(), width: 320, height: 240 })
+      .layer(boxplot({ x: "group", y: "value" }))
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+    // Two outliers (12, 18) → at least 2 circles. SVG renderer represents
+    // circles as <circle> nodes.
+    const circles = svg.querySelectorAll("circle");
+    expect(circles.length).toBeGreaterThanOrEqual(2);
+  });
+
+  test("'minmax' whisker rule emits no outlier circles", () => {
+    const svg = plot({ data: fixture.withOutliers(), width: 320, height: 240 })
+      .layer(boxplot({ x: "group", y: "value" }, { whisker: "minmax", points: "none" }))
+      .toSVG();
+    const circles = svg.querySelectorAll("circle");
+    expect(circles.length).toBe(0);
+  });
+
+  test("auto-overlays jittered points when n < threshold", () => {
+    const svg = plot({ data: fixture.smallSample(), width: 320, height: 240 })
+      .layer(boxplot({ x: "group", y: "value" }, { points: "auto", pointsThreshold: 10 }))
+      .toSVG();
+    const circles = svg.querySelectorAll("circle");
+    expect(circles.length).toBeGreaterThanOrEqual(3);
+  });
+
+  test("dodges by color channel without throwing", () => {
+    const svg = plot({ data: fixture.dodged(), width: 480, height: 320 })
+      .layer(boxplot({ x: "group", y: "value", color: "color" }))
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+  });
+
+  test("does not throw on n=1 or all-equal samples", () => {
+    expect(() =>
+      plot({ data: [{ group: "A", value: 5 }] as Obs[] })
+        .layer(boxplot({ x: "group", y: "value" }))
+        .toSVG({ width: 200, height: 200 }),
+    ).not.toThrow();
+    expect(() =>
+      plot({ data: [1, 1, 1, 1].map((v) => ({ group: "A", value: v })) as Obs[] })
+        .layer(boxplot({ x: "group", y: "value" }))
+        .toSVG({ width: 200, height: 200 }),
+    ).not.toThrow();
+  });
+
+  test("notched boxes emit polygon nodes (one per group)", () => {
+    const svg = plot({ data: fixture.threeGroups(), width: 400, height: 300 })
+      .layer(boxplot({ x: "group", y: "value" }, { notched: true, points: "none" }))
+      .toSVG();
+    // Notched bodies are rendered as polygons; un-notched would be <rect>.
+    const polygons = svg.querySelectorAll("polygon");
+    const rects = svg.querySelectorAll("rect");
+    expect(polygons.length).toBeGreaterThanOrEqual(3);
+    // The 3 box bodies should now be polygons rather than rects (rects may
+    // still appear from background panel etc, but at least 3 polygons exist).
+    expect(polygons.length).toBeGreaterThan(0);
+    expect(rects.length).toBeGreaterThanOrEqual(0);
+  });
+
+  test("mean: true overlays one additional point per group", () => {
+    const data = fixture.threeGroups();
+    const baseSvg = plot({ data, width: 320, height: 240 })
+      .layer(boxplot({ x: "group", y: "value" }, { points: "none", outliers: false }))
+      .toSVG();
+    const meanSvg = plot({ data, width: 320, height: 240 })
+      .layer(boxplot({ x: "group", y: "value" }, { points: "none", outliers: false, mean: true }))
+      .toSVG();
+    const baseCircles = baseSvg.querySelectorAll("circle").length;
+    const meanCircles = meanSvg.querySelectorAll("circle").length;
+    expect(meanCircles - baseCircles).toBe(3);
+  });
+
+  test("mean accepts a custom shape and the renderer doesn't throw", () => {
+    expect(() =>
+      plot({ data: fixture.threeGroups() })
+        .layer(
+          boxplot(
+            { x: "group", y: "value" },
+            { mean: { shape: "diamond", radius: 4 }, points: "none" },
+          ),
+        )
+        .toSVG({ width: 320, height: 240 }),
+    ).not.toThrow();
+  });
+
+  test("showCounts does not throw and renders without an atlas", () => {
+    // SVG export without a device has no glyph atlas, so the count labels are
+    // skipped — but the geom must remain robust. (The full label render is
+    // exercised in the live `plot-box` example.)
+    expect(() =>
+      plot({ data: fixture.threeGroups(), width: 400, height: 300 })
+        .layer(boxplot({ x: "group", y: "value" }, { showCounts: true, points: "none" }))
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  test("varwidth doesn't throw and stays valid for unequal group sizes", () => {
+    const data: Obs[] = [];
+    for (let i = 0; i < 30; i++) data.push({ group: "A", value: Math.sin(i) });
+    for (let i = 0; i < 5; i++) data.push({ group: "B", value: Math.cos(i) });
+    expect(() =>
+      plot({ data, width: 320, height: 240 })
+        .layer(boxplot({ x: "group", y: "value" }, { varwidth: true, points: "none" }))
+        .toSVG(),
+    ).not.toThrow();
+  });
+
+  test("compileHitTest emits one hit per non-empty bucket at (bandCenter, median)", () => {
+    const data = fixture.threeGroups();
+    const xAes = resolveAes<Obs, unknown>("group");
+    const yAes = resolveAes<Obs, unknown>("value");
+    const xScale = buildPositionScale(xAes, data, [0, 300], { type: "band", padding: 0 });
+    const yScale = buildPositionScale(yAes, data, [200, 0]);
+    const scales: ScaleBundle = { x: xScale, y: yScale };
+    const ctx: CompileContext<Obs> = {
+      data,
+      scales,
+      plot: createFrame({ x: 50, y: 30, width: 300, height: 200 }),
+      theme: themeDefault,
+      atlas: undefined,
+    };
+    const geom = boxplot<Obs>({ x: "group", y: "value" });
+    const hits = geom.compileHitTest!(ctx)!;
+    expect(hits.geomKind).toBe("boxplot");
+    expect(hits.dataIndex.length).toBe(3);
+    // Each hit's seriesKey should match the category when not dodging.
+    expect(new Set(hits.seriesKey)).toEqual(new Set(["A", "B", "C"]));
+    // Hit positions should fall inside the plot frame.
+    for (let i = 0; i < hits.dataIndex.length; i++) {
+      expect(hits.positions[i * 2]).toBeGreaterThanOrEqual(50);
+      expect(hits.positions[i * 2]).toBeLessThanOrEqual(50 + 300);
+      expect(hits.positions[i * 2 + 1]).toBeGreaterThanOrEqual(30);
+      expect(hits.positions[i * 2 + 1]).toBeLessThanOrEqual(30 + 200);
+    }
+    // Channels expose median + category synth accessors.
+    const yAesSynth = hits.channels.y!;
+    expect(typeof yAesSynth.fn(data[0]!, 0)).toBe("number");
+  });
+
+  test("fillAlpha: 0 produces outline-only boxes", () => {
+    expect(() =>
+      plot({ data: fixture.threeGroups(), width: 320, height: 240 })
+        .layer(boxplot({ x: "group", y: "value" }, { fillAlpha: 0, points: "none" }))
+        .toSVG(),
+    ).not.toThrow();
+  });
+});
+
+describe("boxplot() — GPU hover emphasis (P5-T3 Gap 1)", () => {
+  function makeCtx(data: Obs[], emphasis = true): CompileContext<Obs> {
+    const xAes = resolveAes<Obs, unknown>("group");
+    const yAes = resolveAes<Obs, unknown>("value");
+    const xScale = buildPositionScale(xAes, data, [0, 300], { type: "band", padding: 0 });
+    const yScale = buildPositionScale(yAes, data, [200, 0]);
+    const scales: ScaleBundle = { x: xScale, y: yScale };
+    return {
+      data,
+      scales,
+      plot: createFrame({ x: 50, y: 30, width: 300, height: 200 }),
+      theme: themeDefault,
+      atlas: undefined,
+      emphasisBase: emphasis ? geomEmphasisBase(0) : undefined,
+    };
+  }
+
+  test("tagging present + every primitive of a single box shares ONE key", () => {
+    // smallSample is one bucket ("A") with raw-point overlay, outliers, mean:
+    // exercises rect + median polyline + whisker polylines + circle dots.
+    const data = fixture.smallSample();
+    const geom = boxplot<Obs>({ x: "group", y: "value" }, { mean: true, points: "always" });
+    const { layer, keys } = makeKeyCapture();
+    for (const b of geom.compile(makeCtx(data))) b.addTo(layer as never);
+    const nonzero = keys.filter((k): k is number => k !== undefined && k >= 1);
+    expect(nonzero.length).toBeGreaterThan(0); // tagging present
+    // Whole-entity invariant: a single bucket → exactly one distinct key, the
+    // resolver's key for bucketIndex 0.
+    const expected = emphasisKeyFor(geomEmphasisBase(0), 0);
+    expect(new Set(nonzero)).toEqual(new Set([expected]));
+  });
+
+  test("tagging is stable across hover (compile no longer reads ctx.hovered)", () => {
+    const data = fixture.threeGroups();
+    const geom = boxplot<Obs>({ x: "group", y: "value" }, { points: "none" });
+    const cap1 = makeKeyCapture();
+    for (const b of geom.compile(makeCtx(data))) b.addTo(cap1.layer as never);
+    const cap2 = makeKeyCapture();
+    for (const b of geom.compile({
+      ...makeCtx(data),
+      hovered: { geomKind: "boxplot", dataIndex: 1, data, x: 0, y: 0 },
+    }))
+      b.addTo(cap2.layer as never);
+    expect(cap2.keys).toEqual(cap1.keys);
+  });
+
+  test("emphasisResolution maps a hit's dataIndex (bucketIndex) to the tagged key", () => {
+    const data = fixture.threeGroups();
+    const geom = boxplot<Obs>({ x: "group", y: "value" });
+    const res = geom.emphasisResolution!(makeCtx(data))!;
+    expect(res.geomKind).toBe("boxplot");
+    expect(res.resolve({ geomKind: "boxplot", dataIndex: 2, data, x: 0, y: 0 })).toBe(
+      emphasisKeyFor(geomEmphasisBase(0), 2),
+    );
+    // A hit from another geom is not ours.
+    expect(res.resolve({ geomKind: "violin", dataIndex: 0, data, x: 0, y: 0 })).toBeNull();
+  });
+
+  test("no emphasisBase (SSR/SVG) → boxes untagged, no resolver key", () => {
+    const data = fixture.threeGroups();
+    const geom = boxplot<Obs>({ x: "group", y: "value" }, { points: "none" });
+    const { layer, keys } = makeKeyCapture();
+    for (const b of geom.compile(makeCtx(data, false))) b.addTo(layer as never);
+    expect(keys.every((k) => k === undefined)).toBe(true);
+    expect(geom.emphasisResolution!(makeCtx(data, false))).toBeNull();
+  });
+});