@inflexa-ai/harness 0.42.2 → 0.43.0

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

@@ -0,0 +1,234 @@
+/**
+ * The dot plot: a marker dot plot of a single-cell study, or the enrichment dot plot of a gene-set test.
+ *
+ * The canonical marker dot plot is the scanpy `pl.dotplot` and the Seurat `DotPlot`: the clusters down the y
+ * axis, the genes along x, the fraction of expressing cells as the dot size, and the mean expression as the
+ * dot color. The canonical enrichment dot plot is the enrichplot `dotplot`: the terms down the y axis, the gene
+ * ratio along x, the gene count as the dot size, and the adjusted p as the dot color. Each plot shows two
+ * keys: a size legend of three reference circles, and a sequential color scale with its two ends.
+ *
+ * The y axis reads top-down in the order of its channel, thus a table that sorts its terms by their ratio
+ * reads from the first term down. The x axis draws categories where its column holds text, and values where
+ * it holds numbers.
+ *
+ * The dots build through the composition machinery. The figure moves each dot onto the place of its category,
+ * and the page builds no such move, thus the rows stay inline whatever their count.
+ */
+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, SEQUENTIAL_RAMP } from "../design.js";
+import { categoryAxis, categoryAxisTitle, chartProblem, colorScale, orderQuickCategories, sizeLegend, toNumber, transformedTitle, withFigureBody, } from "./common.js";
+/** The band at the right of the plot that holds the color scale and the size legend, in percent of the width. */
+const DOTPLOT_KEY_BAND = "28%";
+/** The top of the color scale, and its length in pixels. The size legend sits under it. */
+const DOTPLOT_SCALE_TOP = "8%";
+const DOTPLOT_SCALE_LENGTH_PX = 100;
+/** The place of the size legend: at the bottom right corner, under the color scale. */
+const DOTPLOT_SIZE_PLACE = { right: 8, bottom: 8 };
+/**
+ * The room at each end of a value axis of dots, as a share of the axis. The largest dot sits at an end of the
+ * data, and the room keeps it inside the plot.
+ */
+const DOTPLOT_VALUE_ROOM = ["6%", "6%"];
+/**
+ * The longest category name that a y label draws on one line, in characters. enrichplot wraps a term at 30
+ * characters, thus a long term takes two lines and the plot keeps its width.
+ */
+const DOTPLOT_WRAP_CHARACTERS = 30;
+/** The most lines of one term. A longer term ends its last line with an ellipsis. */
+const DOTPLOT_TERM_LINES = 2;
+/** The height of one line of a y label, and the gap between two terms, in pixels at the page text size. */
+export const DOTPLOT_LINE_PX = 14;
+export const DOTPLOT_ROW_GAP_PX = 6;
+/**
+ * The share of the body that the plot takes at least: the layout discipline gives the top margin and the band
+ * of the turned x labels and the x title.
+ */
+const DOTPLOT_PLOT_SHARE = 2 / 3;
+/**
+ * One term wrapped at its spaces into lines of 30 characters at most, two lines at most. A term past two lines
+ * ends its second line with an ellipsis, thus two terms never run into each other. A word longer than a line
+ * stays whole.
+ */
+export function wrappedTerm(term) {
+    const lines = [];
+    let line = "";
+    for (const word of term.split(" ")) {
+        if (line === "")
+            line = word;
+        else if (line.length + 1 + word.length <= DOTPLOT_WRAP_CHARACTERS)
+            line = `${line} ${word}`;
+        else {
+            lines.push(line);
+            line = word;
+        }
+    }
+    if (line !== "")
+        lines.push(line);
+    if (lines.length <= DOTPLOT_TERM_LINES)
+        return lines.join("\n");
+    const kept = lines.slice(0, DOTPLOT_TERM_LINES);
+    const last = kept[DOTPLOT_TERM_LINES - 1].split(" ");
+    while (last.length > 1 && `${last.join(" ")}…`.length > DOTPLOT_WRAP_CHARACTERS)
+        last.pop();
+    kept[DOTPLOT_TERM_LINES - 1] = `${last.join(" ")}…`;
+    return kept.join("\n");
+}
+/**
+ * The column name that formats the ends of a transformed scale. A transform gives a number that is no p-value
+ * and no count, thus its ends format as a plain number whatever the source column.
+ */
+const TRANSFORMED_COLUMN = "value";
+/** The dot plot. */
+export const DOTPLOT_FIGURE = {
+    reads: new Set(["x", "y", "size", "color", "label"]),
+    derive: deriveDotplot,
+};
+/** The title of a scale over one channel: the declared label or the column, inside its transform. */
+function scaleTitle(labels, channel) {
+    const column = channelColumn(channel);
+    const base = declaredForColumn(labels, column) ?? column;
+    const transform = channelTransform(channel);
+    return transform === undefined ? base : transformedTitle(transform, base);
+}
+/**
+ * The column name and the meaning that format the ends of a scale over one channel. A transformed channel
+ * formats as a plain number, because its value is no p-value and no count of the source column.
+ */
+function formatSource(context, channel) {
+    if (channelTransform(channel) !== undefined)
+        return [TRANSFORMED_COLUMN, undefined];
+    const column = channelColumn(channel);
+    return [column, declaredForColumn(context.meanings, column)];
+}
+/** The members of one item: the array form, or the value of the object form. */
+function itemValue(item) {
+    if (Array.isArray(item))
+        return item;
+    if (typeof item === "object" && item !== null && Array.isArray(item.value))
+        return item.value;
+    return undefined;
+}
+/** One item with its y member set to the place of its category. */
+function placedItem(item, place) {
+    const value = itemValue(item);
+    if (value === undefined)
+        return item;
+    const moved = [value[0], place, ...value.slice(2)];
+    return Array.isArray(item) ? moved : { ...item, value: moved };
+}
+function deriveDotplot(block, rows, context) {
+    const encoding = block.encoding ?? {};
+    const { x, y, size, color, label } = encoding;
+    if (x === undefined || y === undefined) {
+        return err(chartProblem(block.id, `The dotplot chart needs a column for the "${x === undefined ? "x" : "y"}" channel.`));
+    }
+    if (size === undefined && color === undefined) {
+        return err(chartProblem(block.id, 'The dotplot sizes its dots by a "size" channel and colors them by a "color" channel. Name one of the two at least.'));
+    }
+    if (channelTransform(y) !== undefined) {
+        return err(chartProblem(block.id, 'The "y" channel of the dotplot names categories, thus it takes no transform.'));
+    }
+    const yColumn = channelColumn(y);
+    const categories = orderQuickCategories(block.id, rows, yColumn, channelOrder(y));
+    if (categories.isErr())
+        return err(categories.error);
+    const composition = {
+        series: [
+            {
+                form: "scatter",
+                encoding: {
+                    x,
+                    // The figure orders the y categories itself, thus the composition reads the plain column.
+                    y: yColumn,
+                    ...(size !== undefined ? { size } : {}),
+                    ...(color !== undefined ? { color } : {}),
+                    ...(label !== undefined ? { label } : {}),
+                },
+            },
+        ],
+    };
+    // The figure moves each dot onto the place of its term, thus the rows stay inline.
+    const composed = context.compose(composition, { keepsRowsInline: true });
+    if (composed.isErr())
+        return err(composed.error);
+    const option = composed.value;
+    const places = new Map(categories.value.map((category, place) => [String(category), place]));
+    const series = (Array.isArray(option.series) ? option.series : []).map((entry) => ({
+        ...entry,
+        data: (Array.isArray(entry.data) ? entry.data : []).flatMap((item) => {
+            const place = places.get(String(itemValue(item)?.[1]));
+            return place === undefined ? [] : [placedItem(item, place)];
+        }),
+    }));
+    const wraps = categories.value.some((category) => String(category).length > DOTPLOT_WRAP_CHARACTERS);
+    // The series place each dot by the index of its term, thus the axis can show the wrapped text of a term.
+    const terms = wraps ? categories.value.map((category) => wrappedTerm(String(category))) : undefined;
+    const yAxis = {
+        ...categoryAxis("y", terms ?? categories.value, { title: categoryAxisTitle(context.labels, yColumn), topDown: true }),
+        ...(wraps ? { axisLabel: { lineHeight: DOTPLOT_LINE_PX } } : {}),
+    };
+    const lines = terms === undefined ? 1 : highestOf(terms.map((term) => term.split("\n").length));
+    const body = (categories.value.length * (lines * DOTPLOT_LINE_PX + DOTPLOT_ROW_GAP_PX)) / DOTPLOT_PLOT_SHARE;
+    const maps = Array.isArray(option.visualMap) ? option.visualMap : [];
+    const keys = [];
+    const graphic = [];
+    const colorMap = maps.find((entry) => entry.show !== false);
+    if (color !== undefined && colorMap !== undefined) {
+        const values = drawnMembers(series, 2);
+        const scale = { min: lowestOf(values), max: highestOf(values), ramp: SEQUENTIAL_RAMP };
+        const { right: _right, top: _top, ...scaled } = colorScale(scale, scaleTitle(context.labels, color), ...formatSource(context, color));
+        keys.push({ ...colorMap, ...scaled, right: 0, top: DOTPLOT_SCALE_TOP, itemHeight: DOTPLOT_SCALE_LENGTH_PX });
+    }
+    const sizeMaps = maps.filter((entry) => entry.show === false);
+    keys.push(...sizeMaps);
+    if (size !== undefined && sizeMaps.length > 0) {
+        const range = { min: toNumber(sizeMaps[0].min) ?? 0, max: toNumber(sizeMaps[0].max) ?? 0 };
+        graphic.push(sizeLegend(range, scaleTitle(context.labels, size), formatSource(context, size)[0], DOTPLOT_SIZE_PLACE, formatSource(context, size)[1]));
+    }
+    const composedX = typeof option.xAxis === "object" && option.xAxis !== null ? option.xAxis : {};
+    const xAxis = composedX.type === "value"
+        ? { ...composedX, boundaryGap: [...DOTPLOT_VALUE_ROOM], axisLabel: { ...composedX.axisLabel, hideOverlap: true } }
+        : composedX;
+    const drawn = {
+        ...option,
+        series,
+        xAxis,
+        yAxis,
+        visualMap: keys,
+        ...(graphic.length > 0 ? { graphic } : {}),
+        legend: { show: false },
+        // The grid holds its labels and its titles inside the chart, as the runtime does by default.
+        grid: { right: DOTPLOT_KEY_BAND },
+    };
+    return ok(body > CHART_BODY_PX ? withFigureBody(drawn, body) : drawn);
+}
+/** The members at one dimension of each item of some series. */
+function drawnMembers(series, dimension) {
+    const members = [];
+    for (const entry of series) {
+        for (const item of Array.isArray(entry.data) ? entry.data : []) {
+            const member = toNumber(itemValue(item)?.[dimension]);
+            if (member !== null)
+                members.push(member);
+        }
+    }
+    return members;
+}
+/** The smallest of some values, or zero for none. */
+function lowestOf(values) {
+    let low = values.length > 0 ? values[0] : 0;
+    for (const value of values)
+        if (value < low)
+            low = value;
+    return low;
+}
+/** The largest of some values, or one for none. */
+function highestOf(values) {
+    let high = values.length > 0 ? values[0] : 1;
+    for (const value of values)
+        if (value > high)
+            high = value;
+    return high;
+}

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

