@inflexa-ai/harness 0.42.1 → 0.43.0

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

@@ -0,0 +1,395 @@
+/**
+ * The heatmap: a matrix of one value over the pairs of two category columns, with annotation strips.
+ *
+ * The canonical expression heatmap is the pheatmap and ComplexHeatmap figure: the genes down the y axis in the
+ * order of the run, the samples along x, a z-score on a diverging ramp symmetric at zero, and one strip of
+ * category colors over the matrix for each covariate of the samples, with a legend for each strip. The cells
+ * stand apart by a thin white gap, and the axes draw no line. A matrix of many samples hides its sample names,
+ * and the axis title states the count of samples in their place.
+ *
+ * A distance matrix draws on the sequential ramp, whose dark end is the low value. Thus the diagonal of zero
+ * distance draws dark, and two far samples draw light, as the DESeq2 sample-distance figure draws them.
+ *
+ * The run gives the order of each axis through the `orderBy` of its channel, or through the tree of the axis.
+ * A tree is the edge table of a clustering. The axis takes its depth-first leaf order, and the figure draws it
+ * as a dendrogram of elbows: the tree of x above the strips, and the tree of y at the left of the row names.
+ *
+ * A pair of categories holds one value. A repeated pair is a refusal, and never a silent sum. A track column
+ * holds one value for each x category, and a category with two values is a refusal.
+ *
+ * pheatmap names each row. Thus a matrix of more rows than the default body holds at one line of text each
+ * states a taller body, up to the largest body. A taller body grows the column exports in the same ratio.
+ * Past the largest body, and in a column export whose rows are shorter than a line of text, a row name that
+ * overlaps its neighbor hides.
+ */
+import { err, ok } from "neverthrow";
+import { channelColumn, channelOrder, channelTransform } from "../../contracts/report-blocks.js";
+import { declaredForColumn } from "../../contracts/report-reference.js";
+import { CHART_BODY_PX, CHART_BODY_MAX_PX, CHART_INK, CHART_PAGE_TEXT_PX, CHART_SLOT_LIMIT, COLOR_SCALE_BAND_PCT, MUTED_CHART_COLOR } from "../design.js";
+import { axisNameFields, categoricalPalette, categoryAxisTitle, categoryName, chartProblem, colorScale, columnPresent, continuousScale, orderQuickCategories, toNumber, transformColumn, valueAxisTitle, withFigureBody, Y_AXIS_NAME_GAP, } from "./common.js";
+import { checkTree } from "./dendrogram.js";
+/** The count of x categories past which the matrix hides the x labels and states the count in the axis title. */
+export const HEATMAP_LABEL_LIMIT = 40;
+/** The white gap between two cells, in pixels. */
+export const HEATMAP_CELL_GAP_PX = 1;
+/** The height of one annotation strip, in pixels. */
+export const HEATMAP_STRIP_PX = 12;
+/** The height of one line of the strip legends, and the gap between the band of the legends and the strips, in pixels. */
+export const TRACK_LEGEND_LINE_PX = 24;
+export const TRACK_BAND_GAP_PX = 14;
+/** The gap over the legends, and between the strips and the matrix, in pixels. */
+const TRACK_GAP_PX = 6;
+/** The height of one matrix row on the page, in pixels: one line of the page text with a gap. */
+export const HEATMAP_ROW_PX = 16;
+/** The top margin of a matrix with no strip, in pixels: the top margin of the layout discipline on the default body. */
+const PLAIN_TOP_PX = 32;
+/**
+ * The band under a matrix in a taller body, in pixels: the axis title and its gap, and one line of level
+ * labels. A turned label adds its turned length.
+ */
+const TITLE_BAND_PX = 44;
+const LEVEL_LABEL_PX = 18;
+/** The count of x categories past which the layout discipline turns the x labels 45 degrees, and past which 90. */
+const TURN_45_COUNT = 10;
+const TURN_90_COUNT = 20;
+/** The right margin of the grid beside the color scale. */
+const COLOR_SCALE_GRID_RIGHT = `${COLOR_SCALE_BAND_PCT}%`;
+/**
+ * The width of one character of a row label, as a share of the text size. The left margin of a matrix with
+ * strips holds its longest row label, thus the strips and the matrix start at one edge.
+ */
+const LABEL_CHARACTER_SHARE = 0.6;
+const LABEL_MARGIN_MIN_PX = 40;
+const LABEL_MARGIN_PAD_PX = 16;
+/** The size of one entry of a strip legend, in pixels. */
+const TRACK_LEGEND_ITEM_PX = 10;
+/** The depth of the band of one dendrogram, in pixels: the height of the tree of x, and the width of the tree of y. */
+export const DENDROGRAM_BAND_PX = 48;
+/** The gap between the leaves of a dendrogram and the strips, the matrix, or the row names, in pixels. */
+const DENDROGRAM_GAP_PX = 4;
+/** The top margin over the tree of x where no strip legend sits above it, and the margin at the left of the tree of y, in pixels. */
+const DENDROGRAM_TOP_PX = 12;
+const DENDROGRAM_SIDE_PX = 8;
+/** The width of a dendrogram branch, in pixels. */
+const DENDROGRAM_LINE_PX = 1;
+/** The axis parts that the matrix hides: the line and the ticks. */
+const LINELESS_AXIS = { axisLine: { show: false }, axisTick: { show: false } };
+/** The heatmap. */
+export const HEATMAP_FIGURE = {
+    reads: new Set(["x", "y", "value", "tracks", "trees"]),
+    derive: deriveHeatmap,
+};
+/** The plain column of one category channel of the matrix. A transform would make its categories numbers, thus it refuses. */
+function categoryColumn(block, rows, context, member, channel) {
+    if (channelTransform(channel) !== undefined) {
+        return err(chartProblem(block.id, `The "${member}" channel of the heatmap names categories, thus it takes no transform.`));
+    }
+    return present(block.id, rows, context, channelColumn(channel));
+}
+/** The column, where one row at least holds it. A table with no row holds each column. */
+function present(blockId, rows, context, column) {
+    if (rows.length > 0 && !columnPresent(column, rows, context.columns)) {
+        return err(chartProblem(blockId, `The column "${column}" is absent from every row.`));
+    }
+    return ok(column);
+}
+/** The key of one pair. The key carries the type of each cell, thus the number `1` and the text `"1"` stay two categories. */
+function pairKey(xCell, yCell) {
+    return `${cellKey(xCell)} ${cellKey(yCell)}`;
+}
+/** The key of one cell. */
+function cellKey(cell) {
+    return `${typeof cell}:${String(cell)}`;
+}
+function deriveHeatmap(block, rows, context) {
+    const encoding = block.encoding ?? {};
+    for (const member of ["x", "y", "value"]) {
+        if (encoding[member] === undefined) {
+            return err(chartProblem(block.id, `The heatmap chart needs a column for the "${member}" channel.`));
+        }
+    }
+    const xChannel = encoding.x;
+    const yChannel = encoding.y;
+    const valueChannel = encoding.value;
+    if (channelOrder(valueChannel) !== undefined) {
+        return err(chartProblem(block.id, 'The "value" channel draws no category axis, thus it takes no "orderBy".'));
+    }
+    const x = categoryColumn(block, rows, context, "x", xChannel);
+    if (x.isErr())
+        return err(x.error);
+    const y = categoryColumn(block, rows, context, "y", yChannel);
+    if (y.isErr())
+        return err(y.error);
+    const valueColumn = present(block.id, rows, context, channelColumn(valueChannel));
+    if (valueColumn.isErr())
+        return err(valueColumn.error);
+    const transform = channelTransform(valueChannel);
+    const valueName = transform === undefined ? valueColumn.value : `${transform}(${valueColumn.value})`;
+    const values = transform === undefined ? rows.map((row) => toNumber(row[valueColumn.value])) : transformColumn(rows, valueColumn.value, transform);
+    const xOrdered = axisOrder(block, rows, context, "x", x.value, xChannel);
+    if (xOrdered.isErr())
+        return err(xOrdered.error);
+    const yOrdered = axisOrder(block, rows, context, "y", y.value, yChannel);
+    if (yOrdered.isErr())
+        return err(yOrdered.error);
+    const xCategories = xOrdered.value.order;
+    const yCategories = yOrdered.value.order;
+    const xTree = xOrdered.value.tree;
+    const yTree = yOrdered.value.tree;
+    const slots = xCategories.length * yCategories.length;
+    if (slots > CHART_SLOT_LIMIT) {
+        return err(chartProblem(block.id, `The chart holds ${xCategories.length} categories and ${yCategories.length} groups, thus ${slots} slots. A chart holds ${CHART_SLOT_LIMIT} slots at most, thus a table of fewer categories or fewer groups serves the reader.`));
+    }
+    const cells = new Map();
+    for (const [index, row] of rows.entries()) {
+        const key = pairKey(row[x.value], row[y.value]);
+        if (cells.has(key)) {
+            return err(chartProblem(block.id, `The heatmap holds the pair (${String(row[x.value])}, ${String(row[y.value])}) more than one time.`));
+        }
+        cells.set(key, values[index]);
+    }
+    const data = [];
+    const finite = [];
+    for (let xi = 0; xi < xCategories.length; xi++) {
+        for (let yi = 0; yi < yCategories.length; yi++) {
+            const value = cells.get(pairKey(xCategories[xi], yCategories[yi])) ?? null;
+            data.push([xi, yi, value]);
+            if (value !== null)
+                finite.push(value);
+        }
+    }
+    const hidden = xCategories.length > HEATMAP_LABEL_LIMIT;
+    const xTitle = hidden
+        ? `${categoryAxisTitle(context.labels, x.value) ?? categoryName(x.value)} (n = ${xCategories.length})`
+        : categoryAxisTitle(context.labels, x.value);
+    const xAxis = {
+        type: "category",
+        data: xCategories.map(String),
+        ...axisNameFields("x", xTitle),
+        ...LINELESS_AXIS,
+        ...(hidden ? { axisLabel: { show: false } } : {}),
+    };
+    const yAxis = {
+        type: "category",
+        // The runtime draws the first category of a y axis at the origin. The inverted axis puts the first row
+        // of the order at the top, thus the matrix reads down as the run ordered it.
+        inverse: true,
+        data: yCategories.map(String),
+        ...axisNameFields("y", categoryAxisTitle(context.labels, y.value)),
+        ...LINELESS_AXIS,
+        // A matrix of many rows holds more names than its height fits. The runtime then shows each name that
+        // clears its neighbor, and never draws two names over each other.
+        axisLabel: { hideOverlap: true },
+    };
+    const scaleMap = {
+        type: "continuous",
+        ...colorScale(continuousScale(finite), valueAxisTitle(context.labels, valueName), valueName, declaredForColumn(context.meanings, valueColumn.value)),
+    };
+    const matrix = { type: "heatmap", itemStyle: { borderColor: "#ffffff", borderWidth: HEATMAP_CELL_GAP_PX }, data };
+    const tracks = encoding.tracks ?? [];
+    const band = underBand(xCategories, hidden);
+    if (tracks.length === 0 && xTree === undefined && yTree === undefined) {
+        const body = PLAIN_TOP_PX + yCategories.length * HEATMAP_ROW_PX + band;
+        if (body <= CHART_BODY_PX) {
+            return ok({ xAxis, yAxis, visualMap: scaleMap, series: [matrix], grid: { right: COLOR_SCALE_GRID_RIGHT } });
+        }
+        return ok(withFigureBody({
+            xAxis,
+            yAxis,
+            visualMap: scaleMap,
+            series: [matrix],
+            grid: { right: COLOR_SCALE_GRID_RIGHT, top: PLAIN_TOP_PX, bottom: bandShare(band, body) },
+        }, body));
+    }
+    const strips = trackStrips(block, rows, context, x.value, xCategories, tracks);
+    if (strips.isErr())
+        return err(strips.error);
+    const titles = strips.value.map((strip) => strip.title);
+    let longest = 0;
+    for (const name of [...yCategories.map(String), ...titles])
+        longest = Math.max(longest, name.length);
+    const labelMargin = Math.max(LABEL_MARGIN_MIN_PX, Math.round(longest * CHART_PAGE_TEXT_PX * LABEL_CHARACTER_SHARE) + LABEL_MARGIN_PAD_PX);
+    // The tree of y sits at the left of the row names, and a y title sits between the tree and the names.
+    const yTitled = yAxis.name !== undefined;
+    const yTreeBand = yTree === undefined ? 0 : DENDROGRAM_SIDE_PX + DENDROGRAM_BAND_PX + DENDROGRAM_GAP_PX + (yTitled ? CHART_PAGE_TEXT_PX + Y_AXIS_NAME_GAP : 0);
+    const left = yTreeBand + labelMargin;
+    const headTop = tracks.length > 0 ? TRACK_GAP_PX + tracks.length * TRACK_LEGEND_LINE_PX + TRACK_BAND_GAP_PX : xTree !== undefined ? DENDROGRAM_TOP_PX : PLAIN_TOP_PX;
+    const stripTop = headTop + (xTree === undefined ? 0 : DENDROGRAM_BAND_PX + DENDROGRAM_GAP_PX);
+    const matrixTop = tracks.length > 0 ? stripTop + tracks.length * HEATMAP_STRIP_PX + TRACK_GAP_PX : stripTop;
+    const body = matrixTop + yCategories.length * HEATMAP_ROW_PX + band;
+    const tall = body > CHART_BODY_PX;
+    const bottom = tall ? bandShare(band, body) : hidden ? "12%" : xCategories.length > TURN_45_COUNT ? "25%" : "20%";
+    const palette = categoricalPalette(strips.value.reduce((sum, strip) => sum + strip.values.length, 0));
+    const stripSeries = [];
+    const legends = [];
+    let offset = 0;
+    for (const [place, strip] of strips.value.entries()) {
+        stripSeries.push({
+            type: "heatmap",
+            name: strip.title,
+            xAxisIndex: 1,
+            yAxisIndex: 1,
+            itemStyle: { borderColor: "#ffffff", borderWidth: HEATMAP_CELL_GAP_PX },
+            data: strip.codes.flatMap((code, xi) => (code === null ? [] : [[xi, place, code]])),
+        });
+        legends.push({
+            type: "piecewise",
+            seriesIndex: 1 + place,
+            dimension: 2,
+            orient: "horizontal",
+            // Beside a tree of y, the legends start over the row names, thus a column export holds each entry.
+            left: yTree === undefined ? left : yTreeBand,
+            top: TRACK_GAP_PX + place * TRACK_LEGEND_LINE_PX,
+            itemWidth: TRACK_LEGEND_ITEM_PX,
+            itemHeight: TRACK_LEGEND_ITEM_PX,
+            selectedMode: false,
+            showLabel: true,
+            text: [strip.title],
+            // The strips share one palette, and a value past its end takes the muted color.
+            pieces: strip.values.map((value, code) => ({ value: code, label: categoryName(value), color: palette[offset + code] ?? MUTED_CHART_COLOR })),
+        });
+        offset += strip.values.length;
+    }
+    // Beside a tree of y, each row name starts at the leaves. An export draws its text smaller than the page,
+    // thus a name that ends at the matrix would leave a gap between the leaves and the names.
+    const leafLabels = yTree === undefined ? {} : { axisLabel: { hideOverlap: true, align: "left", margin: labelMargin } };
+    const grid = [{ left, right: COLOR_SCALE_GRID_RIGHT, top: matrixTop, bottom }];
+    const xAxes = [xAxis];
+    const yAxes = [{ ...yAxis, ...leafLabels }];
+    if (tracks.length > 0) {
+        grid.push({ left, right: COLOR_SCALE_GRID_RIGHT, top: stripTop, height: tracks.length * HEATMAP_STRIP_PX });
+        xAxes.push({ type: "category", gridIndex: 1, data: xCategories.map(String), ...LINELESS_AXIS, axisLabel: { show: false } });
+        yAxes.push({ type: "category", gridIndex: 1, inverse: true, data: titles, ...LINELESS_AXIS, ...leafLabels });
+    }
+    const treeSeries = [];
+    if (xTree !== undefined) {
+        const index = grid.length;
+        grid.push({ left, right: COLOR_SCALE_GRID_RIGHT, top: headTop, height: DENDROGRAM_BAND_PX });
+        xAxes.push(leafAxis(index, xCategories.length, false));
+        yAxes.push(heightAxis(index, xTree.height, false));
+        treeSeries.push(dendrogramSeries(index, xTree, "x"));
+    }
+    if (yTree !== undefined) {
+        const index = grid.length;
+        grid.push({ left: DENDROGRAM_SIDE_PX, width: DENDROGRAM_BAND_PX, top: matrixTop, bottom });
+        xAxes.push(heightAxis(index, yTree.height, true));
+        yAxes.push(leafAxis(index, yCategories.length, true));
+        treeSeries.push(dendrogramSeries(index, yTree, "y"));
+    }
+    const framed = {
+        grid,
+        xAxis: xAxes,
+        yAxis: yAxes,
+        visualMap: [{ ...scaleMap, seriesIndex: 0 }, ...legends],
+        series: [matrix, ...stripSeries, ...treeSeries],
+        legend: { show: false },
+    };
+    return ok(tall ? withFigureBody(framed, body) : framed);
+}
+/**
+ * The categories of one axis in their order, and the checked tree of the axis where the block binds one.
+ *
+ * A tree gives the leaf order, thus an `orderBy` on the same axis names a second order, and it refuses.
+ */
+function axisOrder(block, rows, context, axis, column, channel) {
+    const tree = context.trees?.[axis];
+    const declared = channelOrder(channel);
+    if (tree !== undefined && declared !== undefined) {
+        return err(chartProblem(block.id, `The ${axis} axis takes the leaf order of its tree, thus the "${axis}" channel takes no "orderBy".`));
+    }
+    const categories = orderQuickCategories(block.id, rows, column, declared);
+    if (categories.isErr())
+        return err(categories.error);
+    if (tree === undefined)
+        return ok({ order: categories.value });
+    return checkTree(block.id, axis, tree, categories.value).map((checked) => ({ order: checked.order, tree: checked }));
+}
+/**
+ * The hidden value axis of a dendrogram along the categories of the matrix. A category axis draws category `i`
+ * at the middle of band `i`, thus a range of half a band past each end puts each leaf under its column or
+ * beside its row. The tree of y reads down, as the matrix reads down.
+ */
+function leafAxis(gridIndex, count, inverse) {
+    return { type: "value", gridIndex, min: -0.5, max: count - 0.5, ...(inverse ? { inverse: true } : {}), show: false };
+}
+/** The hidden value axis of the heights of a dendrogram. The tree of y turns it, thus the root sits at the left and the leaves face the row names. */
+function heightAxis(gridIndex, height, inverse) {
+    return { type: "value", gridIndex, min: 0, max: height > 0 ? height : 1, ...(inverse ? { inverse: true } : {}), show: false };
+}
+/** The branches of one dendrogram: one elbow of lines for each edge, in the order of the tree table. */
+function dendrogramSeries(gridIndex, tree, axis) {
+    return {
+        type: "lines",
+        coordinateSystem: "cartesian2d",
+        xAxisIndex: gridIndex,
+        yAxisIndex: gridIndex,
+        polyline: true,
+        silent: true,
+        clip: false,
+        lineStyle: { color: CHART_INK, width: DENDROGRAM_LINE_PX, opacity: 1 },
+        data: tree.elbows.map((elbow) => ({ coords: axis === "x" ? elbow.map((point) => [point[0], point[1]]) : elbow.map((point) => [point[1], point[0]]) })),
+    };
+}
+/**
+ * The band under the matrix of a taller body, in pixels: the axis title, and the x labels as the layout
+ * discipline turns them. A hidden label takes no room.
+ */
+function underBand(xCategories, hidden) {
+    if (hidden)
+        return TITLE_BAND_PX;
+    if (xCategories.length <= TURN_45_COUNT)
+        return TITLE_BAND_PX + LEVEL_LABEL_PX;
+    let longest = 0;
+    for (const category of xCategories)
+        longest = Math.max(longest, String(category).length);
+    const length = longest * CHART_PAGE_TEXT_PX * LABEL_CHARACTER_SHARE;
+    return TITLE_BAND_PX + Math.ceil(xCategories.length <= TURN_90_COUNT ? length * Math.SQRT1_2 : length);
+}
+/** The band under the matrix as a share of the body, which stops at the largest body. */
+function bandShare(band, body) {
+    return `${Math.round((band / Math.min(body, CHART_BODY_MAX_PX)) * 1e6) / 1e4}%`;
+}
+/**
+ * The strip of each track column. The categories of a strip take the order in which the x axis meets them.
+ * An x category that no row gives a value draws no cell in the strip. A track with no value for any x category
+ * refuses, because its legend would hold no entry, and the runtime then draws a legend of number ranges.
+ */
+function trackStrips(block, rows, context, xColumn, xCategories, tracks) {
+    const strips = [];
+    for (const track of tracks) {
+        const column = present(block.id, rows, context, track);
+        if (column.isErr())
+            return err(column.error);
+        const held = new Map();
+        for (const row of rows) {
+            const category = row[xColumn];
+            const value = row[track];
+            if (category === undefined || value === undefined || value === "")
+                continue;
+            const key = cellKey(category);
+            const prior = held.get(key);
+            if (prior !== undefined && cellKey(prior) !== cellKey(value)) {
+                return err(chartProblem(block.id, `The track column "${track}" holds two values, "${String(prior)}" and "${String(value)}", for the x category "${String(category)}". A track holds one value for each x category.`));
+            }
+            held.set(key, value);
+        }
+        const along = xCategories.map((category) => held.get(cellKey(category)) ?? null);
+        const values = [];
+        const codeOf = new Map();
+        for (const value of along) {
+            if (value === null || codeOf.has(cellKey(value)))
+                continue;
+            codeOf.set(cellKey(value), values.length);
+            values.push(value);
+        }
+        if (values.length === 0 && xCategories.length > 0) {
+            return err(chartProblem(block.id, `The track column "${track}" holds no value for any x category.`));
+        }
+        strips.push({
+            title: declaredForColumn(context.labels, track) ?? categoryName(track),
+            values,
+            codes: along.map((value) => (value === null ? null : (codeOf.get(cellKey(value)) ?? null))),
+        });
+    }
+    return ok(strips);
+}

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

