@inflexa-ai/harness 0.42.1 → 0.43.0

package/dist/report-render/figures/upset.js

@@ -0,0 +1,316 @@
+/**
+ * The UpSet plot: the intersections of some sets, as upset.app, UpSetR, and ComplexHeatmap draw them.
+ *
+ * The figure reads one row for each member of each set: the `x` column names the element, and the `group`
+ * column names the set. Three grids line up:
+ *
+ * - The top grid draws the size of each intersection as a bar, with its count over the bar.
+ * - The middle grid draws the dot matrix: one column for each intersection and one row for each set. A dark
+ *   dot marks each member set of the intersection, a light dot marks each other set, and a line joins the
+ *   member dots of the column.
+ * - The left grid draws the size of each set as a bar that grows to the left, on the rows of the matrix. The
+ *   set names sit between these bars and the matrix.
+ *
+ * The figure computes two named summaries, and each one reads the rows of the bound table alone:
+ *
+ * - The size of a set: the count of its distinct elements.
+ * - The exact intersection of an element: the combination of every set that holds it. The size of an
+ *   intersection is the count of its elements, thus each element counts in one intersection alone.
+ *
+ * The sets sort by size, the largest at the top, and a tie keeps the first appearance. The intersections sort
+ * by size, largest first, then by degree, smallest first, then by the set order of their members. The largest
+ * intersections draw alone past the cap, and the title under the matrix states the count of the others.
+ *
+ * The dots and the count text of one column must fit the column at each export size, thus one media rule for
+ * each export size states the dot size and the turn of the count text there.
+ */
+import { err, ok } from "neverthrow";
+import { CHART_BODY_PX, CHART_EXPORT_SIZES, CHART_INK, CHART_PAGE_TEXT_PX, CHART_PAGE_WIDTH_PX } from "../design.js";
+import { axisNameFields, chartProblem, demandedColumn, valueAxis } from "./common.js";
+/**
+ * The most sets that one figure draws. Each set takes one row of the matrix, and the rows of twelve sets hold
+ * one line of the column-export text each.
+ */
+export const UPSET_SET_LIMIT = 12;
+/** The most intersections that one figure draws. The largest ones draw, and the title states the count of the others. */
+export const UPSET_INTERSECTION_LIMIT = 30;
+/** The titles of the two value axes. */
+const INTERSECTION_TITLE = "Intersection size";
+const SET_TITLE = "Set size";
+/** The light dot of a set that is not a member of the intersection. */
+const ABSENT_DOT_COLOR = "#e0e0e0";
+/** The text between the member names of one intersection. */
+const MEMBER_SEPARATOR = " & ";
+/** The places of the grids, in percent of the chart: the top margin, the gap between the bars and the matrix, and the left and right margins. */
+const TOP_PCT = 9;
+const GAP_PCT = 3;
+const SIDE_PCT = 3;
+/** The width of the set-size bars, in percent of the chart. */
+const SET_BAR_PCT = 16;
+/** The height of one set row, and of the whole matrix, at most, in percent of the chart. */
+const ROW_MAX_PCT = 7;
+const MATRIX_MAX_PCT = 50;
+/** The share of the smaller band of one cell that its dot fills, and the bounds of a dot, in pixels. */
+const DOT_SHARE = 0.7;
+const DOT_MIN_PX = 2;
+const DOT_MAX_PX = 16;
+/** The width of the line that joins the member dots, as a share of the dot size, and its smallest width in pixels. */
+const JOIN_SHARE = 0.25;
+const JOIN_MIN_PX = 1;
+/** The width of one character of the chart text, as a share of the text size. The layout estimates a name width with it. */
+const CHARACTER_SHARE = 0.6;
+/** The gap between a set name and the matrix, and between the name and the set bars, in pixels. */
+const NAME_GAP_PX = 8;
+/** The lines of text under the matrix: the tick labels and the title of the set bars, with their gaps. */
+const BOTTOM_LINES = 3.2;
+/** The UpSet module: the element and the set. */
+export const UPSET_FIGURE = { reads: new Set(["x", "group"]), derive: deriveUpset };
+/** True when a cell holds no text. */
+function emptyCell(cell) {
+    return cell === undefined || String(cell).trim() === "";
+}
+/**
+ * The set sizes and the exact intersections of one membership table.
+ *
+ * A row with an empty set cell names an element in no set, and it adds nothing: the empty intersection draws
+ * no column. The error is the detail of the refusal.
+ */
+export function upsetSummary(rows, element, set) {
+    const setsOf = new Map();
+    const sizes = new Map();
+    for (const row of rows) {
+        const setCell = row[set];
+        if (emptyCell(setCell))
+            continue;
+        const setName = String(setCell).trim();
+        if (emptyCell(row[element])) {
+            return err(`A row of the set "${setName}" names no element in the "${element}" column.`);
+        }
+        const elementName = String(row[element]).trim();
+        const held = setsOf.get(elementName) ?? new Set();
+        if (held.has(setName)) {
+            return err(`The element "${elementName}" is a member of the set "${setName}" in two rows. The table holds one row for each member of each set.`);
+        }
+        held.add(setName);
+        setsOf.set(elementName, held);
+        sizes.set(setName, (sizes.get(setName) ?? 0) + 1);
+    }
+    if (sizes.size === 0) {
+        return err(`The table names no set in the "${set}" column, thus the figure has no intersection to draw.`);
+    }
+    if (sizes.size > UPSET_SET_LIMIT) {
+        return err(`The table names ${sizes.size} sets. An upset figure draws ${UPSET_SET_LIMIT} sets at most, thus a table of fewer sets serves the reader.`);
+    }
+    // The map keeps the first appearance, and the sort is stable, thus a tie keeps that order.
+    const sets = [...sizes.entries()].map(([name, size]) => ({ name, size })).sort((a, b) => b.size - a.size);
+    const places = new Map(sets.map((entry, place) => [entry.name, place]));
+    const counts = new Map();
+    for (const held of setsOf.values()) {
+        const members = [...held].map((name) => places.get(name) ?? -1).sort((a, b) => a - b);
+        const key = members.join(",");
+        const entry = counts.get(key) ?? { members, size: 0 };
+        entry.size += 1;
+        counts.set(key, entry);
+    }
+    const intersections = [...counts.values()].sort((a, b) => b.size - a.size || a.members.length - b.members.length || compareMembers(a.members, b.members));
+    return ok({ sets, intersections });
+}
+/** Compare two member lists of one degree by the set order: the list whose first different set comes first sorts first. */
+function compareMembers(a, b) {
+    for (let place = 0; place < Math.min(a.length, b.length); place += 1) {
+        if (a[place] !== b[place])
+            return a[place] - b[place];
+    }
+    return a.length - b.length;
+}
+/** The page box and the box of each export size. */
+const PAGE_BOX = { widthPx: CHART_PAGE_WIDTH_PX, heightPx: CHART_BODY_PX, textPx: CHART_PAGE_TEXT_PX };
+const EXPORT_SIZES = [CHART_EXPORT_SIZES.single, CHART_EXPORT_SIZES.double, CHART_EXPORT_SIZES.slide];
+/**
+ * The places of the grids for some sets, and set names of some length.
+ *
+ * The set names take a band between the set bars and the matrix, and the tick labels with the title of the set
+ * bars take a band under the matrix. Each band holds its text at the page and at the single column, thus the
+ * percent layout serves each export.
+ */
+function upsetLayout(setCount, longestName) {
+    const boxes = [PAGE_BOX, CHART_EXPORT_SIZES.single];
+    const namePct = Math.max(...boxes.map((box) => ((longestName * box.textPx * CHARACTER_SHARE + 2 * NAME_GAP_PX) / box.widthPx) * 100));
+    const bottomPct = Math.max(...boxes.map((box) => ((BOTTOM_LINES * box.textPx + NAME_GAP_PX) / box.heightPx) * 100));
+    const rowPct = Math.min(ROW_MAX_PCT, MATRIX_MAX_PCT / setCount);
+    return {
+        matrixLeft: rounded(SIDE_PCT + SET_BAR_PCT + namePct),
+        matrixTop: rounded(100 - bottomPct - rowPct * setCount),
+        matrixBottom: rounded(bottomPct),
+        rowPct,
+    };
+}
+/** The dot size of one box: a share of the smaller band of one cell, within the bounds. */
+function dotPx(layout, columns, box) {
+    const column = (((100 - layout.matrixLeft - SIDE_PCT) / 100) * box.widthPx) / columns;
+    const row = (layout.rowPct / 100) * box.heightPx;
+    return rounded(Math.min(DOT_MAX_PX, Math.max(DOT_MIN_PX, DOT_SHARE * Math.min(column, row))));
+}
+/**
+ * The count text over the intersection bars at one box. A text wider than its column turns upright, thus the
+ * counts of many narrow columns stand side by side and none hides the next.
+ */
+function countLabel(layout, columns, digits, box) {
+    const column = (((100 - layout.matrixLeft - SIDE_PCT) / 100) * box.widthPx) / columns;
+    const upright = digits * box.textPx * CHARACTER_SHARE > column;
+    return upright
+        ? { show: true, position: "top", color: CHART_INK, rotate: 90, align: "left", verticalAlign: "middle", distance: 4 }
+        : { show: true, position: "top", color: CHART_INK, distance: 2 };
+}
+/** One layout percentage, rounded, thus a float residue never reaches the option. */
+function rounded(value) {
+    return Math.round(value * 1e4) / 1e4;
+}
+/** A percent of the chart as the option states it. */
+function pct(value) {
+    return `${rounded(value)}%`;
+}
+function deriveUpset(block, rows, context) {
+    const source = { blockId: context.blockId, rows, ...(context.columns !== undefined ? { columns: context.columns } : {}) };
+    const encoding = block.encoding ?? {};
+    const element = demandedColumn("upset", encoding, "x", source);
+    if (element.isErr())
+        return err(element.error);
+    const set = demandedColumn("upset", encoding, "group", source);
+    if (set.isErr())
+        return err(set.error);
+    if (rows.length === 0) {
+        return err(chartProblem(context.blockId, "The upset figure has no rows. It needs one row for each member of each set."));
+    }
+    const summary = upsetSummary(rows, element.value, set.value);
+    if (summary.isErr())
+        return err(chartProblem(context.blockId, summary.error));
+    const { sets, intersections } = summary.value;
+    const drawn = intersections.slice(0, UPSET_INTERSECTION_LIMIT);
+    const hidden = intersections.length - drawn.length;
+    const setNames = sets.map((entry) => entry.name);
+    const columnNames = drawn.map((entry) => entry.members.map((place) => setNames[place]).join(MEMBER_SEPARATOR));
+    const layout = upsetLayout(sets.length, Math.max(...setNames.map((name) => name.length)));
+    const digits = Math.max(...drawn.map((entry) => String(entry.size).length));
+    const members = [];
+    const absent = [];
+    const joins = [];
+    for (const [column, entry] of drawn.entries()) {
+        const held = new Set(entry.members);
+        for (let row = 0; row < sets.length; row += 1) {
+            (held.has(row) ? members : absent).push([column, row]);
+        }
+        if (entry.members.length > 1) {
+            joins.push({
+                coords: [
+                    [column, entry.members[0]],
+                    [column, entry.members[entry.members.length - 1]],
+                ],
+            });
+        }
+    }
+    const pageDot = dotPx(layout, drawn.length, PAGE_BOX);
+    const matrixGrid = { left: pct(layout.matrixLeft), right: pct(SIDE_PCT), top: pct(layout.matrixTop), bottom: pct(layout.matrixBottom) };
+    const hiddenAxis = { axisLabel: { show: false }, axisTick: { show: false }, axisLine: { show: false } };
+    const series = [
+        {
+            id: "intersections",
+            type: "bar",
+            xAxisIndex: 0,
+            yAxisIndex: 0,
+            barCategoryGap: "30%",
+            itemStyle: { color: CHART_INK },
+            label: countLabel(layout, drawn.length, digits, PAGE_BOX),
+            tooltip: { formatter: "{b}: {c}" },
+            data: drawn.map((entry) => entry.size),
+        },
+        {
+            id: "sets",
+            type: "bar",
+            xAxisIndex: 2,
+            yAxisIndex: 2,
+            barCategoryGap: "40%",
+            itemStyle: { color: CHART_INK },
+            tooltip: { formatter: "{b}: {c}" },
+            data: sets.map((entry) => entry.size),
+        },
+        {
+            id: "absent",
+            type: "scatter",
+            xAxisIndex: 1,
+            yAxisIndex: 1,
+            silent: true,
+            symbolSize: pageDot,
+            itemStyle: { color: ABSENT_DOT_COLOR },
+            z: 1,
+            data: absent,
+        },
+        {
+            id: "joins",
+            type: "lines",
+            coordinateSystem: "cartesian2d",
+            xAxisIndex: 1,
+            yAxisIndex: 1,
+            silent: true,
+            lineStyle: { color: CHART_INK, width: joinPx(pageDot), opacity: 1 },
+            z: 2,
+            data: joins,
+        },
+        {
+            id: "members",
+            type: "scatter",
+            xAxisIndex: 1,
+            yAxisIndex: 1,
+            silent: true,
+            symbolSize: pageDot,
+            itemStyle: { color: CHART_INK, opacity: 1 },
+            z: 3,
+            data: members,
+        },
+    ];
+    return ok({
+        tooltip: { trigger: "item" },
+        legend: { show: false },
+        grid: [
+            { left: matrixGrid.left, right: matrixGrid.right, top: pct(TOP_PCT), bottom: pct(100 - layout.matrixTop + GAP_PCT) },
+            matrixGrid,
+            { left: pct(SIDE_PCT), width: pct(SET_BAR_PCT), top: matrixGrid.top, bottom: matrixGrid.bottom },
+        ],
+        xAxis: [
+            { type: "category", gridIndex: 0, data: columnNames, axisLabel: { show: false }, axisTick: { show: false } },
+            {
+                type: "category",
+                gridIndex: 1,
+                data: columnNames,
+                ...hiddenAxis,
+                ...(hidden > 0 ? { ...axisNameFields("x", `Intersections: ${drawn.length} of ${intersections.length} shown`), nameGap: NAME_GAP_PX } : {}),
+            },
+            { ...valueAxis("x", SET_TITLE), gridIndex: 2, inverse: true, splitNumber: 2, minInterval: 1, axisLabel: { rotate: 0 } },
+        ],
+        yAxis: [
+            { ...valueAxis("y", INTERSECTION_TITLE), gridIndex: 0, splitNumber: 3, minInterval: 1 },
+            { type: "category", gridIndex: 1, inverse: true, data: setNames, axisTick: { show: false }, axisLine: { show: false } },
+            { type: "category", gridIndex: 2, inverse: true, data: setNames, show: false },
+        ],
+        series,
+        media: EXPORT_SIZES.map((size) => {
+            const dot = dotPx(layout, drawn.length, size);
+            return {
+                query: { minWidth: size.widthPx, maxWidth: size.widthPx, minHeight: size.heightPx, maxHeight: size.heightPx },
+                option: {
+                    series: [
+                        { label: countLabel(layout, drawn.length, digits, size) },
+                        {},
+                        { symbolSize: dot },
+                        { lineStyle: { width: joinPx(dot) } },
+                        { symbolSize: dot },
+                    ],
+                },
+            };
+        }),
+    });
+}
+/** The width of the line that joins the member dots of one column, at one dot size. */
+function joinPx(dot) {
+    return rounded(Math.max(JOIN_MIN_PX, dot * JOIN_SHARE));
+}

