@inflexa-ai/harness 0.42.2 → 0.43.0

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

@@ -0,0 +1,241 @@
+/**
+ * The PCA of samples, and the shape draw that it shares with the plain scatter.
+ *
+ * The canonical PCA of a bulk study is the DESeq2 `plotPCA` figure: the sample scores on two components, the
+ * condition as the color, a second covariate such as the batch as the symbol, and one unit on x equal to one
+ * unit on y, thus a distance between two samples reads the same in each direction. A small table names each
+ * sample beside its point. The run states the variance of each component, and the declared label of each
+ * column carries it to the axis title.
+ *
+ * The shape draw splits the rows by the pair of their group and their shape. Each split is one series, named
+ * by its group, thus the palette gives the series of one group one color. Each series carries the symbol of
+ * its shape. The legend names each group with a circle, and each shape with its symbol in the ink color, thus
+ * the two keys read apart. A symbol is redundant coding beside the color, thus the figure survives a print in
+ * gray.
+ *
+ * The draw keeps its rows inline. A shape reads for a small table, and a page-side build draws no symbol.
+ */
+import { err, ok } from "neverthrow";
+import { channelColumn, channelOrder, channelTransform } from "../../contracts/report-blocks.js";
+import { CHART_INK, CHART_PALETTE } from "../design.js";
+import { categoricalPalette, categoryName, chartProblem, columnPresent, firstAppearance, POINT_LEGEND_ICON, toNumber, transformColumn, valueAxis, valueAxisTitle, } from "./common.js";
+import { equalRanges, squareLayout } from "./equal-units.js";
+import { NAME_GAP_PX, pointNameSides } from "./label-room.js";
+/**
+ * The symbol of each shape category, in order: the circle, the triangle, the square, the diamond, the
+ * inverted triangle, and the cross. Each one keeps a clear outline at a small size, and past six a reader
+ * no longer tells the symbols apart.
+ */
+export const SHAPE_SYMBOLS = [
+    "circle",
+    "triangle",
+    "rect",
+    "diamond",
+    "path://M0,0L10,0L5,10Z",
+    "path://M3.5,0H6.5V3.5H10V6.5H6.5V10H3.5V6.5H0V3.5H3.5Z",
+];
+/** The symbol size of a point of the shape draw, in pixels. A sample of a PCA is one of few, thus it draws large. */
+export const SHAPED_POINT_PX = 10;
+/** The largest row count of a PCA whose points each carry their name. The DESeq2 workflow labels a small study. */
+export const PCA_LABEL_ROWS = 20;
+/** The share of the longer span that pads each side of a PCA, before the ends round to a tick. */
+const PCA_PAD = 0.04;
+/** The margins of the square of a PCA, in pixels: the tick labels and the title of each axis. */
+const PCA_MARGINS = { top: 16, bottom: 56, left: 64, right: 12 };
+/** The width of the legend band at the right of the square of a PCA, in pixels. */
+const PCA_LEGEND_BAND_PX = 120;
+/** The tooltip of a point with a name, and of a point with none. `{b}` is the name and `{c}` the pair. */
+const NAMED_POINT_TOOLTIP = { trigger: "item", formatter: "{b}<br/>{a}: {c}" };
+const PLAIN_POINT_TOOLTIP = { trigger: "item", formatter: "{a}: {c}" };
+/** The label of each named point of a small PCA. Each point states its own side, and the gap is the one of the place estimate. */
+const POINT_LABEL_FIELDS = { label: { show: true, formatter: "{b}", position: "right", distance: NAME_GAP_PX, color: CHART_INK } };
+const PCA_DRAW = { figure: "pca", equalUnits: true, labelRows: PCA_LABEL_ROWS };
+const SCATTER_DRAW = { figure: "scatter", equalUnits: false, labelRows: 0 };
+/** The PCA of samples. */
+export const PCA_FIGURE = {
+    reads: new Set(["x", "y", "group", "shape", "label"]),
+    derive: (block, rows, context) => deriveShapeDraw(block, rows, context, PCA_DRAW),
+};
+/** The members of a plain scatter that the shape draw does not read beside a shape. */
+const UNSHAPED_MEMBERS = ["color", "size", "low", "high", "facet", "focus"];
+/**
+ * The plain scatter with a `shape` channel.
+ *
+ * The module reads every member of a scatter, thus the refusal of a member that the shape draw cannot draw
+ * names the shape as the cause, and never states that a scatter reads no such member.
+ */
+export const SHAPED_SCATTER_FIGURE = {
+    reads: new Set(["x", "y", "group", "shape", "label", ...UNSHAPED_MEMBERS]),
+    derive: (block, rows, context) => {
+        const encoding = block.encoding ?? {};
+        for (const member of UNSHAPED_MEMBERS) {
+            const declared = member === "focus" ? block.focus : encoding[member];
+            if (declared !== undefined) {
+                const noun = member === "focus" ? "focus" : `"${member}" channel`;
+                return err(chartProblem(block.id, `A scatter with a "shape" channel draws x, y, group, and label alone, thus it takes no ${noun} beside the shape.`));
+            }
+        }
+        return deriveShapeDraw(block, rows, context, SCATTER_DRAW);
+    },
+};
+/**
+ * Resolve one channel of the shape draw. A transform applies to a value channel. An order sorts no axis of
+ * this draw, thus it refuses.
+ */
+function resolve(context, rows, draw, member, channel, numeric) {
+    const column = channelColumn(channel);
+    if (channelOrder(channel) !== undefined) {
+        const reason = numeric ? "draws a value axis" : "draws no category axis";
+        return err(chartProblem(context.blockId, `The "${member}" channel of the ${draw.figure} ${reason}, thus it takes no "orderBy".`));
+    }
+    if (rows.length > 0 && !columnPresent(column, rows, context.columns)) {
+        return err(chartProblem(context.blockId, `The column "${column}" is absent from every row.`));
+    }
+    const transform = channelTransform(channel);
+    if (!numeric && transform !== undefined) {
+        return err(chartProblem(context.blockId, `The "${member}" channel of the ${draw.figure} names categories, thus it takes no transform.`));
+    }
+    if (transform !== undefined) {
+        return ok({ name: `${transform}(${column})`, values: transformColumn(rows, column, transform) });
+    }
+    if (numeric) {
+        for (const row of rows) {
+            const cell = row[column];
+            if (typeof cell === "string" && cell.trim() !== "" && toNumber(cell) === null) {
+                return err(chartProblem(context.blockId, `The column "${column}" holds the text "${cell}", and the ${draw.figure} draws "${member}" on a value axis.`));
+            }
+        }
+    }
+    return ok({ name: column, values: rows.map((row) => row[column] ?? null) });
+}
+/** Derive the shape draw of a PCA or of a plain scatter. */
+function deriveShapeDraw(block, rows, context, draw) {
+    const encoding = block.encoding ?? {};
+    if (encoding.x === undefined || encoding.y === undefined) {
+        const missing = encoding.x === undefined ? "x" : "y";
+        return err(chartProblem(block.id, `The ${draw.figure} chart needs a column for the "${missing}" channel.`));
+    }
+    const x = resolve(context, rows, draw, "x", encoding.x, true);
+    if (x.isErr())
+        return err(x.error);
+    const y = resolve(context, rows, draw, "y", encoding.y, true);
+    if (y.isErr())
+        return err(y.error);
+    let groups;
+    if (encoding.group !== undefined) {
+        const group = resolve(context, rows, draw, "group", encoding.group, false);
+        if (group.isErr())
+            return err(group.error);
+        groups = group.value;
+    }
+    let shapes;
+    if (encoding.shape !== undefined) {
+        const shape = resolve(context, rows, draw, "shape", encoding.shape, false);
+        if (shape.isErr())
+            return err(shape.error);
+        shapes = shape.value;
+    }
+    const labelColumn = encoding.label;
+    if (labelColumn !== undefined && rows.length > 0 && !columnPresent(labelColumn, rows, context.columns)) {
+        return err(chartProblem(block.id, `The column "${labelColumn}" is absent from every row.`));
+    }
+    const points = [];
+    for (let index = 0; index < rows.length; index += 1) {
+        const px = toNumber(x.value.values[index]);
+        const py = toNumber(y.value.values[index]);
+        const pg = groups?.values[index] ?? null;
+        const ps = shapes?.values[index] ?? null;
+        if (px === null || py === null || (groups !== undefined && pg === null) || (shapes !== undefined && ps === null))
+            continue;
+        points.push({ index, x: px, y: py, ...(pg !== null ? { group: categoryName(pg) } : {}), ...(ps !== null ? { shape: categoryName(ps) } : {}) });
+    }
+    const groupNames = firstAppearance(points.flatMap((point) => (point.group === undefined ? [] : [point.group])));
+    const shapeNames = firstAppearance(points.flatMap((point) => (point.shape === undefined ? [] : [point.shape])));
+    if (shapeNames.length > SHAPE_SYMBOLS.length) {
+        return err(chartProblem(block.id, `The "shape" channel holds ${shapeNames.length} categories, and a symbol reads for ${SHAPE_SYMBOLS.length} at most. Draw that column as the "group" channel.`));
+    }
+    const shared = groups !== undefined && shapes !== undefined ? groupNames.find((name) => shapeNames.includes(name)) : undefined;
+    if (shared !== undefined) {
+        return err(chartProblem(block.id, `The value "${shared}" names a group and a shape, thus the legend cannot tell the two keys apart.`));
+    }
+    const ranges = equalRanges(points.map((point) => point.x), points.map((point) => point.y), { pad: PCA_PAD, round: true });
+    const palette = categoricalPalette(groupNames.length);
+    const yTitle = valueAxisTitle(context.labels, y.value.name);
+    const named = labelColumn !== undefined;
+    const labeled = named && draw.labelRows > 0 && points.length <= draw.labelRows;
+    const sides = new Map();
+    if (labeled && labelColumn !== undefined) {
+        const placed = pointNameSides(points.map((point) => ({ x: point.x, y: point.y, text: String(rows[point.index][labelColumn] ?? "") })), ranges, SHAPED_POINT_PX);
+        for (const [place, point] of points.entries())
+            sides.set(point.index, placed[place]);
+    }
+    const buckets = new Map();
+    for (const point of points) {
+        const key = bucketKey(point.group, point.shape);
+        const bucket = buckets.get(key);
+        if (bucket === undefined)
+            buckets.set(key, [point]);
+        else
+            bucket.push(point);
+    }
+    const series = [];
+    const groupKeys = groups === undefined ? [undefined] : groupNames;
+    const shapeKeys = shapes === undefined ? [undefined] : shapeNames;
+    for (const [groupPlace, groupKey] of groupKeys.entries()) {
+        for (const [shapePlace, shapeKey] of shapeKeys.entries()) {
+            const members = buckets.get(bucketKey(groupKey, shapeKey));
+            if (members === undefined)
+                continue;
+            series.push({
+                type: "scatter",
+                name: groupKey ?? shapeKey ?? yTitle,
+                ...(shapeKey !== undefined ? { symbol: SHAPE_SYMBOLS[shapePlace] } : {}),
+                symbolSize: SHAPED_POINT_PX,
+                itemStyle: { color: groupKey !== undefined ? palette[groupPlace] : CHART_PALETTE[0] },
+                ...(labeled ? POINT_LABEL_FIELDS : {}),
+                data: members.map((point) => {
+                    const pair = [point.x, point.y];
+                    const name = labelColumn === undefined ? undefined : rows[point.index][labelColumn];
+                    if (name === undefined)
+                        return pair;
+                    const side = sides.get(point.index);
+                    return { value: pair, name: String(name), ...(side !== undefined && side !== "right" ? { label: { position: side } } : {}) };
+                }),
+            });
+        }
+    }
+    // A shape beside a group keys its symbols in a series of no data, thus the legend draws the symbol in ink.
+    if (groups !== undefined && shapes !== undefined) {
+        for (const [place, name] of shapeNames.entries()) {
+            series.push({ type: "scatter", name, symbol: SHAPE_SYMBOLS[place], symbolSize: SHAPED_POINT_PX, itemStyle: { color: CHART_INK }, data: [] });
+        }
+    }
+    const entries = [
+        ...(groups !== undefined ? groupNames.map((name) => ({ name, icon: POINT_LEGEND_ICON })) : []),
+        ...(shapes !== undefined ? shapeNames.map((name, place) => ({ name, icon: SHAPE_SYMBOLS[place] })) : []),
+    ];
+    const keyed = entries.length > 1;
+    const xTitle = valueAxisTitle(context.labels, x.value.name);
+    const option = {
+        tooltip: named ? { ...NAMED_POINT_TOOLTIP } : { ...PLAIN_POINT_TOOLTIP },
+        series,
+        legend: keyed ? { orient: draw.equalUnits ? "vertical" : "horizontal", ...(draw.equalUnits ? {} : { bottom: 0 }), data: entries } : { show: false },
+    };
+    if (!draw.equalUnits) {
+        return ok({ ...option, xAxis: valueAxis("x", xTitle, { scale: true }), yAxis: valueAxis("y", yTitle, { scale: true }) });
+    }
+    const layout = squareLayout({ panels: 1, margins: PCA_MARGINS, side: keyed ? PCA_LEGEND_BAND_PX : 0, legend: keyed });
+    const interval = ranges.step !== undefined ? { interval: ranges.step } : {};
+    return ok({
+        ...option,
+        grid: layout.grid,
+        xAxis: { ...valueAxis("x", xTitle, ranges.x), ...interval },
+        yAxis: { ...valueAxis("y", yTitle, ranges.y), ...interval },
+        ...(keyed && layout.legend !== undefined ? { legend: { ...option.legend, ...layout.legend } } : {}),
+        media: layout.media,
+    });
+}
+/** The key of the split of one group and one shape. An absent member names no channel. */
+function bucketKey(group, shape) {
+    return JSON.stringify([group ?? null, shape ?? null]);
+}

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

