@inflexa-ai/harness 0.42.1 → 0.43.0

package/dist/report-render/chart-presets.d.ts

@@ -1,25 +1,18 @@
 /**
- * The preset expansion of the chart grammar.
+ * The constants, the classification, and the volcano expansion that the dense figure modules read.
  *
- * A preset is sugar over the composition. `expandPreset` gives the composition of one preset, thus the
- * derivation reads one shape and the two paths cannot drift.
+ * Each default of a figure is a declared constant of this module, and a declared threshold pair replaces
+ * one. A guide line carries such a value, and a guide is never a plotted value.
  *
- * Each default of a preset is a declared constant of this module, and a declared threshold pair replaces
- * one. A guide line carries such a value, and a guide is never a plotted value. The expansion estimates
- * nothing: the `km` preset plots the precomputed survival columns as they are, and it fits no curve.
+ * A figure can carry a classification. The classification reads the plotted pair of one row against the
+ * same values that the guides carry, thus the color split lands on the drawn lines. It reads one row at a
+ * time, and it computes no aggregate. The page builds the series of a dense figure from the rule of the
+ * classification, thus the rule is plain data.
  *
- * A preset can also carry a classification. The classification reads the plotted pair of one row against
- * the same values that the guides carry, thus the color split lands on the drawn lines. It reads one row
- * at a time, and it computes no aggregate.
- *
- * A preset declares its own transform on the channel that it transforms. Thus it reads the column of that
- * channel and it drops an authored transform there, and no value takes the transform two times.
+ * The volcano declares its own transform on the p channel. Thus it reads the column of that channel and it
+ * drops an authored transform there, and no value takes the transform two times.
  */
-import { type ChartChannel, type ChartComposition, type ChartEncoding, type ChartThresholds, type ChartType } from "../contracts/report-blocks.js";
-/** The four chart types that expand into a composition. */
-export declare const PRESET_CHART_TYPES: readonly ["volcano", "manhattan", "ma", "km"];
-/** One chart type that expands into a composition. */
-export type PresetChartType = (typeof PRESET_CHART_TYPES)[number];
+import { type ChartChannel, type ChartComposition, type ChartEncoding, type ChartThresholds } from "../contracts/report-blocks.js";
 /** The default p-value threshold of a volcano. The guide line sits at the transformed value of it. */
 export declare const VOLCANO_P_THRESHOLD = 0.05;
 /** The default effect threshold of a volcano. One guide line sits at each side of zero. */