package/dist/report-render/figures/volcano.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The volcano figure, as DESeq2 papers and EnhancedVolcano draw it: the effect on x, the transformed p on y,
+ * the null points in gray under the two signal sides, and the names of the most significant signal genes.
+ *
+ * - The null points draw under the signal points, in gray and smaller. The down side takes the blue of the
+ *   palette and the up side takes its vermilion.
+ * - The legend names each side with the count of its points.
+ * - The ten most significant signal points that carry a name show it. The derivation places each name clear of
+ *   the other names and of the points, with a leader line to its point. The names place again for the plot and
+ *   the text size of each export, and a name that finds no place clear of the earlier names does not print
+ *   there.
+ * - The effect axis is symmetric around zero, thus the two sides read at one scale.
+ * - A row with no p draws no point and counts on no side.
+ * - A row whose stored p is 0 draws an upward triangle at the top of the plotted range, on the side of its
+ *   effect. It counts on that side, and it takes a name before each finite p.
+ *
+ * The classification and the guides read one pair of cuts, the declared thresholds or the preset defaults.
+ * Thus the color split lands on the drawn lines. The points come from the composition machinery, thus a
+ * table of many thousand genes reads the shared payload.
+ */
+import type { FigureModule } from "./index.js";
+/** The count of signal points that show their name. */
+export declare const VOLCANO_LABEL_COUNT = 10;
+/** The volcano figure module. */
+export declare const VOLCANO_FIGURE: FigureModule;