@@ -0,0 +1,43 @@
+/**
+ * The embedding of cells: a UMAP or a t-SNE, one point for each cell.
+ *
+ * The canonical figure is the scanpy `pl.umap` and the Seurat `DimPlot` of a single-cell study. The two
+ * coordinates carry no unit that a reader reads, thus the axes hide, and a small key at the bottom left corner
+ * names the two dimensions. One unit on x equals one unit on y, because the embedding places near cells near.
+ * The point size follows the cell count by the scanpy rule, and the points draw with a light opacity, thus a
+ * dense cluster reads by its shape.
+ *
+ * A `group` colors the cells by category, and each category name draws on the data at the median place of its
+ * cells, as scanpy `legend_loc="on data"` does. No legend draws beside the names. A `color` colors the cells on
+ * a continuous scale: a zero draws in a light gray ground, the scale clips at the 99th percentile, and the high
+ * values draw on top. A `facet` splits the cells into panels of one shared range.
+ *
+ * The points build through the composition machinery, thus a dense table reads the shared payload of its
+ * artifact. The names of the categories draw as a small series after the points, and it keeps its rows inline.
+ */
+import type { FigureModule } from "./index.js";
+/** The scanpy point area of one cell, in square points, for each cell of the plot: 120000 / n. */
+export declare const SCANPY_AREA_PT2 = 120000;
+/** The bounds of the point diameter of an embedding, in pixels. */
+export declare const EMBEDDING_POINT_MIN_PX = 1;
+export declare const EMBEDDING_POINT_MAX_PX = 6;
+/** The opacity of a point of an embedding. An overlap of cells reads darker than a lone cell. */
+export declare const EMBEDDING_OPACITY = 0.6;
+/** The ground color of a cell whose continuous value is zero: the light gray of the Seurat `FeaturePlot`. */
+export declare const EMBEDDING_GROUND = "#d3d3d3";
+/** The percentile at which the continuous scale of an embedding clips, as scanpy `vmax="p99"` does. */
+export declare const EMBEDDING_CLIP_QUANTILE = 0.99;
+/**
+ * The cell count from which the points draw on the large path of the runtime. The large path draws a square
+ * for each point, thus a smaller embedding draws round points as scanpy does. The large path fills each point
+ * with the one color of its series and reads no per-point color of a scale, thus a continuous color never
+ * takes it.
+ */
+export declare const EMBEDDING_LARGE_CELLS = 50000;
+/** The embedding of cells. */
+export declare const EMBEDDING_FIGURE: FigureModule;
+/**
+ * The point diameter of an embedding of `cells` cells, in pixels: the scanpy area 120000 / n in square points,
+ * as a diameter at 96 pixels for each inch, bounded to the embedding range.
+ */
+export declare function embeddingPointPx(cells: number): number;

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