@@ -45,58 +38,64 @@ export interface PresetCategory {
  * series in the browser, and this shape is what such a build takes. The two forms answer alike, and the
  * shared test vector holds them together.
  *
- * `cut` sits on the plotted y value, which is the transformed p-value, and `effect` sits on the plotted x
- * value. The volcano rule gives the place of the category in `categories`: 0 for the down side, 1 for the
- * up side, and 2 for the null category.
+ * The volcano rule reads the plotted pair. `cut` sits on the plotted y value, which is the transformed
+ * p-value, and `effect` sits on the plotted x value. It gives the place of the category in `categories`: 0
+ * for the down side, 1 for the up side, and 2 for the null category.
+ *
+ * The MA rule reads a third column, the p-value `column`, against `cut` on its untransformed scale. It gives
+ * 0 for a row under the cut and 1 for every other row, a row with no p included. The x axis of an MA is
+ * logarithmic, thus a row whose x is not positive belongs to no category.
  */
-export interface PresetRule {
+export type PresetRule = {
     readonly kind: "volcano";
     readonly cut: number;
     readonly effect: number;
-}
+} | {
+    readonly kind: "ma";
+    readonly column: string;
+    readonly cut: number;
+};
 /**
  * The per-row classification of one preset.
  *
- * `categoryOf` reads the plotted pair of one row and nothing else. Thus it computes no aggregate, and it
- * compares each point against the same numbers that the guide lines carry. The color split then lands on
- * the drawn lines. A row that gives no pair belongs to no category, and its point drops.
+ * `categoryOf` reads the plotted pair of one row, and the row index where the rule reads a third column of
+ * that row. Thus it computes no aggregate, and it compares each point against the same numbers that the
+ * guide lines carry. The color split then lands on the drawn lines. A row that gives no pair belongs to no
+ * category, and its point drops.
  */
 export interface PresetClassification {
     readonly categories: readonly PresetCategory[];
-    readonly categoryOf: (x: number | null, y: number | null) => string | undefined;
+    readonly categoryOf: (x: number | null, y: number | null, index: number) => string | undefined;
     readonly rule: PresetRule;
 }
-/** The expansion of one preset: the composition, and the classification where the preset draws one. */
+/** The expansion of the volcano: the composition of its points and its guides, and its classification. */
 export interface PresetExpansion {
     readonly composition: ChartComposition;
-    readonly classification?: PresetClassification;
+    readonly classification: PresetClassification;
 }
-/** True when the chart type expands into a composition. */
-export declare function isPresetChartType(chartType: ChartType): chartType is PresetChartType;
 /**
- * Expand one preset into a composition.
+ * The composition of a volcano: the effect on x, the transformed p-value on y, three guide lines, and the
+ * three-way classification.
  *
- * `x` and `y` are the two channels that every preset demands. The caller resolves them from the encoding
- * and refuses an absent one, thus this function is total and it needs no failure channel. `encoding`
- * supplies the optional `group` and `label` channels.
+ * `x` and `y` are the two channels that the volcano demands, and the caller refuses an absent one. `encoding`
+ * supplies the optional `label` channel. `thresholds` carries the pair that the author declared, and an absent
+ * pair gives the two constants of this module.
  *
- * `thresholds` carries the pair that the author declared. The volcano is the one preset that reads it, and
- * an absent pair gives the two constants of this module.
+ * The two effect guides sit at each side of zero, and the p guide sits at the transformed significance. The
+ * expression of the guide is the expression of the `neg_log10` transform, thus the guide and the points
+ * share one scale. The classification reads the same two numbers, thus the color split lands on the lines.
+ * The label of the p guide prints the cut as a p-value column prints it, with the power of ten of a figure.
  */
-export declare function expandPreset(preset: PresetChartType, x: ChartChannel, y: ChartChannel, encoding: ChartEncoding, thresholds?: ChartThresholds): PresetExpansion;
+export declare function expandVolcano(x: ChartChannel, y: ChartChannel, encoding: ChartEncoding, thresholds: ChartThresholds | undefined): PresetExpansion;
 /**
- * The semantic axis titles that one preset states.
- *
- * A preset knows its own quantities, thus it names them in words. A volcano plots a log2 effect against the
- * transformed p, and a manhattan plots a genome position against the same transformed p. The `ma` and the
- * `km` presets name nothing, because neither axis of them carries a fixed quantity.
+ * The semantic axis titles of a volcano. It plots a log2 effect against the transformed p, thus it names them
+ * in words.
  *
- * A channel that carries an authored transform plots a derived quantity, thus the semantic title would
- * state the wrong one. Such a channel takes no title, and the derived name of the renderer states the true
- * quantity. The y channel of a volcano and of a manhattan takes the transform of the preset itself, thus
- * its title is exact.
+ * A channel that carries an authored transform plots a derived quantity, thus the semantic title would state
+ * the wrong one. Such a channel takes no title, and the derived name of the renderer states the true quantity.
+ * The y channel takes the transform of the volcano itself, thus its title is exact.
  *
  * The titles rank under a declared column label. Thus they ride beside the composition and never inside its
  * `axes` field, where an agent title sits and where they would outrank the label.
  */
-export declare function presetAxisTitles(preset: PresetChartType, x: ChartChannel): PresetAxisTitles;
+export declare function volcanoAxisTitles(x: ChartChannel): PresetAxisTitles;

package/dist/report-render/chart-presets.js

@@ -1,23 +1,19 @@
 /**
- * The preset expansion of the chart grammar.
+ * The constants, the classification, and the volcano expansion that the dense figure modules read.
  *
- * A preset is sugar over the composition. `expandPreset` gives the composition of one preset, thus the
- * derivation reads one shape and the two paths cannot drift.
+ * Each default of a figure is a declared constant of this module, and a declared threshold pair replaces
+ * one. A guide line carries such a value, and a guide is never a plotted value.
  *
- * Each default of a preset is a declared constant of this module, and a declared threshold pair replaces
- * one. A guide line carries such a value, and a guide is never a plotted value. The expansion estimates
- * nothing: the `km` preset plots the precomputed survival columns as they are, and it fits no curve.
+ * A figure can carry a classification. The classification reads the plotted pair of one row against the
+ * same values that the guides carry, thus the color split lands on the drawn lines. It reads one row at a
+ * time, and it computes no aggregate. The page builds the series of a dense figure from the rule of the
+ * classification, thus the rule is plain data.
  *
- * A preset can also carry a classification. The classification reads the plotted pair of one row against
- * the same values that the guides carry, thus the color split lands on the drawn lines. It reads one row
- * at a time, and it computes no aggregate.
- *
- * A preset declares its own transform on the channel that it transforms. Thus it reads the column of that
- * channel and it drops an authored transform there, and no value takes the transform two times.
+ * The volcano declares its own transform on the p channel. Thus it reads the column of that channel and it
+ * drops an authored transform there, and no value takes the transform two times.
  */
 import { channelColumn, channelTransform, } from "../contracts/report-blocks.js";
-/** The four chart types that expand into a composition. */
-export const PRESET_CHART_TYPES = ["volcano", "manhattan", "ma", "km"];
+import { formatTableCell, typographicExponent } from "./number-format.js";
 /** The default p-value threshold of a volcano. The guide line sits at the transformed value of it. */
 export const VOLCANO_P_THRESHOLD = 0.05;
 /** The default effect threshold of a volcano. One guide line sits at each side of zero. */
@@ -42,41 +38,20 @@ const NEG_LOG10_P_TITLE = "−log10(p)";
 const VOLCANO_DOWN = "Down";
 const VOLCANO_UP = "Up";
 const VOLCANO_NULL = "Not significant";
-/** True when the chart type expands into a composition. */
-export function isPresetChartType(chartType) {
-    // The array holds the four preset members, thus the test never reads a base type as a preset.
-    return PRESET_CHART_TYPES.includes(chartType);
-}
 /**
- * Expand one preset into a composition.
+ * The composition of a volcano: the effect on x, the transformed p-value on y, three guide lines, and the
+ * three-way classification.
  *
- * `x` and `y` are the two channels that every preset demands. The caller resolves them from the encoding
- * and refuses an absent one, thus this function is total and it needs no failure channel. `encoding`
- * supplies the optional `group` and `label` channels.
- *
- * `thresholds` carries the pair that the author declared. The volcano is the one preset that reads it, and
- * an absent pair gives the two constants of this module.
- */
-export function expandPreset(preset, x, y, encoding, thresholds) {
-    switch (preset) {
-        case "volcano":
-            return volcano(x, y, encoding, thresholds);
-        case "manhattan":
-            return manhattan(x, y, encoding);
-        case "ma":
-            return ma(x, y, encoding);
-        case "km":
-            return km(x, y, encoding);
-    }
-}
-/**
- * The effect on x, the transformed p-value on y, three guide lines, and the three-way classification.
+ * `x` and `y` are the two channels that the volcano demands, and the caller refuses an absent one. `encoding`
+ * supplies the optional `label` channel. `thresholds` carries the pair that the author declared, and an absent
+ * pair gives the two constants of this module.
  *
  * The two effect guides sit at each side of zero, and the p guide sits at the transformed significance. The
  * expression of the guide is the expression of the `neg_log10` transform, thus the guide and the points
  * share one scale. The classification reads the same two numbers, thus the color split lands on the lines.
+ * The label of the p guide prints the cut as a p-value column prints it, with the power of ten of a figure.
  */
-function volcano(x, y, encoding, thresholds) {
+export function expandVolcano(x, y, encoding, thresholds) {
     const pColumn = channelColumn(y);
     const significance = thresholds?.significance ?? VOLCANO_P_THRESHOLD;
     const effect = thresholds?.effect ?? VOLCANO_EFFECT_THRESHOLD;
@@ -89,7 +64,12 @@ function volcano(x, y, encoding, thresholds) {
                 },
             ],
             annotations: [
-                { kind: "reference-line", axis: "y", value: -Math.log10(significance), label: `p ${significance}` },
+                {
+                    kind: "reference-line",
+                    axis: "y",
+                    value: -Math.log10(significance),
+                    label: `p ${typographicExponent(formatTableCell(significance, "scientific"))}`,
+                },
                 { kind: "reference-line", axis: "x", value: -effect },
                 { kind: "reference-line", axis: "x", value: effect },
             ],
@@ -132,71 +112,21 @@ function volcanoClassification(significance, effect) {
         },
     };
 }