package/dist/report-render/figures/volcano.js

@@ -0,0 +1,166 @@
+/**
+ * The volcano figure, as DESeq2 papers and EnhancedVolcano draw it: the effect on x, the transformed p on y,
+ * the null points in gray under the two signal sides, and the names of the most significant signal genes.
+ *
+ * - The null points draw under the signal points, in gray and smaller. The down side takes the blue of the
+ *   palette and the up side takes its vermilion.
+ * - The legend names each side with the count of its points.
+ * - The ten most significant signal points that carry a name show it. The derivation places each name clear of
+ *   the other names and of the points, with a leader line to its point. The names place again for the plot and
+ *   the text size of each export, and a name that finds no place clear of the earlier names does not print
+ *   there.
+ * - The effect axis is symmetric around zero, thus the two sides read at one scale.
+ * - A row with no p draws no point and counts on no side.
+ * - A row whose stored p is 0 draws an upward triangle at the top of the plotted range, on the side of its
+ *   effect. It counts on that side, and it takes a name before each finite p.
+ *
+ * The classification and the guides read one pair of cuts, the declared thresholds or the preset defaults.
+ * Thus the color split lands on the drawn lines. The points come from the composition machinery, thus a
+ * table of many thousand genes reads the shared payload.
+ */
+import { err, ok } from "neverthrow";
+import { channelColumn } from "../../contracts/report-blocks.js";
+import { expandVolcano, VOLCANO_EFFECT_THRESHOLD, volcanoAxisTitles } from "../chart-presets.js";
+import { CHART_PALETTE, MUTED_CHART_COLOR } from "../design.js";
+import { transformColumn } from "./common.js";
+import { axisOf, BELOW_RESOLUTION_SYMBOL, BELOW_RESOLUTION_SYMBOL_PX, BELOW_RESOLUTION_TOOLTIP, belowResolutionHeight, belowResolutionRows, countText, DENSE_NULL_OPACITY, DENSE_NULL_SYMBOL_PX, DENSE_NULL_Z, DENSE_SIGNAL_OPACITY, DENSE_SIGNAL_SYMBOL_PX, demandedChannel, largest, niceCeiling, plottedValues, pointLayer, POINT_NAMES, pointNameSeries, seriesOf, sizedSeries, symmetricRange, } from "./dense.js";
+import { placeLeaderNames } from "./label-room.js";
+/** The count of signal points that show their name. */
+export const VOLCANO_LABEL_COUNT = 10;
+/** The sides of a point where a volcano name sits, in the order that the figure tries them. */
+const VOLCANO_NAME_SIDES = ["right", "left", "top"];
+/** The color of the down side and of the up side. The null side takes the muted color. */
+const SIDE_COLORS = [CHART_PALETTE[0], CHART_PALETTE[1]];
+/** The members of a volcano block that the figure reads. */
+const READS = new Set(["x", "y", "label"]);
+/**
+ * The volcano classification with the count of each category in its name.
+ *
+ * The counts read the plotted pair of each row through the preset rule, which is the rule that splits the
+ * series. Thus each name counts the points of its own series.
+ */
+function countedClassification(base, xs, ys) {
+    const counts = new Map(base.categories.map((category) => [category.name, 0]));
+    for (let index = 0; index < xs.length; index += 1) {
+        const category = base.categoryOf(xs[index], ys[index], index);
+        if (category !== undefined)
+            counts.set(category, (counts.get(category) ?? 0) + 1);
+    }
+    const names = new Map(base.categories.map((category) => [category.name, `${category.name} (${countText(counts.get(category.name) ?? 0)})`]));
+    return {
+        categories: base.categories.map((category) => ({ ...category, name: names.get(category.name) ?? category.name })),
+        categoryOf: (x, y, index) => {
+            const category = base.categoryOf(x, y, index);
+            return category === undefined ? undefined : names.get(category);
+        },
+        rule: base.rule,
+    };
+}
+/**
+ * The rows whose point shows its name: the most significant signal rows that carry a name, at most
+ * `VOLCANO_LABEL_COUNT`. The order reads the plotted p, a stored zero first, and a tie keeps the order of the
+ * rows.
+ */
+function labeledRows(rows, labelColumn, base, xs, ys, zeros) {
+    if (labelColumn === undefined)
+        return [];
+    const signal = new Set(base.categories.filter((category) => !category.muted).map((category) => category.name));
+    const candidates = [];
+    for (let index = 0; index < rows.length; index += 1) {
+        const category = base.categoryOf(xs[index], ys[index], index);
+        const name = rows[index][labelColumn];
+        if (category !== undefined && signal.has(category) && name !== undefined && String(name).trim() !== "")
+            candidates.push(index);
+    }
+    const rank = (index) => (zeros.has(index) ? Number.POSITIVE_INFINITY : (ys[index] ?? 0));
+    candidates.sort((a, b) => (rank(a) === rank(b) ? a - b : rank(b) - rank(a)));
+    return candidates.slice(0, VOLCANO_LABEL_COUNT);
+}
+function deriveVolcano(block, rows, context) {
+    const encoding = block.encoding ?? {};
+    const x = demandedChannel(context.blockId, "volcano", encoding, "x");
+    if (x.isErr())
+        return err(x.error);
+    const y = demandedChannel(context.blockId, "volcano", encoding, "y");
+    if (y.isErr())
+        return err(y.error);
+    const expansion = expandVolcano(x.value, y.value, encoding, block.thresholds);
+    const base = expansion.classification;
+    const xs = plottedValues(rows, x.value);
+    const pColumn = channelColumn(y.value);
+    const finite = transformColumn(rows, pColumn, "neg_log10");
+    const peak = largest(finite.flatMap((value, index) => (value !== null && xs[index] !== null ? [value] : []))) ?? 0;
+    const zeroRows = belowResolutionRows(rows, pColumn, xs);
+    const zeros = new Set(zeroRows);
+    const zeroY = belowResolutionHeight(peak, base.rule.kind === "volcano" ? base.rule.cut : 0);
+    // A stored zero draws at the top of the plotted range, thus the counts and the names read it there. The
+    // composition reads the transformed column, which drops it, and the figure draws it in a series of its own.
+    const ys = finite.map((value, index) => (zeros.has(index) ? zeroY : value));
+    const counted = countedClassification(base, xs, ys);
+    const composed = context.compose(expansion.composition, { preset: volcanoAxisTitles(x.value), classification: counted });
+    if (composed.isErr())
+        return err(composed.error);
+    const reach = largest(xs.flatMap((value, index) => (value !== null && ys[index] !== null ? [Math.abs(value)] : [])));
+    const effect = block.thresholds?.effect ?? VOLCANO_EFFECT_THRESHOLD;
+    const end = niceCeiling(Math.max(reach ?? 0, effect));
+    const option = composed.value;
+    const labelColumn = encoding.label;
+    const names = labelColumn === undefined
+        ? []
+        : labeledRows(rows, labelColumn, base, xs, ys, zeros).map((index) => ({
+            x: xs[index] ?? 0,
+            y: ys[index] ?? 0,
+            text: String(rows[index][labelColumn]),
+        }));
+    const top = zeroRows.length > 0 ? Math.max(peak, zeroY) : peak;
+    // The runtime ends the p axis at its own round number at or past the peak. The round number of the figure
+    // is at or past it too, thus the names measure against a span at least as long as the drawn one.
+    const plot = { x: { min: -end, max: end }, y: { min: 0, max: niceCeiling(top) } };
+    const text = sizedSeries([POINT_NAMES], (frame) => pointNameSeries(names, placeLeaderNames(names, { xs, ys, pointPx: DENSE_SIGNAL_SYMBOL_PX }, plot, VOLCANO_NAME_SIDES, top, frame)));
+    const legend = typeof option.legend === "object" && option.legend !== null ? option.legend : {};
+    return ok({
+        ...option,
+        ...text.member,
+        // The legend names the three sides alone, and never the series of the point names.
+        legend: { ...legend, data: seriesOf(option).map((series) => series.name) },
+        xAxis: { ...axisOf(option, "xAxis"), ...symmetricRange(end) },
+        yAxis: { ...axisOf(option, "yAxis"), min: 0 },
+        series: [
+            ...seriesOf(option).map((series, place) => ({ ...series, ...sideLayer(place, DENSE_SIGNAL_SYMBOL_PX, DENSE_NULL_SYMBOL_PX) })),
+            ...zeroSeries(counted, zeroRows, xs, zeroY, labelColumn === undefined ? undefined : (index) => String(rows[index][labelColumn])),
+            ...text.page,
+        ],
+    });
+}
+/** The style of the points of one side, by the place of the side: the two signal sides, then the null side. */
+function sideLayer(place, signalPx, nullPx) {
+    return place < SIDE_COLORS.length
+        ? pointLayer(SIDE_COLORS[place], signalPx, DENSE_SIGNAL_OPACITY)
+        : pointLayer(MUTED_CHART_COLOR, nullPx, DENSE_NULL_OPACITY, DENSE_NULL_Z);
+}
+/**
+ * The series of the stored zeros: one series for each side that holds one, under the name and in the style of
+ * that side, with the upward triangle at the drawn height. The series follow the points of the composition,
+ * thus they keep their rows inline and the points still read the shared payload.
+ */
+function zeroSeries(classification, zeroRows, xs, zeroY, nameOf) {
+    return classification.categories.flatMap((category, place) => {
+        const data = zeroRows
+            .filter((index) => classification.categoryOf(xs[index], zeroY, index) === category.name)
+            .map((index) => (nameOf === undefined ? [xs[index] ?? 0, zeroY] : { name: nameOf(index), value: [xs[index] ?? 0, zeroY] }));
+        if (data.length === 0)
+            return [];
+        return [
+            {
+                type: "scatter",
+                name: category.name,
+                symbol: BELOW_RESOLUTION_SYMBOL,
+                ...sideLayer(place, BELOW_RESOLUTION_SYMBOL_PX, BELOW_RESOLUTION_SYMBOL_PX),
+                tooltip: BELOW_RESOLUTION_TOOLTIP,
+                data,
+            },
+        ];
+    });
+}
+/** The volcano figure module. */
+export const VOLCANO_FIGURE = { reads: READS, derive: deriveVolcano };