@@ -0,0 +1,30 @@
+/**
+ * The QQ figure of a GWAS, as qqman and the GWAS quality-control tools draw it: the expected −log10(p) on x,
+ * the observed −log10(p) on y, and the diagonal where the two agree under the null.
+ *
+ * - The points draw small, in the ink of the page.
+ * - The band between the `low` and the `high` columns draws in light gray under the points. It states the
+ *   confidence band of the null expectation that the run computed.
+ * - An identity line runs from zero to the largest expected value, where the null expectation ends.
+ * - Each axis spans from zero to its own round end, as qqman draws it: x to the largest expected value, and y
+ *   to the largest observed value. A strong signal can reach a hundred times the expected range, and one
+ *   shared range would squeeze the points into a thin strip at the left edge.
+ * - The statistics, for example the genomic inflation λ, print in the top left corner.
+ * - Where the y channel transforms a p column, a stored zero draws an upward triangle at the top of the observed
+ *   range.
+ *
+ * The points come from the composition machinery, thus a table of many thousand p-values reads the shared
+ * payload. The band draws after the points in the series list, and it keeps its rows inline: its upper half
+ * holds the width of the band, which no cell gives. The band reads at most `QQ_BAND_POINTS` rows, spaced
+ * along the x axis, thus it stays small beside a payload of any size.
+ */
+import type { FigureModule } from "./index.js";
+/** The symbol size in pixels of a QQ point. */
+export declare const QQ_POINT_PX = 3;
+/**
+ * The largest count of rows that the band reads. One row for each two pixels of a wide plot keeps the drawn
+ * edge of the band as the full table draws it.
+ */
+export declare const QQ_BAND_POINTS = 400;
+/** The QQ figure module. */
+export declare const QQ_FIGURE: FigureModule;

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

