@inflexa-ai/harness 0.42.2 → 0.43.0

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

@@ -0,0 +1,16 @@
+/**
+ * The lollipop: the mutations of one protein along its amino-acid positions, over its domain track.
+ *
+ * The canonical design is the one of maftools and of the cBioPortal mutation view. Each row draws a stem from
+ * zero to its count and a head at the count, in the color of its class. The domains of the track draw as
+ * labeled boxes on a band under the axis, over a gray backbone of the whole protein. The x axis spans the
+ * protein: from zero to the length column of the track, or to the largest end and position where the track
+ * names no length or where one of them passes it. The three largest counts carry the text of the label column.
+ *
+ * The figure computes no summary. Each stem is one row with a class where the block names a class column, each
+ * box is one row of the track, and the lane of a box is the first lane where it overlaps no earlier box, thus
+ * the lanes follow the order of the track rows.
+ */
+import type { FigureModule } from "./index.js";
+/** The lollipop module: the position, the count, the class, the label, and the domain track. */
+export declare const LOLLIPOP_FIGURE: FigureModule;

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

@@ -0,0 +1,247 @@
+/**
+ * The lollipop: the mutations of one protein along its amino-acid positions, over its domain track.
+ *
+ * The canonical design is the one of maftools and of the cBioPortal mutation view. Each row draws a stem from
+ * zero to its count and a head at the count, in the color of its class. The domains of the track draw as
+ * labeled boxes on a band under the axis, over a gray backbone of the whole protein. The x axis spans the
+ * protein: from zero to the length column of the track, or to the largest end and position where the track
+ * names no length or where one of them passes it. The three largest counts carry the text of the label column.
+ *
+ * The figure computes no summary. Each stem is one row with a class where the block names a class column, each
+ * box is one row of the track, and the lane of a box is the first lane where it overlaps no earlier box, thus
+ * the lanes follow the order of the track rows.
+ */
+import { err, ok } from "neverthrow";
+import { channelColumn, channelOrder, channelTransform } from "../../contracts/report-blocks.js";
+import { STEM_RENDERER } from "../chart-renderers.js";
+import { CHART_INK, CHART_PALETTE, GUIDE_LINE_COLOR } from "../design.js";
+import { categoricalPalette, categoryName, chartProblem, columnPresent, firstAppearance, firstFreeLanes, toNumber, valueAxis, valueAxisTitle, } from "./common.js";
+import { classColors, classOf, legendClasses } from "./oncoprint.js";
+/** The semantic title of the position axis and of the count axis. */
+const POSITION_TITLE = "Amino-acid position";
+const COUNT_TITLE = "Mutations";
+/** The count of the largest counts that carry the text of the label column. */
+const LABELED_COUNT = 3;
+/**
+ * The count of characters that the full span of the x axis holds at the single journal column. A box label
+ * takes the share of this count that its box spans, thus a label never runs past its box at that width.
+ */
+const LABEL_CHARS_ACROSS = 60;
+/** The fewest characters that a shortened box label shows. A box too narrow for them draws no label. */
+const LABEL_MIN_CHARS = 4;
+/** The places of the two grids with a track, in percent of the chart: the stems, and the domain band under them. */
+const STEM_GRID = { left: "10%", right: "5%", top: "10%", bottom: "44%" };
+const BAND_GRID = { left: "10%", right: "5%", top: "58%", height: "12%" };
+/** The icon size and the gap of the class legend, in pixels, as the oncoprint states them. */
+const LEGEND_ICON_PX = 10;
+const LEGEND_GAP_PX = 8;
+/** The margin of a box inside its lane, and of the backbone inside the band, in lanes. */
+const BOX_MARGIN = 0.1;
+const BACKBONE_MARGIN = 0.3;
+/** The opacity of a domain box. The box reads as a region of the backbone, and its label reads on it. */
+const BOX_OPACITY = 0.35;
+/** The lollipop module: the position, the count, the class, the label, and the domain track. */
+export const LOLLIPOP_FIGURE = { reads: new Set(["x", "y", "group", "label", "track"]), derive: deriveLollipop };
+function deriveLollipop(block, rows, context) {
+    const position = numericChannel(block, rows, context, "x");
+    if (position.isErr())
+        return err(position.error);
+    const count = numericChannel(block, rows, context, "y");
+    if (count.isErr())
+        return err(count.error);
+    const groupChannel = block.encoding?.group;
+    if (groupChannel !== undefined && (channelTransform(groupChannel) !== undefined || channelOrder(groupChannel) !== undefined)) {
+        return err(chartProblem(context.blockId, 'The lollipop reads the "group" column as the class of each row, thus the channel takes no transform and no "orderBy".'));
+    }
+    const group = groupChannel === undefined ? undefined : channelColumn(groupChannel);
+    const label = block.encoding?.label;
+    for (const column of [group, label]) {
+        if (column !== undefined && rows.length > 0 && !columnPresent(column, rows, context.columns)) {
+            return err(chartProblem(context.blockId, `The column "${column}" is absent from every row.`));
+        }
+    }
+    const stems = [];
+    for (const row of rows) {
+        const x = toNumber(row[position.value]);
+        const y = toNumber(row[count.value]);
+        // A row with no class falls in no stem series, thus it takes no label and no room on the axis either.
+        if (x !== null && y !== null && (group === undefined || classOf(row, group) !== undefined))
+            stems.push({ row, x, y });
+    }
+    const boxes = context.track === undefined ? ok(undefined) : domainBoxes(context.blockId, context.track);
+    if (boxes.isErr())
+        return err(boxes.error);
+    const length = axisLength(stems, context.track, boxes.value);
+    const classes = group === undefined ? [] : legendClasses(rows, group);
+    const colors = classColors(classes);
+    const stemTitle = valueAxisTitle(context.labels, count.value, COUNT_TITLE);
+    const series = group === undefined
+        ? [stemSeries(stemTitle, CHART_PALETTE[0], stems, label)]
+        : classes.map((name, index) => stemSeries(categoryName(name), colors[index], stems.filter((stem) => classOf(stem.row, group) === name), label));
+    if (label !== undefined)
+        series.push(labelSeries(stems, label));
+    const positionTitle = valueAxisTitle(context.labels, position.value, POSITION_TITLE);
+    const countAxis = { ...valueAxis("y", stemTitle, { min: 0 }), minInterval: 1 };
+    const legend = {
+        bottom: 0,
+        itemWidth: LEGEND_ICON_PX,
+        itemHeight: LEGEND_ICON_PX,
+        itemGap: LEGEND_GAP_PX,
+        data: series.filter((entry) => entry.renderItem === STEM_RENDERER).map((entry) => String(entry.name)),
+    };
+    if (boxes.value === undefined) {
+        return ok({ tooltip: { trigger: "item" }, xAxis: valueAxis("x", positionTitle, { min: 0, max: length }), yAxis: countAxis, series, legend });
+    }
+    const lanes = boxes.value.reduce((most, box) => Math.max(most, box.lane + 1), 1);
+    return ok({
+        tooltip: { trigger: "item" },
+        grid: [{ ...STEM_GRID }, { ...BAND_GRID }],
+        xAxis: [
+            { type: "value", min: 0, max: length, axisLabel: { show: false }, axisTick: { show: false } },
+            { ...valueAxis("x", positionTitle, { min: 0, max: length }), gridIndex: 1, axisLine: { show: false }, splitLine: { show: false } },
+        ],
+        yAxis: [countAxis, { type: "value", gridIndex: 1, min: 0, max: lanes, inverse: true, show: false }],
+        series: [...series, bandSeries(boxes.value, length, lanes)],
+        legend,
+    });
+}
+/** The column of one numeric channel. An absent channel, a transform, and a column that no row holds each refuse. */
+function numericChannel(block, rows, context, name) {
+    const channel = block.encoding?.[name];
+    if (channel === undefined) {
+        return err(chartProblem(context.blockId, `The lollipop figure needs a column for the "${name}" channel.`));
+    }
+    if (channelTransform(channel) !== undefined || channelOrder(channel) !== undefined) {
+        return err(chartProblem(context.blockId, `The lollipop reads the "${name}" column as it stands, thus the channel takes no transform and no "orderBy".`));
+    }
+    const column = channelColumn(channel);
+    if (rows.length > 0 && !columnPresent(column, rows, context.columns)) {
+        return err(chartProblem(context.blockId, `The column "${column}" is absent from every row.`));
+    }
+    return ok(column);
+}
+/**
+ * The boxes of the track in the order of its rows, each one in the first lane where it overlaps no earlier box.
+ * A row whose start or end is not numeric draws no box, and a row whose end precedes its start refuses.
+ */
+function domainBoxes(blockId, track) {
+    for (const column of [track.start, track.end, track.label]) {
+        if (track.rows.length > 0 && !columnPresent(column, track.rows, track.columns)) {
+            return err(chartProblem(blockId, `The track table holds no "${column}" column.`));
+        }
+    }
+    const laneOf = firstFreeLanes(track.rows.length);
+    const boxes = [];
+    for (const [index, row] of track.rows.entries()) {
+        const start = toNumber(row[track.start]);
+        const end = toNumber(row[track.end]);
+        if (start === null || end === null)
+            continue;
+        if (end < start) {
+            return err(chartProblem(blockId, `The track row ${index + 1} ends at ${end}, before its start at ${start}. A domain ends at or after its start.`));
+        }
+        boxes.push({ start, end, name: String(row[track.label] ?? ""), lane: laneOf(start, end) });
+    }
+    return ok(boxes);
+}
+/**
+ * The end of the x axis: the largest of the length column of the first track row that holds a number, the
+ * largest end of a box, and the largest position of a stem. A mutation table and a domain table of two isoforms
+ * disagree on the length, and each stem and each box stays inside the plot.
+ */
+function axisLength(stems, track, boxes) {
+    let largest = 0;
+    const lengthColumn = track?.length;
+    if (track !== undefined && lengthColumn !== undefined) {
+        for (const row of track.rows) {
+            const length = toNumber(row[lengthColumn]);
+            if (length === null)
+                continue;
+            largest = length;
+            break;
+        }
+    }
+    for (const stem of stems)
+        largest = Math.max(largest, stem.x);
+    for (const box of boxes ?? [])
+        largest = Math.max(largest, box.end);
+    return largest;
+}
+/** The stems in order of their count, the largest first, thus a smaller head draws over the stem of a larger one. */
+function byCount(stems) {
+    return stems
+        .map((stem, place) => ({ stem, place }))
+        .sort((a, b) => b.stem.y - a.stem.y || a.place - b.place)
+        .map((entry) => entry.stem);
+}
+/** One series of stems through the stem renderer, in one color. Each item names its row by the label column. */
+function stemSeries(name, color, stems, label) {
+    return {
+        type: "custom",
+        name,
+        renderItem: STEM_RENDERER,
+        encode: { x: 0, y: 1 },
+        itemStyle: { color },
+        tooltip: { formatter: "{a}<br/>{b}" },
+        data: byCount(stems).map((stem) => ({ name: label === undefined ? "" : String(stem.row[label] ?? ""), value: [stem.x, stem.y] })),
+    };
+}
+/** The labels of the three largest counts: one point with no symbol at each head, and its text above it. */
+function labelSeries(stems, label) {
+    return {
+        type: "scatter",
+        silent: true,
+        symbolSize: 0,
+        z: 10,
+        label: { show: true, formatter: "{b}", position: "top", distance: 6, color: CHART_INK },
+        labelLayout: { hideOverlap: true },
+        data: byCount(stems)
+            .slice(0, LABELED_COUNT)
+            .map((stem) => ({ name: String(stem.row[label] ?? ""), value: [stem.x, stem.y] })),
+    };
+}
+/**
+ * The band of the track: one gray backbone over the whole protein, then one box for each domain in its lane.
+ * The boxes of one name share one color. Each label takes the share of the axis that its box spans.
+ */
+function bandSeries(boxes, length, lanes) {
+    const names = firstAppearance(boxes.map((box) => box.name));
+    const palette = categoricalPalette(names.length);
+    const colorOf = new Map(names.map((name, place) => [name, palette[place % palette.length]]));
+    const areas = [
+        [
+            { xAxis: 0, yAxis: BACKBONE_MARGIN, itemStyle: { color: GUIDE_LINE_COLOR, opacity: BOX_OPACITY }, label: { show: false } },
+            { xAxis: length, yAxis: lanes - BACKBONE_MARGIN },
+        ],
+    ];
+    for (const box of boxes) {
+        const text = boxLabel(box, length);
+        areas.push([
+            {
+                name: box.name,
+                xAxis: box.start,
+                yAxis: box.lane + BOX_MARGIN,
+                itemStyle: { color: colorOf.get(box.name), opacity: BOX_OPACITY, borderColor: colorOf.get(box.name), borderWidth: 1 },
+                label: text === undefined ? { show: false } : { show: true, position: "inside", formatter: text, color: CHART_INK },
+            },
+            { xAxis: box.end, yAxis: box.lane + 1 - BOX_MARGIN },
+        ]);
+    }
+    return {
+        type: "line",
+        xAxisIndex: 1,
+        yAxisIndex: 1,
+        silent: true,
+        data: [],
+        markArea: { silent: false, tooltip: { formatter: "{b}" }, data: areas },
+    };
+}
+/** The label of one box: the whole name where it fits the box, a shortened name where some of it fits, else none. */
+function boxLabel(box, length) {
+    const room = length > 0 ? Math.round(((box.end - box.start) / length) * LABEL_CHARS_ACROSS) : 0;
+    if (box.name.length <= room)
+        return box.name;
+    if (room < LABEL_MIN_CHARS)
+        return undefined;
+    return `${box.name.slice(0, room - 1).trimEnd()}…`;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * The MA figure, as the `plotMA` of DESeq2 draws it: the mean of the normalized counts on a log axis, the
+ * log fold change on y, and the significant genes in blue over the gray genes that state no finding.
+ *
+ * - The x axis is logarithmic, and it ends at the decades around the positive means. A row whose mean is not
+ *   positive has no place on it, and it draws no point.
+ * - The `p` column splits the rows at the significance cut: the declared thresholds, or the DESeq2 default
+ *   of 0.1. A row with no p draws gray, as `plotMA` draws it. The significant points take the blue of the
+ *   palette, which is the default of DESeq2, and the gray points draw under them.
+ * - A line sits at zero, and the y axis is symmetric around zero.
+ *
+ * The points come from the composition machinery, thus a table of many thousand genes reads the shared
+ * payload. The rule of the split rides the payload as plain data, thus the page splits the rows as the server
+ * does.
+ */
+import type { FigureModule } from "./index.js";
+/** The significance cut of an MA plot where the block declares none: the `alpha` default of DESeq2. */
+export declare const MA_P_THRESHOLD = 0.1;
+/** The MA figure module. */
+export declare const MA_FIGURE: FigureModule;

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

@@ -0,0 +1,114 @@
+/**
+ * The MA figure, as the `plotMA` of DESeq2 draws it: the mean of the normalized counts on a log axis, the
+ * log fold change on y, and the significant genes in blue over the gray genes that state no finding.
+ *
+ * - The x axis is logarithmic, and it ends at the decades around the positive means. A row whose mean is not
+ *   positive has no place on it, and it draws no point.
+ * - The `p` column splits the rows at the significance cut: the declared thresholds, or the DESeq2 default
+ *   of 0.1. A row with no p draws gray, as `plotMA` draws it. The significant points take the blue of the
+ *   palette, which is the default of DESeq2, and the gray points draw under them.
+ * - A line sits at zero, and the y axis is symmetric around zero.
+ *
+ * The points come from the composition machinery, thus a table of many thousand genes reads the shared
+ * payload. The rule of the split rides the payload as plain data, thus the page splits the rows as the server
+ * does.
+ */
+import { err, ok } from "neverthrow";
+import { channelTransform } from "../../contracts/report-blocks.js";
+import { MA_BASELINE } from "../chart-presets.js";
+import { CHART_PALETTE, MUTED_CHART_COLOR } from "../design.js";
+import { formatNumberCell } from "../number-format.js";
+import { chartProblem, plainColumn, toNumber, valueAxisTitle } from "./common.js";
+import { axisOf, DENSE_NULL_OPACITY, DENSE_NULL_SYMBOL_PX, DENSE_NULL_Z, DENSE_SIGNAL_OPACITY, DENSE_SIGNAL_SYMBOL_PX, demandedChannel, largest, niceCeiling, plottedValues, pointLayer, seriesOf, smallest, symmetricRange, } from "./dense.js";
+/** The significance cut of an MA plot where the block declares none: the `alpha` default of DESeq2. */
+export const MA_P_THRESHOLD = 0.1;
+/** The name of the gray category. The muted rule of the renderer reads the same text. */
+const MA_NULL = "Not significant";
+/** The members of an MA block that the figure reads. */
+const READS = new Set(["x", "y", "p", "label"]);
+/**
+ * The two-way split of an MA plot, one row at a time: under the cut of the p column, or not.
+ *
+ * The significant name states the column and the cut, thus the legend states the rule of the colors. A row
+ * whose mean is not positive belongs to no category, because the log axis has no place for it.
+ */
+function maClassification(rows, pColumn, pTitle, cut) {
+    const significant = `${pTitle} < ${formatNumberCell(cut, "compact-scientific").text}`;
+    return {
+        categories: [
+            { name: significant, muted: false },
+            { name: MA_NULL, muted: true },
+        ],
+        rule: { kind: "ma", column: pColumn, cut },
+        categoryOf: (x, y, index) => {
+            if (x === null || y === null || x <= 0)
+                return undefined;
+            const p = toNumber(rows[index][pColumn]);
+            return p !== null && p < cut ? significant : MA_NULL;
+        },
+    };
+}
+/** The decade at or under a positive value, and the decade at or over it. */
+function decadeFloor(value) {
+    return Math.pow(10, Math.floor(Math.log10(value)));
+}
+function decadeCeiling(value) {
+    return Math.pow(10, Math.ceil(Math.log10(value)));
+}
+function deriveMa(block, rows, context) {
+    const encoding = block.encoding ?? {};
+    if (block.thresholds?.effect !== undefined) {
+        // The figure splits its rows by the p column alone, thus an effect cut would move nothing.
+        return err(chartProblem(context.blockId, "The ma chart reads the significance cut alone. Omit the effect cut."));
+    }
+    const x = demandedChannel(context.blockId, "ma", encoding, "x");
+    if (x.isErr())
+        return err(x.error);
+    if (channelTransform(x.value) !== undefined) {
+        return err(chartProblem(context.blockId, 'The ma figure draws the "x" channel on a log axis, thus it takes no transform.'));
+    }
+    const y = demandedChannel(context.blockId, "ma", encoding, "y");
+    if (y.isErr())
+        return err(y.error);
+    const pColumn = plainColumn("ma", encoding, "p", { blockId: context.blockId, rows, columns: context.columns });
+    if (pColumn.isErr())
+        return err(pColumn.error);
+    const composition = {
+        series: [{ form: "scatter", encoding: { x: x.value, y: y.value, ...(encoding.label !== undefined ? { label: encoding.label } : {}) } }],
+        annotations: [{ kind: "reference-line", axis: "y", value: MA_BASELINE }],
+        axes: { x: { scale: "log" } },
+    };
+    const cut = block.thresholds?.significance ?? MA_P_THRESHOLD;
+    const classification = pColumn.value === undefined ? undefined : maClassification(rows, pColumn.value, valueAxisTitle(context.labels, pColumn.value), cut);
+    const composed = context.compose(composition, classification !== undefined ? { classification } : {});
+    if (composed.isErr())
+        return err(composed.error);
+    const xs = plottedValues(rows, x.value);
+    const ys = plottedValues(rows, y.value);
+    const means = [];
+    const effects = [];
+    for (let index = 0; index < rows.length; index += 1) {
+        const mean = xs[index];
+        const effect = ys[index];
+        if (mean === null || effect === null || mean <= 0)
+            continue;
+        means.push(mean);
+        effects.push(Math.abs(effect));
+    }
+    const low = smallest(means);
+    const high = largest(means);
+    const reach = niceCeiling(largest(effects) ?? 0);
+    const option = composed.value;
+    return ok({
+        ...option,
+        xAxis: { ...axisOf(option, "xAxis"), ...(low !== undefined && high !== undefined ? { min: decadeFloor(low), max: decadeCeiling(high) } : {}) },
+        yAxis: { ...axisOf(option, "yAxis"), ...symmetricRange(reach) },
+        series: classification === undefined
+            ? seriesOf(option).map((series) => ({ ...series, symbolSize: DENSE_SIGNAL_SYMBOL_PX }))
+            : seriesOf(option).map((series, place) => place === 0
+                ? { ...series, ...pointLayer(CHART_PALETTE[0], DENSE_SIGNAL_SYMBOL_PX, DENSE_SIGNAL_OPACITY) }
+                : { ...series, ...pointLayer(MUTED_CHART_COLOR, DENSE_NULL_SYMBOL_PX, DENSE_NULL_OPACITY, DENSE_NULL_Z) }),
+    });
+}
+/** The MA figure module. */
+export const MA_FIGURE = { reads: READS, derive: deriveMa };

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

@@ -0,0 +1,60 @@
+/**
+ * The Manhattan figure, as qqman and the GWAS papers draw it: the cumulative genome position on x, the
+ * transformed p on y, and one block of points for each chromosome.
+ *
+ * - The chromosomes alternate between two colors, thus each boundary reads without a tick.
+ * - Each chromosome name sits under the middle of its points, and the position ticks hide.
+ * - Two guide lines mark the genome-wide significance at 5e-8 and the suggestive level at 1e-5. The
+ *   genome-wide line carries its label.
+ * - The lead variant of each chromosome that passes the genome-wide line is the row with the smallest p of
+ *   that chromosome, as the `annotateTop` rule of qqman gives it. The ten most significant lead variants
+ *   show their names over their peaks, clear of each other and of the points, with a leader line to each
+ *   peak. The label of the genome-wide line sits over the line, clear of them.
+ * - A chromosome name prints where it keeps a gap from the name before it, thus the small chromosomes never
+ *   print two names on top of each other.
+ * - The lead names and the chromosome names place again for the plot and the text size of each export. A render
+ *   tries the most significant lead names whose summed text width fits the plot width, and a name that finds no
+ *   place clear of the earlier names does not print. Thus a narrow export prints fewer names.
+ * - The chromosomes read in genome order whatever the order of the rows: the numbered ones, then X, Y, and MT,
+ *   then each other name. The colors, the names, and the leads read that order.
+ * - A variant whose stored p is 0 draws an upward triangle at the top of the plotted range, and it leads its
+ *   chromosome.
+ * - While a zoom of the page toolbox narrows the x axis, the axis shows each position as `chrN: P Mb`, and the
+ *   chromosome names hide.
+ *
+ * The `group` channel names the chromosome, and the figure needs it. The points come from the composition
+ * machinery, thus a table of many thousand variants reads the shared payload. The lines ride the point series
+ * as mark members, and the chromosome names and the lead names ride one series each after them. Thus the page
+ * draws each of them over the payload points.
+ */
+import type { Cell } from "../chart.js";
+import type { FigureModule } from "./index.js";
+import { type Box, type NameFrame } from "./label-room.js";
+/** The two colors that alternate between the chromosomes: the blue of the palette and the muted gray. */
+export declare const MANHATTAN_COLORS: readonly ["#0072b2", "#94a3b8"];
+/** The suggestive level of a GWAS, the second guide line of qqman. */
+export declare const MANHATTAN_SUGGESTIVE_P = 0.00001;
+/** The largest count of lead variants that show their name, over the whole genome. */
+export declare const MANHATTAN_LABEL_COUNT = 10;
+/**
+ * The smallest gap between two chromosome names that both print, as a share of the text size.
+ *
+ * The small chromosomes lie close together. The name of a chromosome whose text comes nearer than this gap to
+ * the text of the last printed name, in the plot of a render, does not print in that render.
+ */
+export declare const MANHATTAN_NAME_GAP_SHARE = 0.5;
+/**
+ * The box in data units that the label of the genome-wide line takes at the right end of the line, over it, in
+ * the plot of one render.
+ */
+export declare function guideLabelBox(line: number, x: {
+    readonly min: number;
+    readonly max: number;
+}, top: number, text: string, frame: NameFrame): Box;
+/**
+ * The genome order of two chromosome names: the numbered chromosomes in numeric order, then X, Y, and MT, then
+ * each other name in text order. A `chr` prefix takes no part in the order.
+ */
+export declare function compareChromosomes(a: Cell, b: Cell): number;
+/** The Manhattan figure module. */
+export declare const MANHATTAN_FIGURE: FigureModule;