-/** The genome position on x, the transformed p-value on y, and the genome-wide guide line. */
-function manhattan(x, y, encoding) {
-    const pColumn = channelColumn(y);
-    return {
-        composition: {
-            series: [
-                {
-                    form: "scatter",
-                    encoding: { x, y: { column: pColumn, transform: "neg_log10" }, ...optionalChannels(encoding) },
-                },
-            ],
-            annotations: [{ kind: "reference-line", axis: "y", value: -Math.log10(MANHATTAN_P_THRESHOLD), label: `p ${MANHATTAN_P_THRESHOLD}` }],
-        },
-    };
-}
-/** The mean level on x, the effect on y, and the baseline guide line. */
-function ma(x, y, encoding) {
-    return {
-        composition: {
-            series: [{ form: "scatter", encoding: { x, y, ...optionalChannels(encoding) } }],
-            annotations: [{ kind: "reference-line", axis: "y", value: MA_BASELINE }],
-        },
-    };
-}
 /**
- * The time on x and the precomputed survival on y, as one step series for each arm.
- *
- * A survival curve holds its value between two events, thus the step form is the honest one. The quick
- * path carries two channels for the two axes and no channel for a confidence bound. Thus a band around a
- * curve is a composition, where an `area` series names the upper bound on `y` and the lower bound on `y0`.
- */
-function km(x, y, encoding) {
-    return {
-        composition: {
-            series: [{ form: "step", encoding: { x, y, ...optionalChannels(encoding) } }],
-        },
-    };
-}
-/**
- * The semantic axis titles that one preset states.
- *
- * A preset knows its own quantities, thus it names them in words. A volcano plots a log2 effect against the
- * transformed p, and a manhattan plots a genome position against the same transformed p. The `ma` and the
- * `km` presets name nothing, because neither axis of them carries a fixed quantity.
+ * The semantic axis titles of a volcano. It plots a log2 effect against the transformed p, thus it names them
+ * in words.
  *
- * A channel that carries an authored transform plots a derived quantity, thus the semantic title would
- * state the wrong one. Such a channel takes no title, and the derived name of the renderer states the true
- * quantity. The y channel of a volcano and of a manhattan takes the transform of the preset itself, thus
- * its title is exact.
+ * A channel that carries an authored transform plots a derived quantity, thus the semantic title would state
+ * the wrong one. Such a channel takes no title, and the derived name of the renderer states the true quantity.
+ * The y channel takes the transform of the volcano itself, thus its title is exact.
  *
  * The titles rank under a declared column label. Thus they ride beside the composition and never inside its
  * `axes` field, where an agent title sits and where they would outrank the label.
  */