@@ -0,0 +1,182 @@
+/**
+ * The QQ figure of a GWAS, as qqman and the GWAS quality-control tools draw it: the expected −log10(p) on x,
+ * the observed −log10(p) on y, and the diagonal where the two agree under the null.
+ *
+ * - The points draw small, in the ink of the page.
+ * - The band between the `low` and the `high` columns draws in light gray under the points. It states the
+ *   confidence band of the null expectation that the run computed.
+ * - An identity line runs from zero to the largest expected value, where the null expectation ends.
+ * - Each axis spans from zero to its own round end, as qqman draws it: x to the largest expected value, and y
+ *   to the largest observed value. A strong signal can reach a hundred times the expected range, and one
+ *   shared range would squeeze the points into a thin strip at the left edge.
+ * - The statistics, for example the genomic inflation λ, print in the top left corner.
+ * - Where the y channel transforms a p column, a stored zero draws an upward triangle at the top of the observed
+ *   range.
+ *
+ * The points come from the composition machinery, thus a table of many thousand p-values reads the shared
+ * payload. The band draws after the points in the series list, and it keeps its rows inline: its upper half
+ * holds the width of the band, which no cell gives. The band reads at most `QQ_BAND_POINTS` rows, spaced
+ * along the x axis, thus it stays small beside a payload of any size.
+ */
+import { err, ok } from "neverthrow";
+import { channelColumn, channelTransform } from "../../contracts/report-blocks.js";
+import { CHART_INK, GUIDE_LINE_COLOR, GUIDE_LINE_WIDTH_PX, MUTED_CHART_COLOR } from "../design.js";
+import { chartProblem, plainColumn, statisticsGraphic, toNumber } from "./common.js";
+import { axisOf, BELOW_RESOLUTION_NAME, BELOW_RESOLUTION_SYMBOL, BELOW_RESOLUTION_SYMBOL_PX, BELOW_RESOLUTION_TOOLTIP, belowResolutionHeight, belowResolutionRows, demandedChannel, largest, niceCeiling, plottedValues, seriesOf, } from "./dense.js";
+/** The symbol size in pixels of a QQ point. */
+export const QQ_POINT_PX = 3;
+/**
+ * The largest count of rows that the band reads. One row for each two pixels of a wide plot keeps the drawn
+ * edge of the band as the full table draws it.
+ */
+export const QQ_BAND_POINTS = 400;
+/** The fill of the band: the muted gray, light. */
+const BAND_OPACITY = 0.3;
+/** The drawing order of the band. The runtime draws a scatter at the order 2, thus the band sits under it. */
+const BAND_Z = 1;
+/** The titles of the two axes where the binding declares no label. The minus sign is the character. */
+const EXPECTED_TITLE = "Expected −log10(p)";
+const OBSERVED_TITLE = "Observed −log10(p)";
+/** The name of the two band series. The legend of the figure hides, thus the name rides the tooltip alone. */
+const BAND_NAME = "Null band";
+/** The members of a QQ block that the figure reads. */
+const READS = new Set(["x", "y", "low", "high", "statistics"]);
+/**
+ * The rows that the band reads: each row with a number in the three columns, in ascending order of x, thinned
+ * to at most `QQ_BAND_POINTS` rows spaced along the x axis, or spaced by place where each row holds one x. The
+ * first and the last row always stay, thus the band spans the whole axis.
+ *
+ * The band stacks its width on its lower bound, and a stack takes no negative width. Thus a row whose `high`
+ * value sits under its `low` value refuses, and the refusal names the row.
+ */
+function bandRows(blockId, rows, xs, lowColumn, highColumn) {
+    const complete = [];
+    for (let index = 0; index < rows.length; index += 1) {
+        const x = xs[index];
+        const low = toNumber(rows[index][lowColumn]);
+        const high = toNumber(rows[index][highColumn]);
+        if (x === null || low === null || high === null)
+            continue;
+        if (high < low) {
+            return err(chartProblem(blockId, `The row ${index + 1} holds the band from ${low} in "${lowColumn}" to ${high} in "${highColumn}". ` +
+                'The "low" bound sits at or under the "high" bound.'));
+        }
+        complete.push({ x, low, high, index });
+    }
+    complete.sort((a, b) => a.x - b.x || a.index - b.index);
+    if (complete.length <= QQ_BAND_POINTS)
+        return ok(complete);
+    const last = complete[complete.length - 1];
+    const step = (last.x - complete[0].x) / (QQ_BAND_POINTS - 1);
+    // Each row sits zero steps from the next one, thus the rule of the step keeps each row.
+    if (!(step > 0)) {
+        return ok(Array.from({ length: QQ_BAND_POINTS }, (_row, place) => complete[Math.round((place * (complete.length - 1)) / (QQ_BAND_POINTS - 1))]));
+    }
+    // The kept rows sit at least one step apart, and a kept row between the ends sits at least one step before
+    // the last row. Thus the span holds at most `QQ_BAND_POINTS - 1` steps, and the band at most
+    // `QQ_BAND_POINTS` rows.
+    const kept = [complete[0]];
+    for (let place = 1; place < complete.length - 1; place += 1) {
+        const row = complete[place];
+        if (row.x - kept[kept.length - 1].x >= step && last.x - row.x >= step)
+            kept.push(row);
+    }
+    kept.push(last);
+    return ok(kept);
+}
+/**
+ * The two series of the band: a lower series that carries the lower bound with no ink, and an upper series
+ * that stacks the width of the band on it and fills the area between.
+ */
+function bandSeries(band) {
+    const shared = { type: "line", name: BAND_NAME, stack: "qq-band", showSymbol: false, silent: true, tooltip: { show: false }, z: BAND_Z };
+    return [
+        { ...shared, lineStyle: { opacity: 0 }, data: band.map((row) => [row.x, row.low]) },
+        {
+            ...shared,
+            lineStyle: { opacity: 0 },
+            areaStyle: { color: MUTED_CHART_COLOR, opacity: BAND_OPACITY },
+            data: band.map((row) => [row.x, row.high - row.low]),
+        },
+    ];
+}
+function deriveQq(block, rows, context) {
+    const encoding = block.encoding ?? {};
+    const x = demandedChannel(context.blockId, "qq", encoding, "x");
+    if (x.isErr())
+        return err(x.error);
+    const y = demandedChannel(context.blockId, "qq", encoding, "y");
+    if (y.isErr())
+        return err(y.error);
+    // The band draws each bound as its cell gives it, in the unit of the plotted y, thus a bound takes no transform.
+    const source = { blockId: context.blockId, rows, columns: context.columns };
+    const low = plainColumn("qq", encoding, "low", source);
+    if (low.isErr())
+        return err(low.error);
+    const high = plainColumn("qq", encoding, "high", source);
+    if (high.isErr())
+        return err(high.error);
+    const composition = { series: [{ form: "scatter", encoding: { x: x.value, y: y.value } }] };
+    const composed = context.compose(composition, { preset: { x: EXPECTED_TITLE, y: OBSERVED_TITLE } });
+    if (composed.isErr())
+        return err(composed.error);
+    const xs = plottedValues(rows, x.value);
+    const ys = plottedValues(rows, y.value);
+    const banded = low.value !== undefined && high.value !== undefined ? bandRows(context.blockId, rows, xs, low.value, high.value) : ok([]);
+    if (banded.isErr())
+        return err(banded.error);
+    const band = banded.value;
+    const expectedValues = [];
+    const observedValues = [];
+    for (let index = 0; index < rows.length; index += 1) {
+        const expected = xs[index];
+        const observed = ys[index];
+        if (expected === null || observed === null)
+            continue;
+        expectedValues.push(expected);
+        observedValues.push(observed);
+    }
+    const top = largest(expectedValues) ?? 0;
+    const peak = largest(observedValues);
+    // A stored zero of a p that the channel transforms draws at the top of the observed range.
+    const zeroRows = channelTransform(y.value) === "neg_log10" ? belowResolutionRows(rows, channelColumn(y.value), xs) : [];
+    const zeroY = belowResolutionHeight(peak, 0);
+    const xEnd = niceCeiling(Math.max(top, largest(band.map((row) => row.x)) ?? 0));
+    // The y range holds the identity line and the band as well as the points.
+    const yEnd = niceCeiling(Math.max(peak ?? 0, top, largest(band.map((row) => row.high)) ?? 0, zeroRows.length > 0 ? zeroY : 0));
+    const identity = {
+        silent: true,
+        symbol: "none",
+        lineStyle: { color: GUIDE_LINE_COLOR, width: GUIDE_LINE_WIDTH_PX, type: "solid" },
+        label: { show: false },
+        data: [[{ coord: [0, 0] }, { coord: [top, top] }]],
+    };
+    const option = composed.value;
+    const statistics = statisticsGraphic(context.statistics, "top-left");
+    return ok({
+        ...option,
+        legend: { show: false },
+        xAxis: { ...axisOf(option, "xAxis"), min: 0, max: xEnd },
+        yAxis: { ...axisOf(option, "yAxis"), min: 0, max: yEnd },
+        series: [
+            ...seriesOf(option).map((series) => ({ ...series, symbolSize: QQ_POINT_PX, itemStyle: { color: CHART_INK }, markLine: identity })),
+            ...(band.length > 0 ? bandSeries(band) : []),
+            ...(zeroRows.length > 0
+                ? [
+                    {
+                        type: "scatter",
+                        name: BELOW_RESOLUTION_NAME,
+                        symbol: BELOW_RESOLUTION_SYMBOL,
+                        symbolSize: BELOW_RESOLUTION_SYMBOL_PX,
+                        itemStyle: { color: CHART_INK },
+                        tooltip: BELOW_RESOLUTION_TOOLTIP,
+                        data: zeroRows.map((index) => [xs[index] ?? 0, zeroY]),
+                    },
+                ]
+                : []),
+        ],
+        ...(statistics.length > 0 ? { graphic: statistics } : {}),
+    });
+}
+/** The QQ figure module. */
+export const QQ_FIGURE = { reads: READS, derive: deriveQq };

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