@@ -0,0 +1,360 @@
+/**
+ * The embedding of cells: a UMAP or a t-SNE, one point for each cell.
+ *
+ * The canonical figure is the scanpy `pl.umap` and the Seurat `DimPlot` of a single-cell study. The two
+ * coordinates carry no unit that a reader reads, thus the axes hide, and a small key at the bottom left corner
+ * names the two dimensions. One unit on x equals one unit on y, because the embedding places near cells near.
+ * The point size follows the cell count by the scanpy rule, and the points draw with a light opacity, thus a
+ * dense cluster reads by its shape.
+ *
+ * A `group` colors the cells by category, and each category name draws on the data at the median place of its
+ * cells, as scanpy `legend_loc="on data"` does. No legend draws beside the names. A `color` colors the cells on
+ * a continuous scale: a zero draws in a light gray ground, the scale clips at the 99th percentile, and the high
+ * values draw on top. A `facet` splits the cells into panels of one shared range.
+ *
+ * The points build through the composition machinery, thus a dense table reads the shared payload of its
+ * artifact. The names of the categories draw as a small series after the points, and it keeps its rows inline.
+ */
+import { err, ok } from "neverthrow";
+import { channelColumn, channelOrder, channelTransform } from "../../contracts/report-blocks.js";
+import { declaredForColumn } from "../../contracts/report-reference.js";
+import { CHART_INK, CHART_PAGE_TEXT_PX, DIVERGING_RAMP, SEQUENTIAL_RAMP } from "../design.js";
+import { categoricalPalette, categoryName, chartProblem, colorScale, firstAppearance, toNumber, transformColumn, valueAxisTitle } from "./common.js";
+import { equalRanges, squareLayout } from "./equal-units.js";
+import { nameAnchors } from "./label-room.js";
+/** The scanpy point area of one cell, in square points, for each cell of the plot: 120000 / n. */
+export const SCANPY_AREA_PT2 = 120_000;
+/** The bounds of the point diameter of an embedding, in pixels. */
+export const EMBEDDING_POINT_MIN_PX = 1;
+export const EMBEDDING_POINT_MAX_PX = 6;
+/** The opacity of a point of an embedding. An overlap of cells reads darker than a lone cell. */
+export const EMBEDDING_OPACITY = 0.6;
+/** The ground color of a cell whose continuous value is zero: the light gray of the Seurat `FeaturePlot`. */
+export const EMBEDDING_GROUND = "#d3d3d3";
+/** The percentile at which the continuous scale of an embedding clips, as scanpy `vmax="p99"` does. */
+export const EMBEDDING_CLIP_QUANTILE = 0.99;
+/** The share of the longer span that pads each side of an embedding. */
+const EMBEDDING_PAD = 0.03;
+/**
+ * The margins of the squares of an embedding, in pixels: the panel name over each square, and the corner key
+ * under and beside the first square.
+ */
+const EMBEDDING_MARGINS = { top: 22, bottom: 22, left: 22, right: 8 };
+/**
+ * The smallest width of the band of the color scale at the right of the squares, in pixels. A longer scale
+ * title widens the band to its own width, thus the narrowed page body never cuts it.
+ */
+const EMBEDDING_SCALE_BAND_PX = 96;
+/** The width of one character of the scale title, as a share of the page text size, and the pad of the band. */
+const SCALE_CHARACTER_SHARE = 0.6;
+const SCALE_BAND_PAD_PX = 8;
+/** The arrow of the corner key. It points along the axis that its dimension names. */
+const KEY_ARROW = " →";
+/** The width of the white outline of a category name on the data, in pixels, as scanpy `legend_fontoutline=2`. */
+const NAME_OUTLINE_PX = 2;
+/**
+ * The cell count from which the points draw on the large path of the runtime. The large path draws a square
+ * for each point, thus a smaller embedding draws round points as scanpy does. The large path fills each point
+ * with the one color of its series and reads no per-point color of a scale, thus a continuous color never
+ * takes it.
+ */
+export const EMBEDDING_LARGE_CELLS = 50_000;
+/** The drawing order of the category names, over each point. */
+const NAME_Z = 10;
+/** The axis parts that an embedding hides: the line, the ticks, the tick labels, and the grid lines. */
+const HIDDEN_AXIS_PARTS = {
+    axisLine: { show: false },
+    axisTick: { show: false },
+    axisLabel: { show: false },
+    splitLine: { show: false },
+};
+/** The embedding of cells. */
+export const EMBEDDING_FIGURE = {
+    reads: new Set(["x", "y", "group", "color", "facet", "label"]),
+    derive: deriveEmbedding,
+};
+/**
+ * The point diameter of an embedding of `cells` cells, in pixels: the scanpy area 120000 / n in square points,
+ * as a diameter at 96 pixels for each inch, bounded to the embedding range.
+ */
+export function embeddingPointPx(cells) {
+    const areaPt2 = SCANPY_AREA_PT2 / Math.max(1, cells);
+    const diameterPx = 2 * Math.sqrt(areaPt2 / Math.PI) * (96 / 72);
+    return Math.round(Math.min(EMBEDDING_POINT_MAX_PX, Math.max(EMBEDDING_POINT_MIN_PX, diameterPx)) * 10) / 10;
+}
+/** The value of one channel in each row: the transformed number where the channel declares a transform. */
+function channelValues(rows, channel) {
+    const column = channelColumn(channel);
+    const transform = channelTransform(channel);
+    return transform === undefined ? rows.map((row) => row[column] ?? null) : transformColumn(rows, column, transform);
+}
+/** The axis name of one channel: the column, with its transform where it declares one. */
+function channelName(channel) {
+    const transform = channelTransform(channel);
+    return transform === undefined ? channelColumn(channel) : `${transform}(${channelColumn(channel)})`;
+}
+function deriveEmbedding(block, rows, context) {
+    const encoding = block.encoding ?? {};
+    const { x, y, group, color, facet, label } = encoding;
+    if (x === undefined || y === undefined) {
+        return err(chartProblem(block.id, `The embedding chart needs a column for the "${x === undefined ? "x" : "y"}" channel.`));
+    }
+    if (group === undefined && color === undefined) {
+        return err(chartProblem(block.id, 'The embedding colors its cells by a "group" channel or by a "color" channel. Name one of the two.'));
+    }
+    if (group !== undefined && color !== undefined) {
+        return err(chartProblem(block.id, 'A "color" channel beside a "group" channel is a fault, because one chart colors by one channel.'));
+    }
+    for (const [member, channel] of [
+        ["x", x],
+        ["y", y],
+    ]) {
+        if (channelOrder(channel) !== undefined) {
+            return err(chartProblem(block.id, `The "${member}" channel of the embedding draws a hidden value axis, thus it takes no "orderBy".`));
+        }
+    }
+    const composition = {
+        series: [
+            {
+                form: "scatter",
+                encoding: {
+                    x,
+                    y,
+                    ...(group !== undefined ? { group } : {}),
+                    ...(color !== undefined ? { color } : {}),
+                    ...(label !== undefined ? { label } : {}),
+                },
+            },
+        ],
+        ...(facet !== undefined ? { facet } : {}),
+    };
+    const composed = context.compose(composition, color !== undefined ? { colorOnTop: true } : {});
+    if (composed.isErr())
+        return err(composed.error);
+    const xs = channelValues(rows, x);
+    const ys = channelValues(rows, y);
+    const groups = group === undefined ? undefined : channelValues(rows, group);
+    const colors = color === undefined ? undefined : channelValues(rows, color);
+    const facets = facet === undefined ? undefined : rows.map((row) => row[channelColumn(facet)] ?? null);
+    const panelNames = facets === undefined ? [] : firstAppearance(facets.filter((cell) => cell !== null).map((cell) => `${typeof cell}:${String(cell)}`));
+    const panelOf = new Map(panelNames.map((key, place) => [key, place]));
+    const cells = [];
+    for (let index = 0; index < rows.length; index += 1) {
+        const px = toNumber(xs[index]);
+        const py = toNumber(ys[index]);
+        if (px === null || py === null)
+            continue;
+        const cellGroup = groups?.[index] ?? null;
+        if (groups !== undefined && cellGroup === null)
+            continue;
+        const cellColor = colors === undefined ? null : toNumber(colors[index]);
+        if (colors !== undefined && cellColor === null)
+            continue;
+        const facetCell = facets?.[index] ?? null;
+        if (facets !== undefined && facetCell === null)
+            continue;
+        cells.push({
+            x: px,
+            y: py,
+            panel: facetCell === null ? 0 : (panelOf.get(`${typeof facetCell}:${String(facetCell)}`) ?? 0),
+            ...(cellGroup !== null ? { group: categoryName(cellGroup) } : {}),
+            ...(cellColor !== null ? { color: cellColor } : {}),
+        });
+    }
+    const option = composed.value;
+    const panels = Math.max(1, panelNames.length);
+    const pointPx = embeddingPointPx(cells.length);
+    const series = (Array.isArray(option.series) ? option.series : []).map((entry) => ({
+        ...entry,
+        large: color === undefined && cells.length >= EMBEDDING_LARGE_CELLS,
+        symbolSize: pointPx,
+        itemStyle: {
+            ...(typeof entry.itemStyle === "object" && entry.itemStyle !== null ? entry.itemStyle : {}),
+            opacity: EMBEDDING_OPACITY,
+        },
+    }));
+    const ranges = equalRanges(cells.map((cell) => cell.x), cells.map((cell) => cell.y), { pad: EMBEDDING_PAD, round: false });
+    const scaleTitle = color !== undefined ? valueAxisTitle(context.labels, channelName(color)) : "";
+    const scaleBand = Math.max(EMBEDDING_SCALE_BAND_PX, Math.ceil(scaleTitle.length * CHART_PAGE_TEXT_PX * SCALE_CHARACTER_SHARE) + SCALE_BAND_PAD_PX);
+    const layout = squareLayout({
+        panels,
+        margins: EMBEDDING_MARGINS,
+        side: color !== undefined ? scaleBand : 0,
+        visualMaps: color !== undefined ? 1 : 0,
+        points: { series: series.length, px: pointPx },
+    });
+    const xAxes = [];
+    const yAxes = [];
+    const keyStyle = { color: CHART_INK, align: "left" };
+    for (let panel = 0; panel < panels; panel += 1) {
+        const key = panel === 0;
+        xAxes.push({
+            type: "value",
+            gridIndex: panel,
+            ...ranges.x,
+            ...HIDDEN_AXIS_PARTS,
+            ...(key
+                ? {
+                    name: `${valueAxisTitle(context.labels, channelName(x))}${KEY_ARROW}`,
+                    nameLocation: "start",
+                    nameGap: 0,
+                    nameTextStyle: { ...keyStyle, verticalAlign: "top" },
+                }
+                : {}),
+        });
+        yAxes.push({
+            type: "value",
+            gridIndex: panel,
+            ...ranges.y,
+            ...HIDDEN_AXIS_PARTS,
+            ...(key
+                ? {
+                    name: `${valueAxisTitle(context.labels, channelName(y))}${KEY_ARROW}`,
+                    nameLocation: "start",
+                    nameRotate: 90,
+                    nameGap: 0,
+                    nameTextStyle: { ...keyStyle, verticalAlign: "bottom" },
+                }
+                : {}),
+        });
+    }
+    // Each panel names its facet value on an axis of no series over its square, thus the name moves with the square.
+    for (const [panel, name] of panelNames.entries()) {
+        xAxes.push({
+            type: "value",
+            gridIndex: panel,
+            position: "top",
+            ...HIDDEN_AXIS_PARTS,
+            name: categoryName(name.slice(name.indexOf(":") + 1)),
+            nameLocation: "start",
+            nameGap: 0,
+            nameTextStyle: { color: CHART_INK, align: "left", verticalAlign: "bottom", fontWeight: "bold" },
+        });
+    }
+    const out = {
+        ...(option.tooltip !== undefined ? { tooltip: option.tooltip } : {}),
+        grid: layout.grid,
+        xAxis: xAxes,
+        yAxis: yAxes,
+        series,
+        legend: { show: false },
+        media: layout.media,
+    };
+    if (group !== undefined) {
+        const names = firstAppearance(cells.flatMap((cell) => (cell.group === undefined ? [] : [cell.group])));
+        return ok({
+            ...out,
+            color: [...categoricalPalette(names.length)],
+            series: [...series, ...nameSeries(cells, names, panels, ranges)],
+        });
+    }
+    const colorChannel = color;
+    const map = clippedScale(cells.flatMap((cell) => (cell.color === undefined ? [] : [cell.color])), scaleTitle, channelName(colorChannel), declaredForColumn(context.meanings, channelColumn(colorChannel)));
+    const composedMaps = Array.isArray(option.visualMap) ? option.visualMap : [];
+    const seriesIndex = composedMaps.find((entry) => entry.dimension === 2)?.seriesIndex ?? series.map((_entry, index) => index);
+    const place = layout.visualMap?.[0] ?? {};
+    return ok({ ...out, visualMap: [{ type: "continuous", seriesIndex, dimension: 2, ...map, ...place }] });
+}
+/**
+ * The continuous scale of an embedding, clipped at the 99th percentile of its values.
+ *
+ * A column of no negative value takes the sequential ramp from zero to the percentile. A zero lies outside the
+ * selected range, thus it draws in the gray ground, and a value past the percentile draws in the top color. A
+ * column that crosses zero takes the diverging ramp, symmetric at the percentile of the absolute values, and it
+ * draws no ground, because its zero is the middle of the scale.
+ */
+function clippedScale(values, title, column, meaning) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const negative = sorted.length > 0 && sorted[0] < 0;
+    if (negative) {
+        const reach = quantile(values.map((value) => Math.abs(value)).sort((a, b) => a - b), EMBEDDING_CLIP_QUANTILE);
+        const end = reach > 0 ? reach : 1;
+        return withoutRight(colorScale({ min: -end, max: end, ramp: DIVERGING_RAMP }, title, column, meaning));
+    }
+    const positive = sorted.find((value) => value > 0);
+    const clip = quantile(sorted, EMBEDDING_CLIP_QUANTILE);
+    const top = clip > 0 ? clip : (sorted[sorted.length - 1] ?? 0) > 0 ? sorted[sorted.length - 1] : 1;
+    const low = positive === undefined ? top : Math.min(positive, top);
+    return {
+        ...withoutRight(colorScale({ min: 0, max: top, ramp: SEQUENTIAL_RAMP }, title, column, meaning)),
+        range: [low, top],
+        outOfRange: { color: EMBEDDING_GROUND },
+    };
+}
+/** A color scale with no right edge. The layout places the scale by its left edge in the band. */
+function withoutRight(map) {
+    const { right: _right, ...rest } = map;
+    return rest;
+}
+/**
+ * The linear quantile of sorted values, as numpy and R type 7 give it. An empty list gives zero.
+ */
+function quantile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const place = (sorted.length - 1) * p;
+    const low = Math.floor(place);
+    const high = Math.ceil(place);
+    return sorted[low] + (sorted[high] - sorted[low]) * (place - low);
+}
+/**
+ * The series of the category names on the data: one name for each category of each panel, at the median x and
+ * the median y of its cells.
+ *
+ * The median is the computed summary of this figure. It sits inside the cloud of a curved cluster, where a mean
+ * can fall between two arms. The names draw in the ink with a white outline, over every point. A name that
+ * would cover the name of a larger category moves along y by whole lines inside the square, and a name that
+ * finds no free place in the square draws nothing.
+ */
+function nameSeries(cells, names, panels, plot) {
+    const out = [];
+    for (let panel = 0; panel < panels; panel += 1) {
+        const byName = new Map();
+        for (const cell of cells) {
+            if (cell.panel !== panel || cell.group === undefined)
+                continue;
+            let entry = byName.get(cell.group);
+            if (entry === undefined) {
+                entry = { xs: [], ys: [] };
+                byName.set(cell.group, entry);
+            }
+            entry.xs.push(cell.x);
+            entry.ys.push(cell.y);
+        }
+        const present = names.filter((name) => byName.has(name));
+        const anchors = nameAnchors(present.map((name) => {
+            const entry = byName.get(name) ?? { xs: [], ys: [] };
+            return { x: median(entry.xs), y: median(entry.ys), text: name };
+        }), present.map((name) => byName.get(name)?.xs.length ?? 0), plot);
+        const data = present.flatMap((name, place) => {
+            const anchor = anchors[place];
+            return anchor === undefined ? [] : [{ value: [anchor.x, anchor.y], name }];
+        });
+        out.push({
+            type: "scatter",
+            name: "Category names",
+            silent: true,
+            symbolSize: 0,
+            z: NAME_Z,
+            xAxisIndex: panel,
+            yAxisIndex: panel,
+            tooltip: { show: false },
+            label: {
+                show: true,
+                formatter: "{b}",
+                position: "inside",
+                color: CHART_INK,
+                fontWeight: "bold",
+                textBorderColor: "#ffffff",
+                textBorderWidth: NAME_OUTLINE_PX,
+            },
+            data,
+        });
+    }
+    return out;
+}
+/** The median of some values, read after one sort. */
+function median(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    return Number(quantile(sorted, 0.5).toPrecision(12));
+}