insomni-plot 0.1.0-alpha.0

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

@@ -0,0 +1,85 @@
+import type { Color } from "insomni";
+import { type KdeBandwidth, type KdeKernel, type QuantileMethod, type WhiskerRule } from "../../stats/index.ts";
+import type { Aes } from "../aes.ts";
+import type { Geom } from "./types.ts";
+import type { PointsMode } from "./boxplot.ts";
+import { type DensityScale } from "./_distribution.ts";
+export interface ViolinChannels<T> {
+    x: Aes<T, string | number | Date>;
+    /**
+     * Numeric value axis 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>;
+    color?: Aes<T, unknown>;
+}
+export type ViolinScale = DensityScale;
+export type ViolinInner = "box" | "quartile" | "stick" | "none";
+export interface ViolinOptions {
+    orientation?: "x" | "y";
+    /** Violin width as a fraction of the bandwidth (or grouped inner bandwidth). Default `0.9`. */
+    width?: number;
+    /** KDE bandwidth — number, `"silverman"` (default), or `"scott"`. */
+    bandwidth?: KdeBandwidth;
+    /** KDE evaluation grid size. Default `64`. */
+    gridSize?: number;
+    /** KDE kernel. Default `"gaussian"`. */
+    kernel?: KdeKernel;
+    /** Clip KDE to data range (true, default) or pad outward by ~3 bandwidths. */
+    trim?: boolean;
+    /**
+     * Width-normalization mode.
+     *
+     * - `"width"` (default) — each violin uses its full allotted width; shapes
+     *   are easy to compare but **areas are misleading**.
+     * - `"area"` — density scaled relative to the global max so areas are
+     *   comparable across groups (groups with low n look skinny).
+     * - `"count"` — area scales with sample size (bigger n → wider violin).
+     */
+    scale?: ViolinScale;
+    /**
+     * Inner annotation drawn on top of the violin.
+     *
+     * - `"none"` (default) — bare KDE polygon, like ggplot's `geom_violin`.
+     * - `"box"` — slim box plot with median, IQR, whiskers.
+     * - `"quartile"` — three horizontal/vertical lines at Q1, median, Q3.
+     * - `"stick"` — single line at the median only.
+     */
+    inner?: ViolinInner;
+    /** When to overlay raw jittered points. See `BoxplotOptions["points"]`. */
+    points?: PointsMode;
+    pointsThreshold?: number;
+    pointJitter?: number;
+    pointRadius?: number;
+    jitterSeed?: number;
+    /** Box stats: whisker rule when `inner: "box"`. Default `1.5`. */
+    whisker?: WhiskerRule;
+    /** Box stats: quantile method. Default `"type-7"`. */
+    quantile?: QuantileMethod;
+    fill?: Color;
+    stroke?: Color;
+    strokeWidth?: number;
+    /** Color of inner annotation marks. Defaults to `stroke` (or theme text). */
+    innerStroke?: Color;
+    /** Stroke width for the embedded mini-box body. Default `1`. */
+    innerStrokeWidth?: number;
+    /** Inner-band padding for grouped (color-split) layout. Default `0.05`. */
+    groupPadding?: number;
+    /**
+     * Render an `n=<count>` label per group, aligned with the band axis just
+     * outside the plot frame. Useful when the categorical labels alone hide
+     * sample-size differences.
+     */
+    showCounts?: boolean;
+    /**
+     * Pixel offset of the count labels from the plot frame edge along the
+     * band-axis perpendicular. Increase to clear longer tick labels. Default
+     * `28` (vertical) / `32` (horizontal).
+     */
+    countsOffset?: number;
+    countsFontSize?: number;
+    countsColor?: Color;
+    label?: string;
+}
+export declare function violin<T>(channels: ViolinChannels<T>, options?: ViolinOptions): Geom<T>;

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