@@ -0,0 +1,17 @@
+/**
+ * The ROC figure: the empirical curve of each group, the dashed diagonal of chance, and the statistics text.
+ *
+ * A row of the table is one operating point of a classifier: its false positive rate and its true positive
+ * rate at one threshold. The curve runs through the points of its group in order of the false positive rate,
+ * then of the true positive rate, thus the steps of an empirical curve read as steps, and a tie of scores
+ * reads as the diagonal segment that the field draws for it. The figure adds no point that the table does not
+ * hold.
+ *
+ * The two axes hold one quantity, a rate from 0 to 1, thus they share the range, the tick step, and the unit:
+ * the plot is a square, and the diagonal of chance runs at 45 degrees. The legend sits in a band under the
+ * square, thus a narrow column export keeps the square large. The statistics text is the label of a point at
+ * the corner (1, 0) of the data, thus it stays in the corner of the square in each container.
+ */
+import type { FigureModule } from "./index.js";
+/** The ROC curve figure. */
+export declare const ROC_FIGURE: FigureModule;

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

@@ -0,0 +1,116 @@
+/**
+ * The ROC figure: the empirical curve of each group, the dashed diagonal of chance, and the statistics text.
+ *
+ * A row of the table is one operating point of a classifier: its false positive rate and its true positive
+ * rate at one threshold. The curve runs through the points of its group in order of the false positive rate,
+ * then of the true positive rate, thus the steps of an empirical curve read as steps, and a tie of scores
+ * reads as the diagonal segment that the field draws for it. The figure adds no point that the table does not
+ * hold.
+ *
+ * The two axes hold one quantity, a rate from 0 to 1, thus they share the range, the tick step, and the unit:
+ * the plot is a square, and the diagonal of chance runs at 45 degrees. The legend sits in a band under the
+ * square, thus a narrow column export keeps the square large. The statistics text is the label of a point at
+ * the corner (1, 0) of the data, thus it stays in the corner of the square in each container.
+ */
+import { err, ok } from "neverthrow";
+import { categoricalPalette, categoryName, chartProblem, demandedColumn, firstAppearance, GUIDE_LINE_STYLE, plainColumn, STATISTICS_POINT_INSET_PX, statisticsSeries, toNumber, valueAxis, valueAxisTitle, } from "./common.js";
+import { squareLayout } from "./equal-units.js";
+/** The members of a roc block that the figure reads. */
+const ROC_READS = new Set(["x", "y", "group", "statistics"]);
+/** The ROC curve figure. */
+export const ROC_FIGURE = { reads: ROC_READS, derive: deriveRoc };
+/** The tick step of both rate axes. */
+const RATE_STEP = 0.2;
+/** The margins of the square of a ROC curve, in pixels: the tick labels and the title of each axis. */
+const ROC_MARGINS = { top: 16, bottom: 56, left: 64, right: 12 };
+/** The stroke width of a curve, in pixels. */
+const CURVE_WIDTH_PX = 1.5;
+/** Derive the figure of one roc block. */
+function deriveRoc(block, rows, context) {
+    const encoding = block.encoding ?? {};
+    const source = { blockId: context.blockId, rows, columns: context.columns };
+    const fpr = demandedColumn("roc", encoding, "x", source);
+    if (fpr.isErr())
+        return err(fpr.error);
+    const tpr = demandedColumn("roc", encoding, "y", source);
+    if (tpr.isErr())
+        return err(tpr.error);
+    const group = plainColumn("roc", encoding, "group", source);
+    if (group.isErr())
+        return err(group.error);
+    const curves = rocCurves(rows, fpr.value, tpr.value, group.value, context.blockId);
+    if (curves.isErr())
+        return err(curves.error);
+    const palette = categoricalPalette(curves.value.length);
+    const series = curves.value.map((curve, index) => {
+        const color = palette[index % palette.length];
+        return {
+            type: "line",
+            name: categoryName(curve.name),
+            showSymbol: false,
+            itemStyle: { color },
+            lineStyle: { color, width: CURVE_WIDTH_PX },
+            data: curve.points,
+        };
+    });
+    series.push({
+        type: "line",
+        silent: true,
+        tooltip: { show: false },
+        data: [],
+        markLine: {
+            silent: true,
+            symbol: "none",
+            label: { show: false },
+            lineStyle: { ...GUIDE_LINE_STYLE },
+            data: [[{ coord: [0, 0] }, { coord: [1, 1] }]],
+        },
+    });
+    const statistics = statisticsSeries(context.statistics, [1, 0], "bottom-right");
+    const squareLabel = statistics.length > 0 ? { series: series.length, insetPx: STATISTICS_POINT_INSET_PX } : undefined;
+    series.push(...statistics);
+    const keyed = curves.value.length > 1;
+    const names = curves.value.map((curve) => categoryName(curve.name));
+    const layout = squareLayout({
+        panels: 1,
+        margins: ROC_MARGINS,
+        side: 0,
+        legend: keyed,
+        legendBand: { place: "bottom", entries: names },
+        ...(squareLabel !== undefined ? { squareLabel } : {}),
+    });
+    return ok({
+        grid: layout.grid,
+        legend: keyed && layout.legend !== undefined ? { ...layout.legend, data: names } : { show: false },
+        xAxis: { ...valueAxis("x", valueAxisTitle(context.labels, fpr.value), { min: 0, max: 1 }), interval: RATE_STEP },
+        yAxis: { ...valueAxis("y", valueAxisTitle(context.labels, tpr.value), { min: 0, max: 1 }), interval: RATE_STEP },
+        series,
+        media: layout.media,
+    });
+}
+/**
+ * The curves of one table: one for each group in the order of its first row. A row whose rate is not numeric
+ * draws nothing, and a rate outside 0 to 1 refuses, because the axes hold 0 to 1 and a clip would hide it.
+ * The sort is stable, thus two rows at one point keep the order of the table.
+ */
+function rocCurves(rows, fpr, tpr, group, blockId) {
+    const groupOf = (row) => (group === undefined ? "" : (row[group] ?? ""));
+    const names = firstAppearance(rows.map((row) => String(groupOf(row))));
+    const byName = new Map(names.map((name) => [name, []]));
+    for (const [index, row] of rows.entries()) {
+        const x = toNumber(row[fpr]);
+        const y = toNumber(row[tpr]);
+        if (x === null || y === null)
+            continue;
+        for (const [value, column] of [
+            [x, fpr],
+            [y, tpr],
+        ]) {
+            if (value < 0 || value > 1) {
+                return err(chartProblem(blockId, `The roc figure reads rates between 0 and 1, and the row ${index + 1} holds ${value} in the "${column}" column.`));
+            }
+        }
+        byName.get(String(groupOf(row)))?.push([x, y]);
+    }
+    return ok(names.map((name) => ({ name, points: (byName.get(name) ?? []).sort((a, b) => a[0] - b[0] || a[1] - b[1]) })));
+}

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

