@inflexa-ai/harness 0.20.0 → 0.21.1

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

@@ -0,0 +1,205 @@
+/**
+ * The preset expansion of the chart grammar.
+ *
+ * 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 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 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.
+ */
+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"];
+/** 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. */
+export const VOLCANO_EFFECT_THRESHOLD = 1;
+/** The genome-wide significance threshold of a Manhattan plot. */
+export const MANHATTAN_P_THRESHOLD = 5e-8;
+/** The baseline of an MA plot. A point above it rose, and a point below it fell. */
+export const MA_BASELINE = 0;
+/**
+ * The x title of a volcano. The two effect guides sit at `±1`, which is a log2 claim, thus the preset states
+ * the same quantity in words.
+ */
+const LOG2_EFFECT_TITLE = "log2 fold change";
+/** The y title of a preset that transforms its p column. The minus sign is the character, not a hyphen. */
+const NEG_LOG10_P_TITLE = "−log10(p)";
+/**
+ * The three category names of a volcano.
+ *
+ * The two signal names state the side of the effect axis. The null name reads as the standard legend of a
+ * volcano, and the muted rule of the renderer reads the same text.
+ */
+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.
+ *
+ * `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.
+ *
+ * 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.
+ */
+function volcano(x, y, encoding, thresholds) {
+    const pColumn = channelColumn(y);
+    const significance = thresholds?.significance ?? VOLCANO_P_THRESHOLD;
+    const effect = thresholds?.effect ?? VOLCANO_EFFECT_THRESHOLD;
+    return {
+        composition: {
+            series: [
+                {
+                    form: "scatter",
+                    encoding: { x, y: { column: pColumn, transform: "neg_log10" }, ...optionalChannels(encoding) },
+                },
+            ],
+            annotations: [
+                { kind: "reference-line", axis: "y", value: -Math.log10(significance), label: `p ${significance}` },
+                { kind: "reference-line", axis: "x", value: -effect },
+                { kind: "reference-line", axis: "x", value: effect },
+            ],
+        },
+        classification: volcanoClassification(significance, effect),
+    };
+}
+/**
+ * The three-way split of a volcano, one row at a time.
+ *
+ * The significance cut is the value of the y guide, thus the test compares the plotted y against the drawn
+ * line. The effect cuts are the two x guides, and the test compares the plotted x against them. A point on
+ * a guide takes the null category, thus a guide belongs to neither side of itself.
+ *
+ * The down category emits first. The palette of the theme opens with the down color and the up color of the
+ * design tokens, thus each side takes its conventional color from the palette order alone.
+ *
+ * The rule states the same two cuts as plain data. A chart that ships no row builds its series in the
+ * browser from the rule, thus the two splits read one pair of numbers.
+ */
+function volcanoClassification(significance, effect) {
+    const cut = -Math.log10(significance);
+    return {
+        categories: [
+            { name: VOLCANO_DOWN, muted: false },
+            { name: VOLCANO_UP, muted: false },
+            { name: VOLCANO_NULL, muted: true },
+        ],
+        rule: { kind: "volcano", cut, effect },
+        categoryOf: (plottedX, plottedY) => {
+            if (plottedX === null || plottedY === null)
+                return undefined;
+            if (plottedY <= cut)
+                return VOLCANO_NULL;
+            if (plottedX < -effect)
+                return VOLCANO_DOWN;
+            if (plottedX > effect)
+                return VOLCANO_UP;
+            return VOLCANO_NULL;
+        },
+    };
+}
+/** 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.
+ *
+ * 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.
+ *
+ * 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 {};
+    }
+}
+/** The two optional channels that every preset carries through from the quick-path encoding. */
+function optionalChannels(encoding) {
+    return {
+        ...(encoding.group !== undefined ? { group: encoding.group } : {}),
+        ...(encoding.label !== undefined ? { label: encoding.label } : {}),
+    };
+}

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

@@ -1,23 +1,33 @@
 /**
  * The chart derivation of the report page.
  *
- * A chart block binds one whole-table artifact and a channel mapping. `deriveChartOption` turns the
- * chart type, the encoding, and the resolved rows into one ECharts option object. The chart container
- * markup lives beside this file, and it wraps the option that this derivation gives.
+ * A chart block binds one whole-table artifact, and it carries the quick path or the composition.
+ * `deriveChartOption` turns that grammar and the resolved rows into one ECharts option object. The chart
+ * container markup lives beside this file, and it wraps the option that this derivation gives.
+ *
+ * The derivation reads one shape. A preset expands into a composition before the derivation
+ * (`chart-presets.ts`), and each base chart type keeps its own fixed rule. Thus the two paths cannot
+ * drift.
  *
  * The renderer computes no aggregate. Each plotted number stays traceable to one cell of the evidence
- * artifact. A pie or a heatmap arrives one row per category or per cell, thus a repeated category or a
- * repeated pair is a refusal and not a silent sum.
+ * artifact, or to a per-row transform of one cell. A pie or a heatmap arrives one row per category or per
+ * cell, thus a repeated category or a repeated pair is a refusal and not a silent sum.
  *
  * The derivation is deterministic. Every object builds in one fixed key order, and the code reads no
  * clock, no random value, and no locale. A string comparison uses the code-unit order (`<`) and never
  * `localeCompare`, thus the same rows give the same bytes on every host.
+ *
+ * The option rides to the page as inline JSON. Thus no axis label and no tooltip can carry a function
+ * formatter, and every formatter here is a static template of the chart runtime. As a result the
+ * derivation bounds the tick precision of the one axis whose unit it declares itself, and every other
+ * value axis keeps the tick values that ECharts computes.
  */
 import { type Result } from "neverthrow";
-import type { ChartBlock } from "../contracts/report-blocks.js";
+import { type ChartBlock, type ChartTransform } from "../contracts/report-blocks.js";
+import { type PresetRule } from "./chart-presets.js";
 import type { RenderProblem } from "./types.js";
 /** One cell of a resolved row. A cell is one string or one number. */
-type Cell = string | number;
+export type Cell = string | number;
 /** One resolved row of the bound table, keyed by column name. */
 export type ChartRow = Record<string, Cell>;
 /** The derived option object, ready for `normalizeEchartSpec` and the inline JSON. */
@@ -26,8 +36,100 @@ export type EchartOption = Record<string, unknown>;
  * Derive the ECharts option for a chart block, then pass it through `normalizeEchartSpec`.
  *
  * The normalizer owns the bottom legend, the save action, and the axis-label discipline. Thus the
- * derivation sets no `title`, no `legend`, no `toolbox`, and no explicit series color. The theme palette
- * assigns the series colors by their order.
+ * derivation sets no `title`, no `legend`, and no `toolbox`. The theme palette assigns the series colors by
+ * their order, and the null category of a preset is the one series that names a color of its own.
+ *
+ * The axis of a channel names the label that the binding declares for its column. The semantic title of a
+ * preset answers next, and the raw column name answers last.
  */
 export declare function deriveChartOption(block: ChartBlock, rows: readonly ChartRow[], columns?: readonly string[]): Result<EchartOption, RenderProblem>;
-export {};
+/**
+ * Derive the option of one chart, and read the shared payload of its artifact where the inline form grows
+ * too large.
+ *
+ * A chart under the bound keeps its inline data, byte for byte as `deriveChartOption` gives it. Past the
+ * bound the series carry no row, and the option states how the page builds each series from the columnar
+ * payload of the artifact. Thus one dense chart costs the page one option and no second copy of the rows.
+ *
+ * A quick path of a type that draws one point for one row takes a second pass past the bound. The base rule
+ * of such a type builds a bare pair and it collects no descriptor, and the one-series composition plots the
+ * same points with the build beside them. The second pass runs past the bound alone, thus a chart under the
+ * bound keeps its bytes.
+ *
+ * A chart whose series holds a value that no cell gives stays inline whatever its size. A binned count, a
+ * five-number summary, an addressed pair, and the upper half of a band are each such a value, thus no
+ * descriptor can state one.
+ */
+export declare function deriveChartRender(block: ChartBlock, rows: readonly ChartRow[], columns: readonly string[] | undefined, target: ChartPayloadTarget): Result<ChartRender, RenderProblem>;
+/**
+ * The label of one named point. `{b}` is the name of the item, thus the label needs no function.
+ *
+ * A page-side series build writes the same member onto a flagged point, thus one constant answers for the
+ * inline form and the payload form alike.
+ */
+export declare const POINT_LABEL: EchartOption;
+/**
+ * One column that a page-side series build reads: the place of the column in the payload, and the per-row
+ * transform of the channel.
+ */
+export interface ChartColumnSource {
+    readonly column: number;
+    readonly transform?: ChartTransform;
+}
+/**
+ * One runtime series, as the page builds it from the columnar payload.
+ *
+ * `value` is the group value of a split by a group channel, and `category` is the place of a preset
+ * category. A series takes one of the two, or neither when it holds every row.
+ *
+ * `label` names the column that names each point, and `flags` names the rows that carry a point label. The
+ * flags are row places of the payload, thus a split carries the flags of its own rows alone.
+ *
+ * `sort` states that the form draws along the x axis, and `swap` states that the pair leads with the value
+ * of a horizontal bar.
+ */
+export interface ChartSeriesSource {
+    readonly x: ChartColumnSource;
+    readonly y: ChartColumnSource;
+    readonly group?: ChartColumnSource;
+    readonly value?: Cell;
+    readonly category?: number;
+    readonly label?: number;
+    readonly flags?: readonly number[];
+    readonly sort?: boolean;
+    readonly swap?: boolean;
+}
+/**
+ * The data source of one chart: the payload that it reads, the classification rule where a preset splits
+ * the rows, and one descriptor for each runtime series in series order.
+ */
+export interface ChartDataSource {
+    readonly payload: string;
+    readonly rule?: PresetRule;
+    readonly series: readonly ChartSeriesSource[];
+}
+/**
+ * The member of the option that carries the data source.
+ *
+ * The chart runtime reads no member of this name, and the page bootstrap removes it before it sets the
+ * option. The name leads with two underscores, thus no reader mistakes it for a field of the runtime.
+ */
+export declare const CHART_SOURCE_MEMBER = "__reportData";
+/** The payload that a dense chart reads: the key of the registry, and the columns of the payload. */
+export interface ChartPayloadTarget {
+    readonly key: string;
+    readonly columns: readonly string[];
+}
+/** The option of one chart, and whether it reads the registered payload of its artifact. */
+export interface ChartRender {
+    readonly option: EchartOption;
+    readonly readsPayload: boolean;
+}
+/**
+ * The transformed value of one column, one entry for each row. A row with no usable cell gives `null`.
+ *
+ * The page-side series build holds the twin of this function, because a chart that reads the payload
+ * transforms its columns in the browser. A shared test vector runs the two over one set of cells, thus the
+ * two cannot give different numbers in silence.
+ */
+export declare function transformColumn(rows: readonly ChartRow[], column: string, transform: ChartTransform): (number | null)[];