@@ -0,0 +1,135 @@
+/**
+ * The figure registry: one module for each chart type that draws the canonical figure of its field.
+ *
+ * A canonical figure often draws more than the series of one grid over one table: a table under the plot, a
+ * text column beside it, stacked panels, a glyph in a cell, or a track from a second table. Thus a figure is a
+ * module of its own, and `deriveRaw` in `chart.ts` asks this registry before every other path. A base type
+ * with no module keeps its fixed rule. A preset with no module refuses, because no other path draws it.
+ *
+ * A module states the members of the block that it reads. The dispatch refuses each other member before the
+ * module runs, thus a module never meets a channel that it would drop in silence.
+ *
+ * A module is a pure function of the block, the rows, and the context. It reads no clock, no random value, and
+ * no locale, and its option holds no function, because the option rides to the page as inline JSON.
+ */
+import type { Result } from "neverthrow";
+import type { ChartBlock, ChartComposition, ChartEncoding, ChartType } from "../../contracts/report-blocks.js";
+import type { PresetAxisTitles, PresetClassification } from "../chart-presets.js";
+import type { ChartRow, EchartOption } from "../chart.js";
+import type { RenderProblem } from "../types.js";
+import type { ColumnLabels, ColumnMeanings, FigureStatistic } from "./common.js";
+/**
+ * The presets that exist as a figure module alone. No composition expands them, thus each one draws only
+ * through its module.
+ */
+export declare const FIGURE_PRESET_TYPES: readonly ["pca", "embedding", "dotplot", "forest", "roc", "qq", "gsea", "oncoprint", "lollipop", "upset", "sankey", "locuszoom"];
+/** One preset that exists as a figure module alone. */
+export type FigurePresetType = (typeof FIGURE_PRESET_TYPES)[number];
+/** True when the chart type exists as a figure module alone. */
+export declare function isFigurePresetType(chartType: ChartType): chartType is FigurePresetType;
+/**
+ * The chart types that draw through a figure module alone: each figure preset, the heatmap, and the four
+ * presets of the first grammar. No base rule draws the annotation strips of a heatmap, thus the heatmap keeps
+ * no base rule beside its module. The volcano, the MA plot, the Manhattan plot, and the Kaplan-Meier curve
+ * each draw elements that no composition holds, thus none of them keeps an expansion beside its module.
+ */
+export declare const MODULE_ONLY_TYPES: readonly ["pca", "embedding", "dotplot", "forest", "roc", "qq", "gsea", "oncoprint", "lollipop", "upset", "sankey", "locuszoom", "heatmap", "volcano", "ma", "manhattan", "km"];
+/** One chart type that draws through a figure module alone. */
+export type ModuleOnlyType = (typeof MODULE_ONLY_TYPES)[number];
+/** True when the chart type draws through a figure module alone. */
+export declare function isModuleOnlyType(chartType: ChartType): chartType is ModuleOnlyType;
+/**
+ * One member of a chart block that a figure can read: a channel of the quick-path encoding, the statistics,
+ * the track, the trees, or the focus.
+ */
+export type FigureMember = keyof ChartEncoding | "statistics" | "track" | "trees" | "focus";
+/**
+ * The resolved track of a figure: the rows of the second table, its declared column order, and the columns
+ * that the block names in it. The labels and the meanings are the declarations of the track binding.
+ */
+export interface FigureTrack {
+    readonly rows: readonly ChartRow[];
+    readonly columns?: readonly string[];
+    readonly start: string;
+    readonly end: string;
+    readonly label: string;
+    readonly length?: string;
+    readonly labels: ColumnLabels;
+    readonly meanings: ColumnMeanings;
+}
+/**
+ * The resolved tree of one category axis: the edge rows of the tree table, its declared column order, and the
+ * three columns that the block names in it. The labels and the meanings are the declarations of the tree
+ * binding.
+ */
+export interface FigureTree {
+    readonly rows: readonly ChartRow[];
+    readonly columns?: readonly string[];
+    readonly parent: string;
+    readonly child: string;
+    readonly height: string;
+    readonly labels: ColumnLabels;
+    readonly meanings: ColumnMeanings;
+}
+/**
+ * The parts of a preset that a figure hands to the composition machinery: the semantic axis titles, and the
+ * per-row classification where the figure splits the rows itself. `colorOnTop` draws the points of a
+ * continuous color in the ascending order of the color, inline and on the page, thus the high values draw on
+ * top.
+ *
+ * `keepsRowsInline` keeps the rows of the composition inline whatever their size. A figure that rewrites the
+ * items of the composition output states it, because the page builds each item from the cells and never
+ * from the rewrite.
+ */
+export interface FigureComposeExtras {
+    readonly preset?: PresetAxisTitles;
+    readonly classification?: PresetClassification;
+    readonly colorOnTop?: boolean;
+    readonly keepsRowsInline?: boolean;
+}
+/**
+ * What one figure reads beside its block and its rows.
+ *
+ * - `labels` and `meanings` are the declarations of the bound table, and `columns` is its declared column
+ *   order.
+ * - `statistics` holds each statistic of the block in block order, with its resolved value and its shown text.
+ *   A block with no statistic gives an empty list.
+ * - `track` is the resolved second table, where the block binds one.
+ * - `trees` holds the resolved tree of each axis that the block binds one for.
+ * - `textPx` is the text size of the page. The export scales each `graphic` text from it.
+ * - `compose` derives one composition over the bound rows through the shared machinery of `chart.ts`. A dense
+ *   figure builds its primary series here, thus the series reads the shared payload of its artifact past the
+ *   inline bound. A figure can add series after the result, and each such series keeps its rows inline. A
+ *   figure that puts a series before the result keeps the whole chart inline, because the page fills the
+ *   leading series from the descriptors of the composition.
+ */
+export interface FigureContext {
+    readonly blockId: string;
+    readonly labels: ColumnLabels;
+    readonly meanings: ColumnMeanings;
+    readonly columns?: readonly string[];
+    readonly statistics: readonly FigureStatistic[];
+    readonly track?: FigureTrack;
+    readonly trees?: {
+        readonly x?: FigureTree;
+        readonly y?: FigureTree;
+    };
+    readonly textPx: number;
+    readonly compose: (composition: ChartComposition, extras?: FigureComposeExtras) => Result<EchartOption, RenderProblem>;
+}
+/** The derivation of one figure: the raw option, before the layout discipline and the figure rules. */
+export type FigureDerivation = (block: ChartBlock, rows: readonly ChartRow[], context: FigureContext) => Result<EchartOption, RenderProblem>;
+/** One figure module: the members of the block that it reads, and its derivation. */
+export interface FigureModule {
+    readonly reads: ReadonlySet<FigureMember>;
+    readonly derive: FigureDerivation;
+}
+/** The figure module of each chart type that has one. */
+export type FigureRegistry = Readonly<Partial<Record<ChartType, FigureModule>>>;
+/** The registered figure modules. A module joins by one entry here, keyed by its chart type. */
+export declare const FIGURE_MODULES: FigureRegistry;
+/**
+ * The chart types that read each member that the canonical figures add. The refusal of such a member names
+ * these types, and the teaching text of the member names the same ones.
+ */
+export declare const FIGURE_MEMBER_READERS: Readonly<Record<"shape" | "p" | "censor" | "risk" | "hit" | "metric" | "tracks" | "statistics" | "track" | "trees", readonly ChartType[]>>;

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