package/dist/report-render/hybrid-svg.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The hybrid SVG of a dense chart: the vector axes, text, legend, and guides, over one raster layer of the points.
+ *
+ * A chart past the point bound of the export gets no staged SVG, because a vector file of many thousands of
+ * points is too large. The page builds its SVG on a click instead. It draws the export option with the SVG
+ * renderer and the point data emptied, it draws the points alone on a canvas at 300 DPI, and it puts the canvas
+ * image into the SVG at the rectangle of the grid, under the vector marks. The server has no canvas, thus only
+ * the page builds this file.
+ *
+ * The rule of a point layer and the composition of the file hold one rule each in two twins: the TypeScript
+ * function and the page function. A shared test vector runs both, thus the two cannot drift in silence. The
+ * option transforms and the two draws exist on the page alone, because the server never builds the file.
+ */
+/** The box of one export in CSS pixels, and in millimeters for a column export. */
+export interface SvgRootSize {
+    readonly widthPx: number;
+    readonly heightPx: number;
+    readonly widthMm?: number;
+    readonly heightMm?: number;
+}
+/** The raster image of the point layer and its rectangle in the pixel space of the SVG. */
+export interface PointLayerImage {
+    readonly href: string;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}
+/**
+ * True when one series draws a point for each row: a `scatter` whose symbol draws and which shows no series
+ * label. A scatter of size zero, or one with a shown label, carries names, and names stay vector text.
+ */
+export declare function isPointLayer(series: unknown): boolean;
+/** True when an option holds a point layer. The page can then build the hybrid SVG of the option. */
+export declare function holdsPointLayer(option: Readonly<Record<string, unknown>>): boolean;
+/**
+ * The SVG text with its root at the millimeter size of a column. The view box keeps the pixel space, thus a
+ * vector editor opens the file at the column width. A size with no millimeter box leaves the root as it is.
+ */
+export declare function millimeterRoot(svg: string, size: SvgRootSize): string;
+/**
+ * The hybrid SVG file: the vector file with one `<image>` element of the point layer, and the root at the
+ * millimeter size.
+ *
+ * The image goes first after the background rectangle, thus each vector mark draws over the points: the axes,
+ * the guides, the names, and the legend. The rectangle of the image is the grid rectangle, and the image
+ * stretches to it, because the raster drew the grid at that rectangle. A text that holds no SVG root passes
+ * through with no image.
+ */
+export declare function composeHybridSvg(svg: string, layer: PointLayerImage, size: SvgRootSize): string;
+/**
+ * The page twin of the point-layer rule and of the composition, and the page build of the hybrid file, as
+ * browser source text.
+ *
+ * `reportHybridSvg(runtime, option, size)` is the entry point. It reads the chart runtime and the document of
+ * the page, and it gives the SVG text, or `null` when the option holds no point layer or the runtime gives no
+ * grid rectangle. The fragment reads `reportExportOption` of the renderer fragment, thus the bootstrap inlines
+ * that fragment first.
+ *
+ * The draws run in this order:
+ *
+ * 1. The vector draw takes the export option with the rows of each point layer emptied. Each point layer keeps
+ *    each row that carries its own label, and two anchors with no symbol at the least and the greatest value of
+ *    each dimension. Thus each axis and each color scale keeps the extent of the full rows.
+ * 2. The rectangle of each grid that holds a point layer comes from the runtime: a halving search of each edge
+ *    with `containPixel` from a point inside the grid. The extent of each continuous axis of such a grid comes
+ *    from `convertFromPixel` at the two edges.
+ * 3. The raster draw takes the export option with the point layers alone. Each grid stands at its measured
+ *    rectangle, each axis holds its measured extent and draws nothing, and the legend, the graphics, and the
+ *    color scales draw nothing. Thus each point lands on the pixel where the vector axes place it.
+ * 4. The composition crops the raster to the union of the grid rectangles at 300 DPI, and it puts the PNG into
+ *    the vector file. The crop reaches past each grid edge by half of the largest symbol of a layer or of a
+ *    visual map of a layer, thus a point on an edge keeps its whole symbol, as it does on the page.
+ */
+export declare const HYBRID_SVG_SOURCE: string;