@@ -0,0 +1,187 @@
+// @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 { violin } from "./violin.ts";
+import { emphasisKeyFor, geomEmphasisBase } from "./emphasis.ts";
+import type { CompileContext } from "./types.ts";
+
+// Fake Layer recording the emphasisKey of every primitive a violin composites
+// (KDE polygon + outline polyline + inner box rect/polylines + point overlay).
+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 = {
+  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 < 50; i++) {
+        out.push({ group: name, value: mu + (rand() - 0.5) * 0.3 });
+      }
+    }
+    return out;
+  },
+  bimodal: (): Obs[] => {
+    const out: Obs[] = [];
+    for (let i = 0; i < 30; i++) out.push({ group: "A", value: 0.2 + i * 0.005 });
+    for (let i = 0; i < 30; i++) out.push({ group: "A", value: 0.8 + i * 0.005 });
+    return out;
+  },
+};
+
+// ============ Tests ============
+describe("violin()", () => {
+  test("renders a polygon per group to SVG", () => {
+    const svg = plot({ data: fixture.threeGroups(), width: 480, height: 320 })
+      .layer(violin({ x: "group", y: "value" }))
+      .toSVG();
+    expect(svg).toBeInstanceOf(SVGSVGElement);
+    // SVG renderer tessellates filled polygons into <path> elements.
+    const polygons = svg.querySelectorAll("polygon");
+    expect(polygons.length).toBeGreaterThan(0);
+  });
+
+  test("respects gridSize via point-count of polygon (2 * gridSize vertices)", () => {
+    // We don't have a direct vertex-count probe through SVG, but we can verify
+    // it doesn't crash on small grids and renders non-empty output.
+    const svg = plot({ data: fixture.bimodal(), width: 320, height: 240 })
+      .layer(violin({ x: "group", y: "value" }, { gridSize: 16 }))
+      .toSVG();
+    expect(svg.querySelectorAll("polygon").length).toBeGreaterThan(0);
+  });
+
+  test("'inner: none' suppresses the embedded box-and-stick", () => {
+    const svgWith = plot({ data: fixture.threeGroups(), width: 320, height: 240 })
+      .layer(violin({ x: "group", y: "value" }, { inner: "box", points: "none" }))
+      .toSVG();
+    const svgNone = plot({ data: fixture.threeGroups(), width: 320, height: 240 })
+      .layer(violin({ x: "group", y: "value" }, { inner: "none", points: "none" }))
+      .toSVG();
+    // Inner "box" mode draws additional <rect> + <line> elements.
+    const withRects = svgWith.querySelectorAll("rect").length;
+    const noneRects = svgNone.querySelectorAll("rect").length;
+    expect(withRects).toBeGreaterThan(noneRects);
+  });
+
+  test("does not throw on degenerate samples (n=1, all-equal)", () => {
+    expect(() =>
+      plot({ data: [{ group: "A", value: 5 }] as Obs[] })
+        .layer(violin({ x: "group", y: "value" }))
+        .toSVG({ width: 200, height: 200 }),
+    ).not.toThrow();
+    expect(() =>
+      plot({ data: [3, 3, 3, 3].map((v) => ({ group: "A", value: v })) as Obs[] })
+        .layer(violin({ x: "group", y: "value" }))
+        .toSVG({ width: 200, height: 200 }),
+    ).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 = violin<Obs>({ x: "group", y: "value" });
+    const hits = geom.compileHitTest!(ctx)!;
+    expect(hits.geomKind).toBe("violin");
+    expect(hits.dataIndex.length).toBe(3);
+    expect(new Set(hits.seriesKey)).toEqual(new Set(["A", "B", "C"]));
+  });
+
+  test("scale: 'count' / 'area' / 'width' all render", () => {
+    for (const mode of ["width", "area", "count"] as const) {
+      const svg = plot({ data: fixture.threeGroups(), width: 400, height: 300 })
+        .layer(violin({ x: "group", y: "value" }, { scale: mode }))
+        .toSVG();
+      expect(svg).toBeInstanceOf(SVGSVGElement);
+    }
+  });
+});
+
+describe("violin() — 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 violin shares ONE key", () => {
+    const data = fixture.bimodal(); // one bucket "A"
+    const geom = violin<Obs>({ x: "group", y: "value" }, { inner: "box", 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);
+    const expected = emphasisKeyFor(geomEmphasisBase(0), 0);
+    expect(new Set(nonzero)).toEqual(new Set([expected]));
+  });
+
+  test("emphasisResolution maps a hit's dataIndex (bucketIndex) to the tagged key", () => {
+    const data = fixture.threeGroups();
+    const geom = violin<Obs>({ x: "group", y: "value" });
+    const res = geom.emphasisResolution!(makeCtx(data))!;
+    expect(res.geomKind).toBe("violin");
+    expect(res.resolve({ geomKind: "violin", dataIndex: 1, data, x: 0, y: 0 })).toBe(
+      emphasisKeyFor(geomEmphasisBase(0), 1),
+    );
+    expect(res.resolve({ geomKind: "boxplot", dataIndex: 0, data, x: 0, y: 0 })).toBeNull();
+  });
+
+  test("no emphasisBase (SSR/SVG) → violins untagged, no resolver key", () => {
+    const data = fixture.threeGroups();
+    const geom = violin<Obs>({ x: "group", y: "value" });
+    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();
+  });
+});