@@ -0,0 +1,100 @@
+/**
+ * The figure registry: one module for each chart type that draws the canonical figure of its field.
+ *
+ * A canonical figure often draws more than the series of one grid over one table: a table under the plot, a
+ * text column beside it, stacked panels, a glyph in a cell, or a track from a second table. Thus a figure is a
+ * module of its own, and `deriveRaw` in `chart.ts` asks this registry before every other path. A base type
+ * with no module keeps its fixed rule. A preset with no module refuses, because no other path draws it.
+ *
+ * A module states the members of the block that it reads. The dispatch refuses each other member before the
+ * module runs, thus a module never meets a channel that it would drop in silence.
+ *
+ * A module is a pure function of the block, the rows, and the context. It reads no clock, no random value, and
+ * no locale, and its option holds no function, because the option rides to the page as inline JSON.
+ */
+import { GSEA_FIGURE } from "./gsea.js";
+import { LOLLIPOP_FIGURE } from "./lollipop.js";
+import { ONCOPRINT_FIGURE } from "./oncoprint.js";
+import { FOREST_FIGURE } from "./forest.js";
+import { KM_FIGURE } from "./km.js";
+import { ROC_FIGURE } from "./roc.js";
+import { MA_FIGURE } from "./ma.js";
+import { MANHATTAN_FIGURE } from "./manhattan.js";
+import { QQ_FIGURE } from "./qq.js";
+import { VOLCANO_FIGURE } from "./volcano.js";
+import { DOTPLOT_FIGURE } from "./dotplot.js";
+import { EMBEDDING_FIGURE } from "./embedding.js";
+import { HEATMAP_FIGURE } from "./heatmap.js";
+import { PCA_FIGURE } from "./pca.js";
+import { UPSET_FIGURE } from "./upset.js";
+import { SANKEY_FIGURE } from "./sankey.js";
+import { LOCUSZOOM_FIGURE } from "./locuszoom.js";
+/**
+ * The presets that exist as a figure module alone. No composition expands them, thus each one draws only
+ * through its module.
+ */
+export const FIGURE_PRESET_TYPES = [
+    "pca",
+    "embedding",
+    "dotplot",
+    "forest",
+    "roc",
+    "qq",
+    "gsea",
+    "oncoprint",
+    "lollipop",
+    "upset",
+    "sankey",
+    "locuszoom",
+];
+/** True when the chart type exists as a figure module alone. */
+export function isFigurePresetType(chartType) {
+    return FIGURE_PRESET_TYPES.includes(chartType);
+}
+/**
+ * The chart types that draw through a figure module alone: each figure preset, the heatmap, and the four
+ * presets of the first grammar. No base rule draws the annotation strips of a heatmap, thus the heatmap keeps
+ * no base rule beside its module. The volcano, the MA plot, the Manhattan plot, and the Kaplan-Meier curve
+ * each draw elements that no composition holds, thus none of them keeps an expansion beside its module.
+ */
+export const MODULE_ONLY_TYPES = [...FIGURE_PRESET_TYPES, "heatmap", "volcano", "ma", "manhattan", "km"];
+/** True when the chart type draws through a figure module alone. */
+export function isModuleOnlyType(chartType) {
+    return MODULE_ONLY_TYPES.includes(chartType);
+}
+/** The registered figure modules. A module joins by one entry here, keyed by its chart type. */
+export const FIGURE_MODULES = {
+    km: KM_FIGURE,
+    forest: FOREST_FIGURE,
+    roc: ROC_FIGURE,
+    gsea: GSEA_FIGURE,
+    oncoprint: ONCOPRINT_FIGURE,
+    lollipop: LOLLIPOP_FIGURE,
+    volcano: VOLCANO_FIGURE,
+    ma: MA_FIGURE,
+    manhattan: MANHATTAN_FIGURE,
+    qq: QQ_FIGURE,
+    pca: PCA_FIGURE,
+    embedding: EMBEDDING_FIGURE,
+    dotplot: DOTPLOT_FIGURE,
+    heatmap: HEATMAP_FIGURE,
+    upset: UPSET_FIGURE,
+    sankey: SANKEY_FIGURE,
+    locuszoom: LOCUSZOOM_FIGURE,
+};
+/**
+ * The chart types that read each member that the canonical figures add. The refusal of such a member names
+ * these types, and the teaching text of the member names the same ones.
+ */
+export const FIGURE_MEMBER_READERS = {
+    shape: ["pca", "scatter"],
+    p: ["ma", "forest"],
+    censor: ["km"],
+    risk: ["km"],
+    hit: ["gsea"],
+    metric: ["gsea", "locuszoom"],
+    tracks: ["heatmap", "oncoprint"],
+    statistics: ["km", "roc", "qq", "gsea"],
+    track: ["lollipop", "locuszoom"],
+    trees: ["heatmap"],
+};

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

@@ -0,0 +1,16 @@
+/**
+ * The Kaplan-Meier figure: one step curve for each group, the confidence band as a step band, a tick at each
+ * censored row, the number-at-risk table under the plot, the median lines, and the statistics text.
+ *
+ * The figure plots the precomputed survival of the table, and it fits no curve. It computes two lookups from
+ * the rows, and each one reads the rows of one group alone:
+ *
+ * - The number at risk at each tick of the time axis is the risk of the first row at or after the tick, and 0
+ *   past the last row of the group. A risk table that does not sit at the axis ticks misleads, thus the figure
+ *   sets the ticks itself and reads the table at them.
+ * - The median of a group is the time of the first row whose survival is at or under 0.5. A curve that never
+ *   reaches 0.5 has no median, and it takes no median line.
+ */
+import type { FigureModule } from "./index.js";
+/** The Kaplan-Meier survival figure. */
+export declare const KM_FIGURE: FigureModule;