-export function presetAxisTitles(preset, x) {
-    switch (preset) {
-        case "volcano":
-            return { ...(channelTransform(x) === undefined ? { x: LOG2_EFFECT_TITLE } : {}), y: NEG_LOG10_P_TITLE };
-        case "manhattan":
-            return { y: NEG_LOG10_P_TITLE };
-        case "ma":
-        case "km":
-            return {};
-    }
+export function volcanoAxisTitles(x) {
+    return { ...(channelTransform(x) === undefined ? { x: LOG2_EFFECT_TITLE } : {}), y: NEG_LOG10_P_TITLE };
 }
-/** The two optional channels that every preset carries through from the quick-path encoding. */
+/** The two optional channels that the volcano carries through from the quick-path encoding. */
 function optionalChannels(encoding) {
     return {
         ...(encoding.group !== undefined ? { group: encoding.group } : {}),

package/dist/report-render/chart-renderers.d.ts

@@ -0,0 +1,163 @@
+/**
+ * The named renderers of a custom series, in two twins.
+ *
+ * The chart runtime draws an interval, a violin outline, an oncoprint cell, and a lollipop stem through a
+ * `custom` series. The option rides to the page as inline JSON, thus it holds no function. The derivation
+ * writes the name of a renderer as the `renderItem` string, and the chart runtime finds the function under
+ * that name in its own registry. Each consumer registers each renderer with `registerCustomSeries` before it
+ * draws: the page bootstrap through the source text below, and the server export through the TypeScript
+ * functions. A series that needs parameters beyond its items carries them as JSON in `itemPayload`, and the
+ * renderer reads them from its first argument.
+ *
+ * The two twins hold one rule each. A shared test vector runs both over one set of items with a stub of the
+ * runtime, and it compares the elements that they give. Thus the two cannot drift in silence.
+ *
+ * A category axis rounds a data coordinate to its category, thus a renderer never adds a fraction of a
+ * category to a coordinate. It takes the band of one category in pixels from the runtime, and it shifts the
+ * pixel position by a fraction of that band.
+ *
+ * The export option lives here too, in the same two twins: the server draws the SVG through it, and the page
+ * draws each PNG through it.
+ */
+/** The renderer name of an interval: an error bar, a confidence interval, or the inner mark of a violin. */
+export declare const INTERVAL_RENDERER = "interval";
+/** The renderer name of a violin outline. */
+export declare const OUTLINE_RENDERER = "outline";
+/** The renderer name of one oncoprint cell: the gray ground and the glyph of its alteration class. */
+export declare const CELL_GLYPH_RENDERER = "cell-glyph";
+/** The renderer name of one lollipop mutation: a stem from zero and a head at its count. */
+export declare const STEM_RENDERER = "stem";
+/** The gap between two oncoprint cells, in pixels. */
+export declare const CELL_GAP_PX = 1;
+/** The share of the ground height that the glyph of a class covers. The gray ground shows above and below it. */
+export declare const CELL_GLYPH_SHARE = 0.6;
+/** The radius of the head of a lollipop stem, in pixels. */
+export declare const STEM_HEAD_RADIUS_PX = 3.5;
+/** The count of grid points of one violin outline. Each item of an outline holds one pair for each point. */
+export declare const VIOLIN_GRID_POINTS = 64;
+/** The half length of the cap at each bound of an error bar, in pixels. It is the half width of an arrow too. */
+export declare const INTERVAL_CAP_PX = 4;
+/** The length of the arrow at a clipped end of an interval, in pixels. */
+export declare const INTERVAL_ARROW_PX = 6;
+/** The first argument of a renderer: the JSON parameters that the series carries in `itemPayload`. */
+export interface RenderParams {
+    readonly itemPayload?: Readonly<Record<string, unknown>>;
+}
+/** The part of the chart runtime that a renderer reads. */
+export interface RenderApi {
+    value(dimension: number): number;
+    coord(point: number[]): number[];
+    size(delta: number[]): number[];
+    visual(name: "color"): string;
+}
+/** One graphic element that a renderer gives back to the chart runtime. */
+export interface RenderedElement {
+    type: string;
+    shape?: Record<string, unknown>;
+    style?: Record<string, unknown>;
+    children?: RenderedElement[];
+}
+/**
+ * Draw one interval.
+ *
+ * An item is `[x, y, low, high, axis, offset, mark, clipped]`. `axis` is `0` for an interval along x and `1`
+ * for one along y. `offset` is a fraction of one category band, and it moves the interval over its own bar in a
+ * grouped chart. `mark` is `0` for an error bar with two caps, and `1` for the inner mark of a violin: a
+ * thick quartile line and one point at the median, which is the anchor `y`. `clipped` is optional: its bit `1`
+ * marks a `low` that the axis clipped and its bit `2` a clipped `high`, and a clipped end draws an arrow in
+ * place of its cap, as `forestplot` draws it.
+ */
+export declare function intervalRenderer(_params: RenderParams, api: RenderApi): RenderedElement;
+/**
+ * Draw one violin outline.
+ *
+ * An item is `[c, yMin, yMax, offset, w1, y1, w2, y2, ...]` with one pair for each grid point. `c` is the
+ * category index, `yMin` and `yMax` are the extent of the grid, and `offset` is a fraction of one band that
+ * moves a grouped violin inside its band. Each pair is a half-width in band fractions and its grid value.
+ * The outline runs up the right side and down the left side, thus the polygon closes on itself.
+ */
+export declare function outlineRenderer(_params: RenderParams, api: RenderApi): RenderedElement;
+/**
+ * Draw one oncoprint cell.
+ *
+ * An item is `[x, y, class]`. `x` and `y` are the places of the sample and the gene on the two category axes,
+ * and `class` is the place of the alteration class in the `colors` list of the payload, or `-1` for a cell
+ * with no alteration. Each cell draws the `ground` color of the payload over its band less one gap. An altered
+ * cell adds one glyph in the color of its class: the width of the ground and a share of its height, centered.
+ */
+export declare function cellGlyphRenderer(params: RenderParams, api: RenderApi): RenderedElement;
+/**
+ * Draw one lollipop mutation.
+ *
+ * An item is `[x, y]`: the amino-acid position and the count. The stem is a thin gray line from the value `0`
+ * to the count, and the head is one circle at the count in the color of the series.
+ */
+export declare function stemRenderer(_params: RenderParams, api: RenderApi): RenderedElement;
+/** One renderer function: the parameters of its series and the part of the runtime that it reads. */
+export type ChartRenderer = (params: RenderParams, api: RenderApi) => RenderedElement;
+/**
+ * One registered renderer: the name that a derived series states, the TypeScript function that the export
+ * registers, and the name of the page twin in `CHART_RENDERERS_SOURCE` that the bootstrap registers.
+ */
+export interface ChartRendererEntry {
+    readonly name: string;
+    readonly render: ChartRenderer;
+    readonly pageFunction: string;
+}
+/**
+ * The registered renderers. A renderer joins by one entry here, beside its TypeScript function and its page
+ * twin, and each consumer registers it under the same name.
+ */
+export declare const CHART_RENDERERS: readonly ChartRendererEntry[];
+/** The part of the chart runtime that holds the registry of the named renderers. */
+export interface RendererRegistry {
+    registerCustomSeries(name: string, render: ChartRenderer): void;
+}
+/**
+ * Register each renderer with the chart runtime. A second registration of one name replaces the first with
+ * the same function, thus a caller registers before each draw and the runtime holds one function per name.
+ */
+export declare function registerChartRenderers(runtime: RendererRegistry): void;
+/**
+ * The member of an option that holds the series of each export width, for a figure whose text the derivation
+ * places itself.
+ *
+ * A name that the derivation places clears its neighbors at one plot size and one text size alone. Thus the
+ * figure places its names again for the plot of each export, and the export takes the series of its width in
+ * place of the page series of the same names. The member is no field of the chart runtime, and the runtime
+ * keeps an unknown member without a draw.
+ */
+export declare const SIZED_SERIES_MEMBER = "sizedSeries";
+/** The series of each export width: the names of the page series that they replace, and the series of each width. */
+export interface SizedSeries {
+    readonly names: readonly string[];
+    readonly widths: Readonly<Record<string, readonly unknown[]>>;
+}
+/** The height of one line of the chart text, as a share of the text size. An upright category label takes one line along its axis. */
+export declare const LABEL_LINE_SHARE = 1.3;
+/**
+ * The label interval of an axis of upright category labels at one width and one text size: the count of labels that
+ * the chart runtime skips after each label that it prints. The width holds one upright label for each line of text.
+ * An axis of more categories prints the first label of each run that the width gives, and an axis that fits skips none.
+ */
+export declare function categoryInterval(count: number, textPx: number, widthPx: number): number;
+/**
+ * The option of one export at one text size.
+ *
+ * An export is a still figure. Thus it carries no tooltip, no toolbox, and no animation. The theme of the
+ * export sets the text size, and the gap between an axis and its name, and the label of a facet panel, scale
+ * with the text. The copy leaves the input as it is, thus the page keeps its own option.
+ *
+ * A column export is short and narrow. Thus the grid of a chart with a bottom legend holds its labels and its
+ * names above a band of the legend height, and the panels of a facet end over the band of the legend lines
+ * that the export width gives. The category labels turn where they do not fit the width, and a color scale
+ * prints its ends as static text. A grid that contains its labels contains its names too.
+ */
+export declare function exportOption(option: Record<string, unknown>, textPx: number, widthPx: number, heightPx: number): Record<string, unknown>;
+/**
+ * The page twin of each renderer, of the bind step, and of the export option, as browser source text.
+ *
+ * Each function holds the rule of its TypeScript twin in the same order of operations. Thus the two give
+ * the same numbers for one item, and the shared test vector compares them exactly.
+ */
+export declare const CHART_RENDERERS_SOURCE: string;