@@ -0,0 +1,48 @@
+/**
+ * The Sankey diagram: the flows between the nodes of some stages, as the ECharts `sankey` series draws them.
+ *
+ * The figure reads one row for each flow: the `x` column names the source node, the `y` column names the
+ * target node, and the `value` column gives the size of the flow. The optional `group` column names the
+ * category of each flow, and each flow takes the palette color of its category.
+ *
+ * - The nodes keep the order of their first appearance in the rows, and the layout runs no iteration. Thus
+ *   the order of the table is the order of each stage, and the same rows give the same picture.
+ * - The palette starts again at each stage, thus each node takes the palette color of its place in its stage.
+ *   Each flow takes the color of its source at a light opacity. With a group, each flow takes the color of its group, the nodes draw gray, and a legend names
+ *   each group.
+ * - Each label sits beside its node: at the right, and at the left in the last stage, thus each label stays
+ *   inside the chart. A label wraps into the room between two stages. The runtime draws a series label at a
+ *   fixed size of its own, thus the page and one media rule for each export size state the text size.
+ * - Each label sits on a box of the page color, thus no flow covers it.
+ * - The node gap holds one label line where the stage of the most nodes has the room, thus the label of a thin
+ *   node meets no neighbor. A label that still meets a neighbor hides, and the tooltip of its node names it.
+ * - The tooltip of a flow names its two nodes and its value.
+ *
+ * The figure computes one named summary: the stage of each node. The stage is the longest chain of flows from
+ * a node with no inflow, and a node with no outflow takes the last stage, thus each end of the flows lines up
+ * at the right. The chart runtime sizes each node by the larger of its inflow and its outflow.
+ */
+import { type Result } from "neverthrow";
+import type { FigureModule } from "./index.js";
+/** The opacity of a flow. A flow reads as the path of its source, and a label reads over it. */
+export declare const SANKEY_LINK_OPACITY = 0.35;
+/**
+ * The box of a label: the color of the page, and the room at each side of the text, in pixels at the page text
+ * size. A label sits over the flows of its node, and the flows of a thin node are thinner than the text. Thus a
+ * flow edge would cross the letters, and a halo keeps it visible between them. The box hides each flow under
+ * the text.
+ */
+export declare const SANKEY_LABEL_BOX_COLOR = "#ffffff";
+/** The Sankey module: the source, the target, the flow, and the group. */
+export declare const SANKEY_FIGURE: FigureModule;
+/** One flow of the table: its two nodes. */
+export interface SankeyEdge {
+    readonly source: string;
+    readonly target: string;
+}
+/**
+ * The stage of each node, in the order of first appearance: the longest chain of flows from a node with no
+ * inflow. A node with no outflow takes the last stage. A cycle has no stage, thus it refuses, and the error
+ * names the nodes of the cycle.
+ */
+export declare function sankeyStages(edges: readonly SankeyEdge[]): Result<Map<string, number>, string>;