From 04203fc48558a0419b6ea795ddbdea38fd3fb055 Mon Sep 17 00:00:00 2001 From: Alexandr Date: Wed, 21 Oct 2026 13:29:31 +0200 Subject: [PATCH 01/17] MILAB-7194: store columns as result-pool ids and gates and conditions as column value refs --- .changeset/column-value-refs.md | 11 + kind/src/index.ts | 146 +++----- model/src/abundance.ts | 106 ++++++ model/src/column_access.ts | 67 ++++ model/src/columns.ts | 46 +-- model/src/dataModel.ts | 48 ++- model/src/index.ts | 501 +++++++++++---------------- model/src/metadata.ts | 126 +++++++ model/src/stored_data.ts | 34 ++ model/src/types.ts | 69 ++-- ui/src/components/PageHeader.vue | 4 +- ui/src/components/RunStatistics.vue | 31 +- ui/src/components/SettingsDrawer.vue | 137 ++++---- ui/src/pages/DistributionPage.vue | 6 +- workflow/src/main.tpl.tengo | 52 ++- 15 files changed, 807 insertions(+), 577 deletions(-) create mode 100644 .changeset/column-value-refs.md create mode 100644 model/src/abundance.ts create mode 100644 model/src/column_access.ts create mode 100644 model/src/metadata.ts create mode 100644 model/src/stored_data.ts diff --git a/.changeset/column-value-refs.md b/.changeset/column-value-refs.md new file mode 100644 index 0000000..0aadb6e --- /dev/null +++ b/.changeset/column-value-refs.md @@ -0,0 +1,11 @@ +--- +"@platforma-open/milaboratories.sort-seq-analysis.block": major +"@platforma-open/milaboratories.sort-seq-analysis.kind": major +"@platforma-open/milaboratories.sort-seq-analysis.model": major +"@platforma-open/milaboratories.sort-seq-analysis.ui": major +"@platforma-open/milaboratories.sort-seq-analysis.workflow": major +--- + +Columns are stored by their result-pool column ids: the dataset and the condition, gate and sort-fraction columns. The gates of the gate order, the unsorted input and the excluded conditions are stored as column value references of the gate and condition columns, so the block that produced the metadata knows which of its values this block uses; the ranks the workflow receives are keyed by the same references. The model finds columns, builds the options of every column and value picker and reads the sample names through the column collection API instead of the deprecated result pool API, the values are read by the model instead of fetched by the settings panel, and the workflow takes every column through a column bundle. The block no longer keeps snapshots of the gate and condition columns' values. +Opening a project created before this change keeps its dataset, and clears its condition, gate and sort-fraction columns, the gate order, the unsorted input and the excluded conditions, since they were stored by ids anchored to the dataset and as plain values, which name no producing block; they have to be picked again before the block runs. The initialization params of the kind carry the same ids and references and no longer carry the value snapshots, so templates made for an earlier version of the kind cannot be applied. +Gates, the input and excluded conditions that are no longer among the values of their column stay selected and are marked as not available instead of being removed silently, with a tooltip naming the block that was to provide them, as a link to it, and what went wrong. Picking another gate or condition column still resets the values picked in it. Excluding every condition is shown as a warning in the settings instead of disabling the run. diff --git a/kind/src/index.ts b/kind/src/index.ts index 1d2cef0..2002a57 100644 --- a/kind/src/index.ts +++ b/kind/src/index.ts @@ -1,9 +1,6 @@ import { assertParamsObject, defineBlockKind } from "@platforma-sdk/block-kind"; -import { - isAnchoredPColumnId, - isColumnUniversalKey, - type SUniversalPColumnId, -} from "@platforma-sdk/model"; +import type { ColumnUniversalId, ColumnValueId } from "@platforma-sdk/model"; +import { isColumnUniversalId, isColumnValueId } from "@platforma-sdk/model"; import { name, version } from "../package.json" with { type: "json" }; /** @@ -14,33 +11,21 @@ import { name, version } from "../package.json" with { type: "json" }; * says gate, which says sort fraction, and what the gate ladder is. A lab that runs the same * FACS ladder over library after library pins that once and then only picks the dataset. * - * **The three column refs travel, and that is not obvious — it holds because of what they - * point at.** An `SUniversalPColumnId` is anchored: it is meaningless without the anchor map - * that `abundanceRef` supplies, and `abundanceRef` is deliberately not a param (a `PlRef` names - * an entry in one project's result pool and nothing in another). What the id *encodes* is the - * column's own spec, and for a `samples-and-data` metadata column that spec's discriminator is - * `pl7.app/columnId` set to the column's **label** — every path that creates one passes - * `global: true`, so the value is `"Condition"`, not a generated per-project id. Two projects - * whose metadata carries a column labelled the same way therefore derive the same anchored id, - * and the template resolves. Where the upstream differs, it resolves to nothing and the picker - * shows no selection — visible, not silently wrong. + * The three columns are result-pool column ids, each naming the block that produced the column. + * The gates of the ladder are column value ids of the gate column: each names the column it was + * picked from, and through it the block that produced the value. A gate the column no longer + * carries stays in the ladder and is shown as not available. * - * **The three value snapshots are params for a reason that is easy to miss.** `gateValues`, - * `conditionValues` and `gateColumnLabel` are snapshots the UI writes when a column is picked, - * and they look like derived state that a fresh block should rebuild. But the model's - * `settingsIssues` validates `gateOrder` against `gateValues`, so a template carrying a gate - * ladder and an empty snapshot arrives with Run disabled and two complaints; and the only way - * to refill the snapshot from the UI is to re-pick the gate column, which overwrites - * `gateOrder` with every value of the column. The templated ladder would be destroyed by the - * act of making the block runnable. Carrying the snapshots keeps the template usable on - * arrival. + * `gateColumnLabel` travels with the gate column because the subtitle is a pure function of the + * block's data, and only the column's option knows its label. * * Left out, and why: * - * - **`abundanceRef`** — a `PlRef` into one project's result pool. Nothing can carry one. - * - **`excludedConditions` and `readFloor`** — run recipe, and both would travel fine. They are - * out because the operator scoped the contract to the metadata reading; a run's exclusions - * and its floor are decisions taken against the data in front of you. + * - **`abundanceRef`** — the dataset of one project's result pool, picked against the data in + * front of you. + * - **`excludedConditions`, `inputGate` and `readFloor`** — run recipe. They are out because the + * operator scoped the contract to the metadata reading; a run's exclusions, its reference and + * its floor are decisions taken against the data in front of you. * - **View state** — `customBlockLabel`, `resultsTableState`, `distributionGraphStates`. Not * configuration. * @@ -48,15 +33,24 @@ import { name, version } from "../package.json" with { type: "json" }; * `init` keeps its own default behind each one. */ export type BlockParams = { - conditionColumnRef?: SUniversalPColumnId; - gateColumnRef?: SUniversalPColumnId; - sortFractionColumnRef?: SUniversalPColumnId; - gateOrder?: string[]; - gateValues?: string[]; + conditionColumnRef?: ColumnUniversalId; + gateColumnRef?: ColumnUniversalId; + sortFractionColumnRef?: ColumnUniversalId; + gateOrder?: ColumnValueId[]; gateColumnLabel?: string; - conditionValues?: string[]; }; +// Identity (`name`/`version`) comes from this package's own `package.json`, so the on-wire +// `{name}@{version}` reference can never drift from what npm publishes; the bundler inlines the +// JSON import. +export const kind = defineBlockKind({ + name, + version, + parseInitializationParams, +}); + +// Internals + /** * The same contract at runtime, for params arriving from a template file rather than from typed * code — the only point that can catch a hand-written entry being wrong. @@ -67,92 +61,52 @@ export type BlockParams = { * key-set check would mean this file keeping its own field names as strings, and nothing holds * that list in step with the type above. * - * The checks stop at the shape of a value. That `gateOrder` names only values `gateValues` - * carries, that a gate column is not also the condition column — those are refused by - * `settingsIssues` in the model, where the whole configuration is in view. A parser stricter - * than the settings drawer would make this block export a template its own kind then refuses to - * apply. + * The checks stop at the form of a value. That a gate column is not also the condition column, + * that the ladder holds values of the gate column — those are refused by `settingsIssues` in the + * model, where the whole configuration is in view. A parser stricter than the settings drawer + * would make this block export a template its own kind then refuses to apply. */ function parseInitializationParams(value: unknown): BlockParams { assertParamsObject(value); - const { - conditionColumnRef, - gateColumnRef, - sortFractionColumnRef, - gateOrder, - gateValues, - gateColumnLabel, - conditionValues, - } = value; + const { conditionColumnRef, gateColumnRef, sortFractionColumnRef, gateOrder, gateColumnLabel } = + value; return { conditionColumnRef: optionalColumnRef(conditionColumnRef, "conditionColumnRef"), gateColumnRef: optionalColumnRef(gateColumnRef, "gateColumnRef"), sortFractionColumnRef: optionalColumnRef(sortFractionColumnRef, "sortFractionColumnRef"), - gateOrder: optionalStringList(gateOrder, "gateOrder"), - gateValues: optionalStringList(gateValues, "gateValues"), + gateOrder: optionalValueList(gateOrder, "gateOrder"), gateColumnLabel: optionalString(gateColumnLabel, "gateColumnLabel"), - conditionValues: optionalStringList(conditionValues, "conditionValues"), }; } /** - * A column ref is a canonically serialized id, not a free string, so this checks the string - * parses and that what comes out is a shape the SDK recognizes as a column id. - * - * **Not `isColumnUniversalId`, which is the obvious choice and the wrong one.** The block stores - * what `AnchoredIdDeriver.deriveS` returns — an *anchored* id, `{name, type, domain, axes}` with - * `{anchor, idx}` refs in the axes. `ColumnUniversalId` is a union of the PObject / filtered / - * discovered / overridden key forms and does not include the anchored one, so - * `isColumnUniversalId` returns `false` for every id this block actually holds. (The - * `SUniversalPColumnId` name is a deprecated alias of `ColumnUniversalId`, which is what makes - * the mistake look correct.) Verified against pl-model-common 1.48.0: an anchored id fails - * `isColumnUniversalId` and passes `isAnchoredPColumnId`. - * - * `isColumnUniversalKey` is kept alongside so a ref that arrives in one of the other forms is - * not refused for a reason that has nothing to do with the template being wrong. - * - * The cast is over a real check: both guards narrow the *parsed* value, and nothing in the SDK - * narrows the string that carried it. + * Any result-pool column id form is accepted — a leaf, filtered, discovered or overridden one. + * An id anchored against the dataset names no producing block and is refused. */ -function optionalColumnRef(value: unknown, field: string): SUniversalPColumnId | undefined { +function optionalColumnRef(value: unknown, field: string): ColumnUniversalId | undefined { if (value === undefined) return undefined; - if (typeof value !== "string") throw new Error(`'${field}' must be a column id.`); - - let parsed: unknown; - try { - parsed = JSON.parse(value); - } catch { - throw new Error(`'${field}' must be a column id.`); + if (!isColumnUniversalId(value)) { + throw new Error(`'${field}' must be a metadata column, written as a column id.`); } - - if (!isAnchoredPColumnId(parsed) && !isColumnUniversalKey(parsed)) - throw new Error(`'${field}' must be a column id.`); - - return value as SUniversalPColumnId; -} - -function optionalString(value: unknown, field: string): string | undefined { - if (value === undefined) return undefined; - if (typeof value !== "string") throw new Error(`'${field}' must be a string.`); return value; } -function optionalStringList(value: unknown, field: string): string[] | undefined { +/** Picked values of a column, each written as a column value id; a plain value is refused. */ +function optionalValueList(value: unknown, field: string): ColumnValueId[] | undefined { if (value === undefined) return undefined; if (!Array.isArray(value)) throw new Error(`'${field}' must be a list.`); return value.map((entry, index) => { - if (typeof entry !== "string") throw new Error(`'${field}[${index}]' must be a string.`); + if (!isColumnValueId(entry)) { + throw new Error(`'${field}[${index}]' must be a column value, written as a column value id.`); + } return entry; }); } -// Identity (`name`/`version`) comes from this package's own `package.json`, so the on-wire -// `{name}@{version}` reference can never drift from what npm publishes; the bundler inlines the -// JSON import. -export const kind = defineBlockKind({ - name, - version, - parseInitializationParams, -}); +function optionalString(value: unknown, field: string): string | undefined { + if (value === undefined) return undefined; + if (typeof value !== "string") throw new Error(`'${field}' must be a string.`); + return value; +} diff --git a/model/src/abundance.ts b/model/src/abundance.ts new file mode 100644 index 0000000..20ad97c --- /dev/null +++ b/model/src/abundance.ts @@ -0,0 +1,106 @@ +import type { + ColumnUniversalId, + DatasetOption, + DatasetSelection, + PlRef, + RenderCtxBase, +} from "@platforma-sdk/model"; +import { + buildDatasetOptions, + createDatasetSelection, + createGlobalPObjectId, + createPrimaryRef, + deriveColumnOptions, + isPColumnSpec, + isPlRef, + parseColumnIdSafely, +} from "@platforma-sdk/model"; +import { findColumn, resultPool } from "./column_access"; +import { Alphabet, AlphabetDomain, Annotation, abundanceSelector } from "./columns"; + +/** The dataset and the subset it is restricted to, as the block stores them. */ +export type AbundancePick = { + abundanceRef: ColumnUniversalId | undefined; + filterRef: ColumnUniversalId | undefined; +}; + +/** + * Per-sample abundances on the variant grain of upstream blocks, as dataset picker options, each + * with its subset columns (e.g. Repertoire Labeling labels) as filters. Every option is a + * result-pool leaf, so it names the block that produced the column. + */ +export function getAbundanceOptions(ctx: RenderCtxBase): DatasetOption[] { + // Only the filters are taken from here: the datasets below are matched to them by column id. + const withFilters = + buildDatasetOptions(ctx, { + primary: (spec) => + isPColumnSpec(spec) && + spec.axesSpec.length === 2 && + spec.annotations?.[Annotation.AbundanceIsPrimary] === "true" && + spec.annotations?.[Annotation.AbundanceNormalized] === "false", + // Only subsets keyed by the dataset's key axis alone + filter: (spec) => + isPColumnSpec(spec) && + spec.axesSpec.length === 1 && + DATASET_KEY_AXES.has(spec.axesSpec[0].name), + requireEnrichments: false, + }) ?? []; + const columns = resultPool(ctx).filter({ include: abundanceSelector }); + return deriveColumnOptions(columns).flatMap(({ id, label }): DatasetOption[] => { + const ref = toPlRef(id); + if (ref === undefined) return []; + const primary = { ref, label }; + const filters = withFilters.find((o) => toColumnId(o.primary.ref) === id)?.filters; + return [filters === undefined ? { primary } : { primary, filters }]; + }); +} + +/** The dataset picker's selection of the stored dataset and subset. */ +export function toAbundanceSelection(pick: AbundancePick): DatasetSelection | undefined { + const column = pick.abundanceRef === undefined ? undefined : toPlRef(pick.abundanceRef); + if (column === undefined) return undefined; + const filter = pick.filterRef === undefined ? undefined : toPlRef(pick.filterRef); + return createDatasetSelection(createPrimaryRef(column, filter)); +} + +/** The dataset and subset a dataset picker selection stores. */ +export function fromAbundanceSelection(selection: DatasetSelection | undefined): AbundancePick { + const primary = selection?.primary; + return { + abundanceRef: primary === undefined ? undefined : toColumnId(primary.column), + filterRef: primary?.filter === undefined ? undefined : toColumnId(primary.filter), + }; +} + +/** + * Whether the dataset is at the nucleotide grain; `undefined` while its spec is not known or it + * declares no alphabet. + */ +export function isNucleotideDataset( + ctx: RenderCtxBase, + abundanceRef: ColumnUniversalId, +): boolean | undefined { + // Axis 1 is the variant axis; the abundance selector admits only two-axis columns. + const alphabet = findColumn(ctx, abundanceRef)?.getSpec().axesSpec[1]?.domain?.[AlphabetDomain]; + return alphabet === undefined ? undefined : alphabet === Alphabet.Nucleotide; +} + +/** The result-pool id of the upstream output a ref points to: it names the same block and column. */ +export function toColumnId(ref: PlRef): ColumnUniversalId { + return createGlobalPObjectId(ref.blockId, ref.name); +} + +// Internals + +/** Key axes of the datasets this block filters: bulk and single-cell clonotypes, and variants. */ +const DATASET_KEY_AXES: ReadonlySet = new Set([ + "pl7.app/vdj/clonotypeKey", + "pl7.app/vdj/scClonotypeKey", + "pl7.app/variantKey", +]); + +/** The upstream output a result-pool id names, as the ref the dataset picker works with. */ +function toPlRef(id: ColumnUniversalId): PlRef | undefined { + const key = parseColumnIdSafely(id); + return isPlRef(key) ? key : undefined; +} diff --git a/model/src/column_access.ts b/model/src/column_access.ts new file mode 100644 index 0000000..16a7584 --- /dev/null +++ b/model/src/column_access.ts @@ -0,0 +1,67 @@ +import type { + AxisSpec, + ColumnUniversalId, + PColumn, + PColumnDataUniversal, + RelaxedAxisSelector, + RenderCtxBase, + StringMatcher, + TreeNodeAccessor, +} from "@platforma-sdk/model"; +import { Column, ColumnRecipe, ColumnsCollection, isDataColumn } from "@platforma-sdk/model"; + +/** A column offered in a column picker, by its result-pool id. */ +export type ColumnPickerOption = { + value: ColumnUniversalId; + label: string; +}; + +/** Columns of upstream blocks. */ +export function resultPool(ctx: RenderCtxBase): ColumnsCollection { + return ColumnsCollection(["result_pool"], { ctx: ctx.ctx }); +} + +/** + * The column with this id, found by id alone. `undefined` while it is still resolving and once + * it is gone: a stored id may name a column its upstream block no longer produces. + */ +export function findColumn(ctx: RenderCtxBase, id: ColumnUniversalId): ColumnRecipe | undefined { + if (ColumnRecipe.getStatus(id, { ctx: ctx.ctx }) !== "present") return undefined; + return Column(id, { ctx: ctx.ctx }); +} + +/** + * Columns of one of this block's outputs. `undefined` until the output is there and every column + * of it has arrived. + */ +export function getOutputColumns( + ctx: RenderCtxBase, + accessor: TreeNodeAccessor | undefined, +): ColumnsCollection | undefined { + if (accessor === undefined) return undefined; + const collection = ColumnsCollection([accessor], { ctx: ctx.ctx }); + return collection.isFinal() ? collection : undefined; +} + +/** + * Columns as the `PColumn`s graph frames are built from. Only plain stored columns have that + * form; data still on its way stays `undefined`. + */ +export function toPColumns(columns: ColumnRecipe[]): PColumn[] { + return columns + .filter(isDataColumn) + .map((column) => ({ id: column.id, spec: column.getSpec(), data: column.getData() })); +} + +/** A selector of exactly this axis: its name, type and every entry of its domain. */ +export function axisSelector(axis: AxisSpec): RelaxedAxisSelector { + const domain = Object.fromEntries( + Object.entries(axis.domain ?? {}).map(([key, value]) => [key, [exact(value)]]), + ); + return { name: [exact(axis.name)], type: axis.type, domain }; +} + +/** A matcher of exactly this string. A bare string in a selector is a regex. */ +export function exact(value: string): StringMatcher { + return { type: "exact", value }; +} diff --git a/model/src/columns.ts b/model/src/columns.ts index 9e176af..dfe17ea 100644 --- a/model/src/columns.ts +++ b/model/src/columns.ts @@ -7,7 +7,8 @@ * annotations and never names an axis. */ -import type { AnchoredPColumnSelector, PColumnSpec, PObjectSpec } from "@platforma-sdk/model"; +import type { AnchoredPColumnSelector, RelaxedColumnSelector } from "@platforma-sdk/model"; +import { exact } from "./column_access"; /** Annotation keys this block reads on upstream columns. */ export const Annotation = { @@ -84,14 +85,6 @@ export const ReferenceMode = { export const AlphabetDomain = "pl7.app/alphabet"; export const Alphabet = { Nucleotide: "nucleotide", AminoAcid: "aminoacid" } as const; -function isPColumnSpec(spec: PObjectSpec): spec is PColumnSpec { - return spec.kind === "PColumn"; -} - -function annotation(spec: PColumnSpec, key: string): string | undefined { - return spec.annotations?.[key]; -} - /** * The anchor: per-sample abundance on the variant grain. * @@ -99,37 +92,36 @@ function annotation(spec: PColumnSpec, key: string): string | undefined { * normalized, and three more carry the abundance marker without the primary one — admitting * those computes a bin score over aggregated totals with output of ordinary shape. * - * Two axes by COUNT, not name — see the file header. + * Exactly two axes, matched by COUNT, not name — see the file header. */ -export function isAbundanceAnchor(spec: PObjectSpec): boolean { - if (!isPColumnSpec(spec)) return false; - if (spec.axesSpec.length !== 2) return false; - return ( - annotation(spec, Annotation.AbundanceIsPrimary) === "true" && - annotation(spec, Annotation.AbundanceNormalized) === "false" - ); -} +export const abundanceSelector: RelaxedColumnSelector = { + axes: [{}, {}], + partialAxesMatch: false, + annotations: { + [Annotation.AbundanceIsPrimary]: [exact("true")], + [Annotation.AbundanceNormalized]: [exact("false")], + }, +}; /** - * Per-sample metadata — the option list the three roles are picked from, so it is expected to - * resolve to many. Which role a column plays is the user's pick; no spec predicate can tell. + * Per-sample metadata on the dataset's sample axis — the option list the three roles are picked + * from, so it is expected to resolve to many. Which role a column plays is the user's pick; no + * spec predicate can tell. * * `pl7.app/metadata` is the column's NAME, not an annotation. Matching it as an annotation * matches nothing silently: the list comes back empty and the pickers look broken. */ -export const metadataSelector: AnchoredPColumnSelector = { - axes: [{ anchor: "main", idx: 0 }], - name: PColumnName.Metadata, +export const metadataSelector: RelaxedColumnSelector = { + name: [exact(PColumnName.Metadata)], }; /** * The sample axis's label column. `pl7.app/isLabel` is required alongside the name, which the * variant label column shares. */ -export const sampleLabelSelector: AnchoredPColumnSelector = { - axes: [{ anchor: "main", idx: 0 }], - name: PColumnName.SampleLabel, - annotations: { "pl7.app/isLabel": "true" }, +export const sampleLabelSelector: RelaxedColumnSelector = { + name: [exact(PColumnName.SampleLabel)], + annotations: { "pl7.app/isLabel": [exact("true")] }, }; /** diff --git a/model/src/dataModel.ts b/model/src/dataModel.ts index 7b2d54b..e0895d5 100644 --- a/model/src/dataModel.ts +++ b/model/src/dataModel.ts @@ -1,6 +1,13 @@ import type { GraphMakerState } from "@milaboratories/graph-maker"; import { kind } from "@platforma-open/milaboratories.sort-seq-analysis.kind"; -import { createPlDataTableStateV2, DataModelBuilder } from "@platforma-sdk/model"; +import { + createPlDataTableStateV2, + DataModelBuilder, + isColumnUniversalId, + isColumnValueId, +} from "@platforma-sdk/model"; +import { toColumnId } from "./abundance"; +import type { BlockDataV1, BlockDataV2 } from "./stored_data"; import type { BlockData } from "./types"; /** @@ -22,12 +29,14 @@ export function defaultDistributionGraphState(title: string): GraphMakerState { * invented. Later shape changes add `.migrate(...)` links rather than editing this. */ export const blockDataModel = new DataModelBuilder({ kind }) - .from>("Ver_2026_08_07") + .from("Ver_2026_08_07") // Each of the two score tables keeps its own grid state; older blocks have only one. - .migrate("Ver_2026_09_21", (previous) => ({ + .migrate("Ver_2026_09_21", (previous) => ({ ...previous, ntResultsTableState: createPlDataTableStateV2(), })) + // Columns become result-pool ids and the picked values column value ids. + .migrate("Ver_2026_10_21", toColumnIds) // The kind's init-params contract, field for field. `.templateParams(...)` in `index.ts` // projects the same fields back out; the two must name the same set. `params` is optional, // so every field keeps a default. @@ -36,9 +45,7 @@ export const blockDataModel = new DataModelBuilder({ kind }) gateColumnRef: params?.gateColumnRef, sortFractionColumnRef: params?.sortFractionColumnRef, gateOrder: params?.gateOrder ?? [], - gateValues: params?.gateValues ?? [], gateColumnLabel: params?.gateColumnLabel, - conditionValues: params?.conditionValues ?? [], // Not init params — see the kind. The two facts and the baseline are absent rather than // defaulted: an absent input means no enrichment, and an absent order flag means ordered. @@ -48,3 +55,34 @@ export const blockDataModel = new DataModelBuilder({ kind }) ntResultsTableState: createPlDataTableStateV2(), distributionGraphStates: {}, })); + +// Internals + +/** + * Moves stored data to column ids. A ref to an upstream output becomes the result-pool id of that + * output, which names the same block and column. The condition, gate and sort-fraction columns + * were picked by ids anchored against the dataset and the gates, excluded conditions and input + * gate stored as plain values; neither names the block that produced the metadata, so they + * cannot become column ids and column value ids and are dropped, to be picked again. The + * snapshots of the gate and condition columns' values are dropped too: the model reads the + * values of the picked columns itself. + */ +function toColumnIds(data: BlockDataV2): BlockData { + const { gateValues: _gateValues, conditionValues: _conditionValues, ...kept } = data; + const column = (stored: string | undefined) => (isColumnUniversalId(stored) ? stored : undefined); + const value = (picked: string | undefined) => (isColumnValueId(picked) ? picked : undefined); + const gateColumnRef = column(data.gateColumnRef); + return { + ...kept, + abundanceRef: data.abundanceRef === undefined ? undefined : toColumnId(data.abundanceRef), + filterRef: data.filterRef === undefined ? undefined : toColumnId(data.filterRef), + conditionColumnRef: column(data.conditionColumnRef), + gateColumnRef, + sortFractionColumnRef: column(data.sortFractionColumnRef), + // The label names the gate column, so it goes with it. + gateColumnLabel: gateColumnRef === undefined ? undefined : data.gateColumnLabel, + gateOrder: data.gateOrder.filter(isColumnValueId), + excludedConditions: data.excludedConditions.filter(isColumnValueId), + inputGate: value(data.inputGate), + }; +} diff --git a/model/src/index.ts b/model/src/index.ts index a392224..35be8c7 100644 --- a/model/src/index.ts +++ b/model/src/index.ts @@ -1,38 +1,31 @@ import { BlockModelV3, type BlockRenderCtx, - buildDatasetOptions, - createGlobalPObjectId, + type ColumnRecipe, + columnValueLabel, createPFrameForGraphs, createPlDataTableV3, - DataColumn, - type DatasetOption, discoverTableColumnSnaphots, type InferOutputsType, - isPColumnSpec, - type PColumn, - type PColumnSpec, - type PColumnValues, - type StringMatcher, - type SUniversalPColumnId, + parseColumnValueId, } from "@platforma-sdk/model"; import { kind } from "@platforma-open/milaboratories.sort-seq-analysis.kind"; -import { - Alphabet, - AlphabetDomain, - Annotation, - FacsBin, - isAbundanceAnchor, - metadataSelector, - PColumnName, - sampleLabelSelector, -} from "./columns"; +import { getAbundanceOptions, isNucleotideDataset } from "./abundance"; +import type { ColumnPickerOption } from "./column_access"; +import { exact, getOutputColumns, toPColumns } from "./column_access"; +import { Alphabet, AlphabetDomain, FacsBin, PColumnName } from "./columns"; import { blockDataModel } from "./dataModel"; +import type { MetadataRole } from "./metadata"; +import { getMetadataOptions, getMetadataValues, getSampleLabels, narrowToRole } from "./metadata"; import type { BlockArgs, BlockData, RunManifest } from "./types"; +export { fromAbundanceSelection, toAbundanceSelection } from "./abundance"; +export type { AbundancePick } from "./abundance"; export { blockDataModel, defaultDistributionGraphState } from "./dataModel"; export * from "./columns"; export * from "./types"; +export type { ColumnPickerOption } from "./column_access"; +export type { MetadataColumnValues } from "./metadata"; /** * Whether the baseline is offered. Pairs with `EMIT_BASELINE_COLUMNS` in @@ -62,29 +55,35 @@ export function settingsIssues(data: BlockData): string[] { } // The order is a selection, so coverage is deliberately NOT checked: a gate column carrying - // an input or a specificity arm is the ordinary case. Only non-emptiness and that it names - // nothing outside the column. + // an input or a specificity arm is the ordinary case. Only non-emptiness and that every gate + // was picked from the gate column. A gate the column no longer carries is shown as not + // available in the drawer; `data` does not hold the column's values, so it is not refused + // here, and neither is excluding every condition. // // Guarded on the pick so a fresh block does not get two complaints for one unmade choice. - if (data.gateColumnRef !== undefined) { - if (data.gateValues.length === 0) { - issues.push("The gate column has no values to rank"); - } else if (data.gateOrder.length === 0) { - issues.push("Keep at least one gate in the order — every gate has been removed"); + const gateColumn = data.gateColumnRef; + if (gateColumn !== undefined) { + if (data.gateOrder.length === 0) { + issues.push( + "Keep at least one gate in the order — the gate column has none, or every gate has been removed", + ); } - const unknown = data.gateOrder.filter((value) => !data.gateValues.includes(value)); - if (unknown.length > 0) { - issues.push(`Ordered value(s) the gate column does not carry: ${unknown.join(", ")}`); + const foreign = [...data.gateOrder, ...(data.inputGate === undefined ? [] : [data.inputGate])] + .filter((picked) => parseColumnValueId(picked).column !== gateColumn) + .map(columnValueLabel); + if (foreign.length > 0) { + issues.push(`Gate value(s) picked from another column: ${foreign.join(", ")}`); } } - // Refused rather than producing nothing: an empty result is indistinguishable from a - // failed run. - if ( - data.conditionValues.length > 0 && - data.conditionValues.every((value) => data.excludedConditions.includes(value)) - ) { - issues.push("At least one condition must remain — every value is currently excluded"); + const conditionColumn = data.conditionColumnRef; + if (conditionColumn !== undefined) { + const foreign = data.excludedConditions + .filter((picked) => parseColumnValueId(picked).column !== conditionColumn) + .map(columnValueLabel); + if (foreign.length > 0) { + issues.push(`Excluded condition(s) picked from another column: ${foreign.join(", ")}`); + } } if (data.readFloor !== undefined && data.readFloor < 0) { @@ -103,10 +102,8 @@ export function settingsIssues(data: BlockData): string[] { // A gate that referenced itself would give exactly 1 everywhere. Reachable by // reordering after the pick, so the option list alone is not enough. issues.push( - `The input '${data.inputGate}' is also a ranked gate — remove it from the gate order`, + `The input '${columnValueLabel(data.inputGate)}' is also a ranked gate — remove it from the gate order`, ); - } else if (data.gateValues.length > 0 && !data.gateValues.includes(data.inputGate)) { - issues.push(`The gate column does not carry the input value '${data.inputGate}'`); } } @@ -116,23 +113,6 @@ export function settingsIssues(data: BlockData): string[] { return issues; } -/** A bare string in a selector is a REGEX, so an exact name must say so. */ -function exact(name: string): StringMatcher { - return { type: "exact", value: name }; -} - -/** Conditions read off the domain key, sorted — they carry no order of their own. */ -function distributionConditionsOf( - columns: readonly C[], -): string[] { - const conditions = new Set(); - for (const column of columns) { - const condition = column.spec.domain?.[FacsBin.ConditionDomain]; - if (condition !== undefined) conditions.add(condition); - } - return [...conditions].sort(); -} - /** * With an entry for the plot's title, without one for the nav. The count is what the run drew, * not the computation's cut — that is a maximum, and would read "Top 20" over twelve variants. @@ -147,118 +127,38 @@ export function distributionPlotTitle( : `Variant Frequency — ${condition}`; } -/** - * One scores table for one grain. A nucleotide run emits two column families on two axes, told - * apart by the `pl7.app/alphabet` domain. `undefined` where the run produced none. - */ -function buildScoresTable(ctx: BlockRenderCtx, alphabet: string) { - const all = ctx.outputs?.resolve("scoresPf")?.getPColumns() as - | PColumn[] - | undefined; - if (!all) return undefined; - // The alphabet is the only thing separating the two families: they share every name and - // condition domain, and mixing them joins protein scores to nothing. - const own = all.filter((column) => column.spec.domain?.[AlphabetDomain] === alphabet); - if (own.length === 0) return undefined; - - // Unordered gates produce no `gateRankMean`, so the enrichment carries the anchor there. - // Both are keyed on the variant axes, so the key shape below is the same either way. - const pickAnchor = (name: string) => - own - .filter((column) => column.spec.name === name) - .sort((a, b) => - ( - (a.spec.domain?.[FacsBin.ConditionDomain] ?? "") + - "\0" + - (a.spec.domain?.[FacsBin.GateDomain] ?? "") - ).localeCompare( - (b.spec.domain?.[FacsBin.ConditionDomain] ?? "") + - "\0" + - (b.spec.domain?.[FacsBin.GateDomain] ?? ""), - ), - )[0]; - const anchor = pickAnchor(FacsBin.GateRankMean) ?? pickAnchor(FacsBin.GateEnrichment); - if (!anchor) return undefined; - - // Primary columns, so they are always shown and never compete with a pool namesake. - // - // Filtered to the anchor's own key shape: `scoresPf` also carries the per-position baseline - // on `[parentId, position]`, and passing that in fails the whole table with - // `discoverColumns failed`. Compared on axis names, so a new differently-keyed column does - // not need this list updated. - const anchorKey = anchor.spec.axesSpec.map((axis) => axis.name).join("\0"); - const primaryColumns = own - .filter((column) => column.spec.axesSpec.map((axis) => axis.name).join("\0") === anchorKey) - .map((column) => DataColumn.fromColumn(column)); - - // Everything else the variant axis reaches. - // - // The WHOLE `pl7.app/facsBin/` namespace is excluded, this block's own included. A second - // sort-seq block's columns are identical in everything discovery matches on, and a selector - // can require a domain value but cannot refuse one — so there is no selector admitting ours - // and refusing a sibling's. This also drops the duplicate our own `exports.pf` creates. - const { primary, secondary } = discoverTableColumnSnaphots(ctx, { - anchors: { main: anchor.spec }, - // Strict axis equality. "related" reaches every column the variant axis participates in, - // giving a row per variant per position per gate. - selector: { - mode: "exact", - exclude: [{ name: [{ type: "regex", value: "^pl7\\.app/facsBin/.*$" }] }], - }, - }); - - return createPlDataTableV3(ctx, { - primaryColumns, - columns: [...primary, ...secondary], - tableState: - alphabet === Alphabet.Nucleotide ? ctx.data.ntResultsTableState : ctx.data.resultsTableState, - displayOptions: { - /** - * First match wins, and an unmatched column keeps its own annotation — upstream sets - * `default` on nearly everything, so the catch-all last is required. - * - * `optional` rather than `hidden`: they stay one click away in the column picker. - */ - visibility: [ - { match: { name: exact(FacsBin.GateRankMean) }, visibility: "default" }, - { match: { name: exact(FacsBin.BinScore) }, visibility: "default" }, - { match: { name: exact(FacsBin.GateEnrichment) }, visibility: "default" }, - { match: { name: exact(PColumnName.VariantLabel) }, visibility: "default" }, - { match: { name: exact(PColumnName.Mutations) }, visibility: "default" }, - { match: { name: ".*" }, visibility: "optional" }, - ], - }, - }); -} - -// Key axes of the datasets this block filters: bulk and single-cell clonotypes, and variants. -const DATASET_KEY_AXES: ReadonlySet = new Set([ - "pl7.app/vdj/clonotypeKey", - "pl7.app/vdj/scClonotypeKey", - "pl7.app/variantKey", -]); - export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind }) .args((data) => { // Throwing disables Run but carries no reason to the user; `settingsIssues` names it. const issues = settingsIssues(data); if (issues.length > 0) throw new Error(issues.join("; ")); + // `settingsIssues` refuses each of these absent; checked again so the type says so. + const { abundanceRef, conditionColumnRef, gateColumnRef } = data; + if ( + abundanceRef === undefined || + conditionColumnRef === undefined || + gateColumnRef === undefined + ) { + throw new Error("Select the dataset, the condition column and the gate column"); + } + // Two facts, not a mode. An enrichment needs a reference, so naming one is what asks for // it; ranks need an order, so the toggle is what asks for those. `inputGate` carries the // first straight through, so only the second needs a local. const ordered = data.gatesOrdered !== false; return { - abundanceRef: data.abundanceRef!, - conditionColumnRef: data.conditionColumnRef!, - gateColumnRef: data.gateColumnRef!, + abundanceRef, + conditionColumnRef, + gateColumnRef, // Position becomes the rank, contiguous over the gates the list holds — a gap would // move every score, since ranks enter the weighted mean as numbers. The key set also // tells the computation which gates the run covers. // // Canonicalised so an edit with no effect produces the same bytes and does not fire - // the staleness gate. + // the staleness gate. Keyed by the gate's column value id, which the workflow turns back + // into the gate value. gateRanks: Object.fromEntries(data.gateOrder.map((gate, index) => [gate, index + 1])), excludedConditions: [...data.excludedConditions].sort(), // `undefined` rather than a value: the workflow omits the field and the computation @@ -278,10 +178,10 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } BASELINE_AVAILABLE && data.inputGate !== undefined && data.baseline === "sequence" ? data.baselineSequence : undefined, - // The subset's canonical column id, which the workflow stamps as the outputs' + // The subset's result-pool id, which the workflow stamps as the outputs' // `pl7.app/inputSubset`. Absent without a filter, so unfiltered args are unchanged. ...(data.filterRef !== undefined && { - inputFilter: createGlobalPObjectId(data.filterRef.blockId, data.filterRef.name), + inputFilter: data.filterRef, }), }; }) @@ -294,39 +194,7 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } * The anchor. Matched on axis count plus the two abundance annotations, never on a name. * Each carries its subset columns (e.g. Repertoire Labeling labels) as filters. */ - .output( - "abundanceOptions", - (ctx): DatasetOption[] => - buildDatasetOptions(ctx, { - primary: isAbundanceAnchor, - // Only subsets keyed by the dataset's key axis alone - filter: (spec) => - isPColumnSpec(spec) && - spec.axesSpec.length === 1 && - DATASET_KEY_AXES.has(spec.axesSpec[0].name), - requireEnrichments: false, - }) ?? [], - ) - - /** Every per-sample metadata column in the anchor's context — one query, four consumers. */ - .output("metadataColumns", (ctx) => { - const anchor = ctx.data.abundanceRef; - if (!anchor) return undefined; - - const anchorCtx = ctx.resultPool.resolveAnchorCtx({ main: anchor }); - if (!anchorCtx) return undefined; - - const columns = ctx.resultPool.getAnchoredPColumns({ main: anchor }, [metadataSelector]); - if (!columns) return undefined; - - return columns.map((column) => ({ - // From the column's own spec, so id and objectId are correlated by construction rather - // than by list position. - value: anchorCtx.deriveS(column.spec), - objectId: column.id, - label: column.spec.annotations?.[Annotation.Label] ?? column.spec.name, - })); - }) + .output("abundanceOptions", (ctx) => getAbundanceOptions(ctx)) /** * Whether the selected dataset is at the nucleotide grain. The one fact the drawer needs that @@ -334,57 +202,36 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } * `settingsIssues` — that choice is not a broken run, just an empty baseline. */ .output("datasetIsNucleotide", (ctx) => { - const anchor = ctx.data.abundanceRef; - if (!anchor) return undefined; - - const spec = ctx.resultPool.getPColumnSpecByRef(anchor); - // Axis 1 is the variant axis; `isAbundanceAnchor` admits only two-axis columns. - const alphabet = spec?.axesSpec?.[1]?.domain?.[AlphabetDomain]; - return alphabet === undefined ? undefined : alphabet === Alphabet.Nucleotide; + const abundanceRef = ctx.data.abundanceRef; + if (abundanceRef === undefined) return undefined; + return isNucleotideDataset(ctx, abundanceRef); }) /** The pickers, each offering what the other two roles do not already hold. */ - .output("conditionOptions", (ctx) => narrowTo(ctx, "conditionColumnRef")) - .output("gateOptions", (ctx) => narrowTo(ctx, "gateColumnRef")) - .output("sortFractionOptions", (ctx) => narrowTo(ctx, "sortFractionColumnRef")) + .output("conditionOptions", (ctx) => roleOptions(ctx, "conditionColumnRef")) + .output("gateOptions", (ctx) => roleOptions(ctx, "gateColumnRef")) + .output("sortFractionOptions", (ctx) => roleOptions(ctx, "sortFractionColumnRef")) // --------------------------------------------------------------------------- - // The two controls that need a picked column's values rather than its spec. + // The controls that need a picked column's values rather than its spec. // --------------------------------------------------------------------------- /** - * EVERY metadata column, not just the picked ones. The UI snapshots values in the same - * gesture as the pick, so they must be in hand before it; publishing only picked columns - * lags by a round trip and the gate-order control never appears. + * The values of every metadata column on offer, so the gate order can be seeded in the same + * gesture as the gate pick, and the picked gates, input and excluded conditions be shown by + * the values they pick. */ - .output("metadataColumnsPframe", (ctx) => { - const anchor = ctx.data.abundanceRef; - if (!anchor) return undefined; - - const columns = ctx.resultPool.getAnchoredPColumns({ main: anchor }, [metadataSelector]); - if (!columns || columns.length === 0) return undefined; - - return ctx.createPFrame(columns as PColumn[]); + .output("metadataValues", (ctx) => { + const abundanceRef = ctx.data.abundanceRef; + if (abundanceRef === undefined) return undefined; + return getMetadataValues(ctx, abundanceRef, ctx.data); }) - /** The sample label column, for resolving the pooling report's `PlId`s to names. */ - .output("sampleLabelPframe", (ctx) => { - const anchor = ctx.data.abundanceRef; - if (!anchor) return undefined; - - const columns = ctx.resultPool.getAnchoredPColumns({ main: anchor }, [sampleLabelSelector]); - if (!columns || columns.length === 0) return undefined; - - return ctx.createPFrame(columns as PColumn[]); - }) - - /** The `PObjectId` for reading that column out of the frame above. */ - .output("sampleLabelColumnId", (ctx) => { - const anchor = ctx.data.abundanceRef; - if (!anchor) return undefined; - - const columns = ctx.resultPool.getAnchoredPColumns({ main: anchor }, [sampleLabelSelector]); - return columns?.[0]?.id; + /** Sample names by sample id, for the pooling report's sample ids. */ + .output("sampleLabels", (ctx) => { + const abundanceRef = ctx.data.abundanceRef; + if (abundanceRef === undefined) return undefined; + return getSampleLabels(ctx, abundanceRef); }) // --------------------------------------------------------------------------- @@ -413,17 +260,12 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } /** Which levels the run produced, so the UI shows one table or two. */ .output("scoreLevels", (ctx) => { - const own = ctx.outputs?.resolve("scoresPf")?.getPColumns(); + const own = getOutputColumns(ctx, ctx.outputs?.resolve("scoresPf"))?.getColumns(); if (!own) return undefined; - const levels = new Set(); - for (const column of own) { - const alphabet = column.spec.domain?.[AlphabetDomain]; - if (alphabet !== undefined) levels.add(alphabet); - } - return [...levels].sort(); + return scoreLevelsOf(own); }) .output("distributionConditions", (ctx) => { - const columns = ctx.outputs?.resolve("distributionPf")?.getPColumns(); + const columns = getOutputColumns(ctx, ctx.outputs?.resolve("distributionPf"))?.getColumns(); if (!columns) return undefined; return distributionConditionsOf(columns); }) @@ -436,16 +278,16 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } * axis's label column, without which charts draw raw keys. */ .outputWithStatus("distributionPf", (ctx) => { - const columns = ctx.outputs?.resolve("distributionPf")?.getPColumns(); + const columns = getOutputColumns(ctx, ctx.outputs?.resolve("distributionPf"))?.getColumns(); if (!columns) return undefined; - return createPFrameForGraphs(ctx, columns); + return createPFrameForGraphs(ctx, toPColumns(columns)); }) /** The same columns as id+spec pairs, so a page binds to real specs instead of names. */ .output("distributionPfCols", (ctx) => { - const columns = ctx.outputs?.resolve("distributionPf")?.getPColumns(); + const columns = getOutputColumns(ctx, ctx.outputs?.resolve("distributionPf"))?.getColumns(); if (!columns) return undefined; - return columns.map((column) => ({ id: column.id, spec: column.spec })); + return columns.map((column) => ({ id: column.id, spec: column.getSpec() })); }) /** The not-ready-safe accessor is required: plain `getDataAsJson` throws mid-run. */ @@ -491,19 +333,13 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } /** Exposed so the UI can show it as the subtitle field's placeholder. */ .output("defaultBlockLabel", (ctx) => deriveBlockLabel(ctx.data)) - /** - * The inverse of the data model's `init`, field for field. Mandatory — `done()` throws - * without it. The value snapshots are included: without them a templated gate ladder arrives - * unrunnable, and making it runnable destroys the ladder. - */ + /** The inverse of the data model's `init`, field for field. Mandatory — `done()` throws without it. */ .templateParams((data) => ({ conditionColumnRef: data.conditionColumnRef, gateColumnRef: data.gateColumnRef, sortFractionColumnRef: data.sortFractionColumnRef, gateOrder: data.gateOrder, - gateValues: data.gateValues, gateColumnLabel: data.gateColumnLabel, - conditionValues: data.conditionValues, })) /** Constant. What an instance is configured for belongs in the subtitle. */ @@ -520,14 +356,12 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } * back as a space — `CD4+` being an ordinary condition value. */ .sections((ctx) => { - const columns = ctx.outputs?.resolve("distributionPf")?.getPColumns(); + const columns = getOutputColumns(ctx, ctx.outputs?.resolve("distributionPf"))?.getColumns(); // Each entry must stay an `as const` literal with no annotation on the array: the route's // query type is derived from the href's template literal type. - const levels = ctx.outputs?.resolve("scoresPf")?.getPColumns(); - const hasNt = (levels ?? []).some( - (column) => column.spec.domain?.[AlphabetDomain] === Alphabet.Nucleotide, - ); + const levels = getOutputColumns(ctx, ctx.outputs?.resolve("scoresPf"))?.getColumns(); + const hasNt = scoreLevelsOf(levels ?? []).includes(Alphabet.Nucleotide); return [ // Must match the page's own title. @@ -554,65 +388,126 @@ export function deriveBlockLabel(data: BlockData): string { // Every gate, not just the ends: a reordering of the middle is exactly the change that // silently moves every score. - return `${data.gateColumnLabel}: ${ordered.join("-")}`; + return `${data.gateColumnLabel}: ${ordered.map(columnValueLabel).join("-")}`; +} + +export type BlockOutputs = InferOutputsType; + +// Internals + +/** The metadata options a role picker offers. */ +function roleOptions( + ctx: BlockRenderCtx, + role: MetadataRole, +): ColumnPickerOption[] | undefined { + const abundanceRef = ctx.data.abundanceRef; + if (abundanceRef === undefined) return undefined; + const options = getMetadataOptions(ctx, abundanceRef); + if (options === undefined) return undefined; + return narrowToRole(options, ctx.data, role); +} + +/** The grains the run scored at, read off the alphabet domain of its score columns. */ +function scoreLevelsOf(columns: readonly ColumnRecipe[]): string[] { + const levels = new Set(); + for (const column of columns) { + const alphabet = column.getSpec().domain?.[AlphabetDomain]; + if (alphabet !== undefined) levels.add(alphabet); + } + return [...levels].sort(); +} + +/** Conditions read off the domain key, sorted — they carry no order of their own. */ +function distributionConditionsOf(columns: readonly ColumnRecipe[]): string[] { + const conditions = new Set(); + for (const column of columns) { + const condition = column.getSpec().domain?.[FacsBin.ConditionDomain]; + if (condition !== undefined) conditions.add(condition); + } + return [...conditions].sort(); } /** - * The metadata options minus what the other two roles hold. The distinctness refusal stays in - * `args`; this only keeps the user away from it. A role never hides its own current pick, or - * the control renders empty. + * One scores table for one grain. A nucleotide run emits two column families on two axes, told + * apart by the `pl7.app/alphabet` domain. `undefined` where the run produced none. */ -function narrowTo( - ctx: { - data: BlockData; - resultPool: unknown; - outputs?: unknown; - } & { data: BlockData }, - role: "conditionColumnRef" | "gateColumnRef" | "sortFractionColumnRef", -): { label: string; value: SUniversalPColumnId }[] | undefined { - const all = metadataColumnsOf(ctx); +function buildScoresTable(ctx: BlockRenderCtx, alphabet: string) { + const all = getOutputColumns(ctx, ctx.outputs?.resolve("scoresPf")); if (!all) return undefined; + // The alphabet is the only thing separating the two families: they share every name and + // condition domain, and mixing them joins protein scores to nothing. + const own = all + .filter({ include: { domain: { [AlphabetDomain]: [exact(alphabet)] } } }) + .getColumns() + .map((column) => ({ column, spec: column.getSpec() })); + if (own.length === 0) return undefined; - const roles = ["conditionColumnRef", "gateColumnRef", "sortFractionColumnRef"] as const; - const taken = new Set( - roles - .filter((other) => other !== role) - .map((other) => ctx.data[other]) - .filter((ref): ref is SUniversalPColumnId => ref !== undefined), - ); + // Unordered gates produce no `gateRankMean`, so the enrichment carries the anchor there. + // Both are keyed on the variant axes, so the key shape below is the same either way. + const pickAnchor = (name: string) => + own + .filter((column) => column.spec.name === name) + .sort((a, b) => + ( + (a.spec.domain?.[FacsBin.ConditionDomain] ?? "") + + "\0" + + (a.spec.domain?.[FacsBin.GateDomain] ?? "") + ).localeCompare( + (b.spec.domain?.[FacsBin.ConditionDomain] ?? "") + + "\0" + + (b.spec.domain?.[FacsBin.GateDomain] ?? ""), + ), + )[0]; + const anchor = pickAnchor(FacsBin.GateRankMean) ?? pickAnchor(FacsBin.GateEnrichment); + if (!anchor) return undefined; - return all - .filter((column) => !taken.has(column.value)) - .map((column) => ({ label: column.label, value: column.value })); -} + // Primary columns, so they are always shown and never compete with a pool namesake. + // + // Filtered to the anchor's own key shape: `scoresPf` also carries the per-position baseline + // on `[parentId, position]`, and passing that in fails the whole table with + // `discoverColumns failed`. Compared on axis names, so a new differently-keyed column does + // not need this list updated. + const anchorKey = anchor.spec.axesSpec.map((axis) => axis.name).join("\0"); + const primaryColumns = own + .filter((column) => column.spec.axesSpec.map((axis) => axis.name).join("\0") === anchorKey) + .map(({ column }) => column); -/** The same query `metadataColumns` runs; the runtime memoizes it across both. */ -function metadataColumnsOf(ctx: { - data: BlockData; - resultPool: unknown; -}): { value: SUniversalPColumnId; label: string }[] | undefined { - const anchor = ctx.data.abundanceRef; - if (!anchor) return undefined; + // Everything else the variant axis reaches. + // + // The WHOLE `pl7.app/facsBin/` namespace is excluded, this block's own included. A second + // sort-seq block's columns are identical in everything discovery matches on, and a selector + // can require a domain value but cannot refuse one — so there is no selector admitting ours + // and refusing a sibling's. This also drops the duplicate our own `exports.pf` creates. + const { primary, secondary } = discoverTableColumnSnaphots(ctx, { + anchors: { main: anchor.spec }, + // Strict axis equality. "related" reaches every column the variant axis participates in, + // giving a row per variant per position per gate. + selector: { + mode: "exact", + exclude: [{ name: [{ type: "regex", value: "^pl7\\.app/facsBin/.*$" }] }], + }, + }); - const pool = ctx.resultPool as { - resolveAnchorCtx: ( - a: Record, - ) => { deriveS: (spec: unknown) => SUniversalPColumnId } | undefined; - getAnchoredPColumns: ( - a: Record, - s: unknown[], - ) => { id: string; spec: { name: string; annotations?: Record } }[] | undefined; - }; - - const anchorCtx = pool.resolveAnchorCtx({ main: anchor }); - if (!anchorCtx) return undefined; - const columns = pool.getAnchoredPColumns({ main: anchor }, [metadataSelector]); - if (!columns) return undefined; - - return columns.map((column) => ({ - value: anchorCtx.deriveS(column.spec), - label: column.spec.annotations?.[Annotation.Label] ?? column.spec.name, - })); + return createPlDataTableV3(ctx, { + primaryColumns, + columns: [...primary, ...secondary], + tableState: + alphabet === Alphabet.Nucleotide ? ctx.data.ntResultsTableState : ctx.data.resultsTableState, + displayOptions: { + /** + * First match wins, and an unmatched column keeps its own annotation — upstream sets + * `default` on nearly everything, so the catch-all last is required. + * + * `optional` rather than `hidden`: they stay one click away in the column picker. + */ + visibility: [ + { match: { name: exact(FacsBin.GateRankMean) }, visibility: "default" }, + { match: { name: exact(FacsBin.BinScore) }, visibility: "default" }, + { match: { name: exact(FacsBin.GateEnrichment) }, visibility: "default" }, + { match: { name: exact(PColumnName.VariantLabel) }, visibility: "default" }, + { match: { name: exact(PColumnName.Mutations) }, visibility: "default" }, + { match: { name: ".*" }, visibility: "optional" }, + ], + }, + }); } - -export type BlockOutputs = InferOutputsType; diff --git a/model/src/metadata.ts b/model/src/metadata.ts new file mode 100644 index 0000000..6a21576 --- /dev/null +++ b/model/src/metadata.ts @@ -0,0 +1,126 @@ +import type { ColumnUniversalId, ColumnValueOption, RenderCtxBase } from "@platforma-sdk/model"; +import { + deriveColumnOptions, + deriveColumnValueOptions, + readColumnValues, +} from "@platforma-sdk/model"; +import type { ColumnPickerOption } from "./column_access"; +import { axisSelector, findColumn, resultPool } from "./column_access"; +import { metadataSelector, sampleLabelSelector } from "./columns"; +import type { BlockData } from "./types"; + +/** The three roles a sample-metadata column is picked for. */ +export type MetadataRole = "conditionColumnRef" | "gateColumnRef" | "sortFractionColumnRef"; + +/** The column picked for each role. */ +export type MetadataPicks = Pick; + +/** The values of one sample-metadata column, as options of the value pickers. */ +export type MetadataColumnValues = { + column: ColumnUniversalId; + options: ColumnValueOption[]; +}; + +/** + * Sample-metadata columns of upstream blocks whose only axis is the dataset's sample axis + * (axis 0), as options of the three role pickers. Every option id is a result-pool leaf, so it + * names the block that produced the column. `undefined` only while the result pool is still + * resolving; a dataset that is gone from a settled pool offers no options. + */ +export function getMetadataOptions( + ctx: RenderCtxBase, + abundanceRef: ColumnUniversalId, +): ColumnPickerOption[] | undefined { + const sampleAxis = findColumn(ctx, abundanceRef)?.getSpec().axesSpec[0]; + if (sampleAxis === undefined) return resultPool(ctx).isFinal() ? [] : undefined; + + const columns = resultPool(ctx).filter({ + include: { ...metadataSelector, axes: [axisSelector(sampleAxis)], partialAxesMatch: false }, + }); + return deriveColumnOptions(columns).map(({ id, label }) => ({ value: id, label })); +} + +/** + * The metadata options minus what the other two roles hold. The distinctness refusal stays in + * `args`; this only keeps the user away from it. A role keeps its own pick among the options + * while the column is offered, or the control renders empty. + */ +export function narrowToRole( + options: ColumnPickerOption[], + picks: MetadataPicks, + role: MetadataRole, +): ColumnPickerOption[] { + const taken = new Set( + METADATA_ROLES.filter((other) => other !== role).map((other) => picks[other]), + ); + return options.filter((option) => !taken.has(option.value)); +} + +/** + * The values of every offered sample-metadata column and of the picked condition and gate + * columns, each value a column value id naming its column, and through it the block that + * produced the value. + * + * Every offered column rather than the picked ones: the gate order is seeded from the gate + * column's values in the same gesture as the pick, so they must be in hand before it. + * + * `undefined` while the metadata options are. A column whose values cannot be read now — still + * resolving, not computed, gone, or not stored inline — offers no values, so its picks show as + * not available. + */ +export function getMetadataValues( + ctx: RenderCtxBase, + abundanceRef: ColumnUniversalId, + picks: MetadataPicks, +): MetadataColumnValues[] | undefined { + const options = getMetadataOptions(ctx, abundanceRef); + if (options === undefined) return undefined; + + const columns = new Set(options.map((option) => option.value)); + for (const picked of [picks.conditionColumnRef, picks.gateColumnRef]) { + if (picked !== undefined) columns.add(picked); + } + return [...columns].map((column) => ({ column, options: readValueOptions(ctx, column) })); +} + +/** + * Sample names by sample id, read off the label column of the dataset's sample axis. + * `undefined` while the dataset or its label column is not known or not readable. + */ +export function getSampleLabels( + ctx: RenderCtxBase, + abundanceRef: ColumnUniversalId, +): Record | undefined { + const sampleAxis = findColumn(ctx, abundanceRef)?.getSpec().axesSpec[0]; + if (sampleAxis === undefined) return undefined; + + const [column] = resultPool(ctx) + .filter({ + include: { + ...sampleLabelSelector, + axes: [axisSelector(sampleAxis)], + partialAxesMatch: false, + }, + }) + .getColumns(); + if (column === undefined) return undefined; + + const entries = readColumnValues(column); + if (entries === undefined) return undefined; + // One axis, so the key's only entry is the sample id. + return Object.fromEntries(entries.map((entry) => [String(entry.key[0]), String(entry.value)])); +} + +// Internals + +const METADATA_ROLES: readonly MetadataRole[] = [ + "conditionColumnRef", + "gateColumnRef", + "sortFractionColumnRef", +]; + +function readValueOptions(ctx: RenderCtxBase, columnRef: ColumnUniversalId): ColumnValueOption[] { + const column = findColumn(ctx, columnRef); + const entries = column === undefined ? undefined : readColumnValues(column); + return deriveColumnValueOptions(entries ?? []); +} diff --git a/model/src/stored_data.ts b/model/src/stored_data.ts new file mode 100644 index 0000000..c070892 --- /dev/null +++ b/model/src/stored_data.ts @@ -0,0 +1,34 @@ +import type { GraphMakerState } from "@milaboratories/graph-maker"; +import type { PlDataTableStateV2, PlRef } from "@platforma-sdk/model"; +import type { BaselineOption } from "./types"; + +/** + * Data as stored at `Ver_2026_09_21`: the dataset as a ref to an upstream output, the condition, + * gate and sort-fraction columns as ids anchored against the dataset, the picked gates, excluded + * conditions and input gate as plain values, and the distinct values of the gate and condition + * columns snapshotted when they were picked. + */ +export type BlockDataV2 = { + abundanceRef?: PlRef; + filterRef?: PlRef; + conditionColumnRef?: string; + gateColumnRef?: string; + gateOrder: string[]; + excludedConditions: string[]; + readFloor?: number; + sortFractionColumnRef?: string; + gatesOrdered?: boolean; + inputGate?: string; + baseline?: BaselineOption; + baselineSequence?: string; + gateValues: string[]; + gateColumnLabel?: string; + conditionValues: string[]; + customBlockLabel: string; + resultsTableState: PlDataTableStateV2; + ntResultsTableState: PlDataTableStateV2; + distributionGraphStates: Record; +}; + +/** Data as stored at `Ver_2026_08_07`: the same shape, before the nucleotide table had a state. */ +export type BlockDataV1 = Omit; diff --git a/model/src/types.ts b/model/src/types.ts index 3fcbcaf..37e1252 100644 --- a/model/src/types.ts +++ b/model/src/types.ts @@ -1,5 +1,5 @@ import type { GraphMakerState } from "@milaboratories/graph-maker"; -import type { PlDataTableStateV2, PlRef, SUniversalPColumnId } from "@platforma-sdk/model"; +import type { ColumnUniversalId, ColumnValueId, PlDataTableStateV2 } from "@platforma-sdk/model"; /** * One word for what the run did, **derived** by the computation from whether an input was @@ -12,28 +12,33 @@ export type BaselineOption = "wild-type" | "synonymous" | "sequence"; /** * What the workflow consumes. Fields 8-11 are omitted rather than defaulted on a gate-ranking - * run, so an existing block's args keep their exact bytes. + * run, so the args JSON carries only what the run uses. + * + * Every column is a result-pool column id, naming the block that produced it. Every picked value + * is a column value id of the column it was picked from; the workflow reads the plain values + * back out at its entry. */ export type BlockArgs = { /** 1. The dataset selection that anchors every other input. */ - abundanceRef: PlRef; + abundanceRef: ColumnUniversalId; /** 2. A per-sample metadata column, picked from the option list. */ - conditionColumnRef: SUniversalPColumnId; + conditionColumnRef: ColumnUniversalId; /** 3. A per-sample metadata column, picked for the other role. */ - gateColumnRef: SUniversalPColumnId; + gateColumnRef: ColumnUniversalId; /** - * 4. A rank per selected gate, contiguous from 1, derived from `gateOrder` by position. + * 4. A rank per selected gate, contiguous from 1, derived from `gateOrder` by position. Keyed + * by the gate's column value id, so each key still names the gate column it was picked from. * * The key set doubles as the run's gate scope: a gate-column value absent from it takes no * part in the run, which is the ordinary case rather than an incomplete configuration. */ - gateRanks: Record; + gateRanks: Record; /** 5. Absent (empty) means every distinct value of the condition column is a condition. */ - excludedConditions: string[]; + excludedConditions: ColumnValueId[]; /** 6. Absent means **no floor is applied** — not a floor of zero, and not a guess. */ readFloor?: number; /** 7. Absent means the score is computed **uncorrected**, declared on every value. */ - sortFractionColumnRef?: SUniversalPColumnId; + sortFractionColumnRef?: ColumnUniversalId; /** * 8. Whether the gates lie along a binding axis. Absent means they do. False drops the rank @@ -45,33 +50,35 @@ export type BlockArgs = { * for the enrichment. Never a key of `gateRanks` — a gate that referenced itself would give * exactly 1 everywhere. */ - inputGate?: string; + inputGate?: ColumnValueId; /** 10. Absent means report no baseline, which is an answer and not an unset field. */ baseline?: BaselineOption; /** 11. The variant key the `sequence` baseline names. Set only with that option. */ baselineSequence?: string; - /** The subset column's canonical id. Absent without a filter, so unfiltered args are unchanged. */ - inputFilter?: string; + /** The subset column's result-pool id. Absent without a filter, so unfiltered args are unchanged. */ + inputFilter?: ColumnUniversalId; }; /** What the user edits. Projected to `BlockArgs` by the args lambda; view state never crosses. */ export type BlockData = { // --- The seven arguments, in argument order ------------------------------ - abundanceRef?: PlRef; + abundanceRef?: ColumnUniversalId; /** Subset column picked with the dataset in PlDatasetSelector (e.g. a Repertoire Labeling label). */ - filterRef?: PlRef; - conditionColumnRef?: SUniversalPColumnId; - gateColumnRef?: SUniversalPColumnId; + filterRef?: ColumnUniversalId; + conditionColumnRef?: ColumnUniversalId; + gateColumnRef?: ColumnUniversalId; /** - * The selected gates in declared order, weakest binder first. A list, not a rank map, so - * position IS the rank and a duplicate rank is unrepresentable. Seeded from the column then - * narrowed by the user; removing a gate takes it out of the run. + * The selected gates in declared order, weakest binder first, as column value ids of the gate + * column. A list, not a rank map, so position IS the rank and a duplicate rank is + * unrepresentable. Seeded from the column then narrowed by the user; removing a gate takes it + * out of the run. A gate the column no longer carries stays and is shown as not available. */ - gateOrder: string[]; - excludedConditions: string[]; + gateOrder: ColumnValueId[]; + /** Column value ids of the condition column. */ + excludedConditions: ColumnValueId[]; /** `undefined` applies no floor at all, and is the normal first run. */ readFloor?: number; - sortFractionColumnRef?: SUniversalPColumnId; + sortFractionColumnRef?: ColumnUniversalId; // --- The two facts, plus the baseline ------------------------------------- // @@ -79,27 +86,19 @@ export type BlockData = { // metrics on. There is no mode. /** `undefined` means ordered, which is the ordinary case. */ gatesOrdered?: boolean; - /** The gate value serving as the unsorted reference. Only meaningful in enrichment mode. */ - inputGate?: string; + /** + * The gate value serving as the unsorted reference, as a column value id of the gate column. + * Only meaningful in enrichment mode. + */ + inputGate?: ColumnValueId; /** `undefined` reports no baseline. */ baseline?: BaselineOption; /** The variant key for the `sequence` baseline. */ baselineSequence?: string; - // --- Snapshots of the picked columns' distinct values --------------------- - // - // The args lambda sees only `data`, but two validations need a picked column's VALUES, which - // only a PFrame fetch produces — so the UI writes ref and values in one gesture. - // - // Allowed to go stale: keeping it fresh means a watcher on an output writing back to shared - // data, and the computation re-derives the real values anyway. - /** Distinct values of the picked gate column, at the moment it was picked. */ - gateValues: string[]; /** Snapshotted so the subtitle stays a pure function of `data`: only the option list knows a * column's label, and that list is an output. */ gateColumnLabel?: string; - /** Distinct values of the picked condition column, at the moment it was picked. */ - conditionValues: string[]; /** The user's override for the block subtitle. Empty means use the derived label. */ customBlockLabel: string; diff --git a/ui/src/components/PageHeader.vue b/ui/src/components/PageHeader.vue index d78d758..d2dd19c 100644 --- a/ui/src/components/PageHeader.vue +++ b/ui/src/components/PageHeader.vue @@ -11,7 +11,7 @@ * button, one drawer, one place. Mounting it per page gave three `PlSlideModal`s racing * over one shared open flag. */ -import { PlBtnGhost, PlMaskIcon24 } from "@platforma-sdk/ui-vue"; +import { PlBtnGhost, PlIcon24 } from "@platforma-sdk/ui-vue"; import { useApp } from "../app"; import { useSettingsDrawer } from "../useSettingsDrawer"; import SettingsDrawer from "./SettingsDrawer.vue"; @@ -23,7 +23,7 @@ const { isOpen } = useSettingsDrawer(useApp()); Settings diff --git a/ui/src/components/RunStatistics.vue b/ui/src/components/RunStatistics.vue index 46a8fac..442a243 100644 --- a/ui/src/components/RunStatistics.vue +++ b/ui/src/components/RunStatistics.vue @@ -5,15 +5,13 @@ * `@click.stop` is required: the dialog closes on an outside click, and the opening click would * bubble up and be read as outside. Open state is a local ref — in `data` it would be shared. */ -import { getSingleColumnData, type PObjectId } from "@platforma-sdk/model"; import { PlAgOverlayLoading, PlAlert, PlBtnGhost, PlDialogModal, PlLogView, - PlMaskIcon24, - useWatchFetch, + PlIcon24, } from "@platforma-sdk/ui-vue"; import { computed, ref } from "vue"; import { useApp } from "../app"; @@ -76,32 +74,9 @@ const inputDepths = computed(() => { })); }); -/** `sampleId` -> sample name. One axis, so `axesData[0]` lines up with `data` by position. */ -const sampleLabels = useWatchFetch( - () => ({ - pframe: app.model.outputs.sampleLabelPframe, - columnId: app.model.outputs.sampleLabelColumnId, - }), - async ({ pframe, columnId }) => { - const out: Record = {}; - if (!pframe || !columnId) return out; - - const column = await getSingleColumnData(pframe, columnId as PObjectId); - const ids = Object.values(column?.axesData ?? {})[0] ?? []; - const labels = column?.data ?? []; - for (const [index, id] of ids.entries()) { - const label = labels[index]; - if (id !== null && id !== undefined && label !== null && label !== undefined) { - out[String(id)] = String(label); - } - } - return out; - }, -); - /** The sample's name, falling back to the raw id. */ function labelFor(sampleId: string): string { - return sampleLabels.value?.[sampleId] ?? sampleId; + return app.model.outputs.sampleLabels?.[sampleId] ?? sampleId; } /** @@ -163,7 +138,7 @@ function binScoreCell(entry: { Statistics diff --git a/ui/src/components/SettingsDrawer.vue b/ui/src/components/SettingsDrawer.vue index 91e321a..4ffe948 100644 --- a/ui/src/components/SettingsDrawer.vue +++ b/ui/src/components/SettingsDrawer.vue @@ -3,17 +3,23 @@ * One control per argument. Two things are easy to "fix" wrongly: * * 1. The read-count floor is clearable — cleared IS the answer, and the normal first run. - * 2. Column values are snapshotted on the user's gesture, never by a watcher: a watcher on an + * 2. The gate order is seeded on the user's gesture, never by a watcher: a watcher on an * output writing to `data` is the hairpin, and two clients would race. + * + * Picked gates, the input and excluded conditions are column value ids of their columns. One no + * longer among the column's values stays picked and is shown as not available, with the reason + * in a tooltip; only picking another column clears them. */ -import { BASELINE_AVAILABLE } from "@platforma-open/milaboratories.sort-seq-analysis.model"; -import type { DatasetSelection, SUniversalPColumnId } from "@platforma-sdk/model"; import { - createDatasetSelection, - createPrimaryRef, - getSingleColumnData, - plRefsEqual, - type PObjectId, + BASELINE_AVAILABLE, + fromAbundanceSelection, + toAbundanceSelection, +} from "@platforma-open/milaboratories.sort-seq-analysis.model"; +import type { + ColumnUniversalId, + ColumnValueId, + ColumnValueOption, + DatasetSelection, } from "@platforma-sdk/model"; import { PlAccordion, @@ -25,11 +31,11 @@ import { PlElementList, PlDatasetSelector, PlDropdownMulti, - PlMaskIcon24, + PlIcon24, PlNumberField, PlSlideModal, PlTooltip, - useWatchFetch, + PlValueLabel, } from "@platforma-sdk/ui-vue"; import { computed, ref } from "vue"; import { useApp } from "../app"; @@ -44,39 +50,32 @@ const armsOpen = ref(true); const isOpen = defineModel({ required: true }); /** - * Distinct values of EVERY metadata column, keyed by ref rather than role: the snapshot is - * written in the same gesture as the pick, so the values must already be in hand. Fetching only - * picked columns lags by a round trip and the gate-order control never appears. + * Values of a metadata column, as the model read them. `undefined` while they are not known, so + * picks are not marked as not available before the model has caught up. */ -const valuesByRef = useWatchFetch( - () => ({ - pframe: app.model.outputs.metadataColumnsPframe, - columns: app.model.outputs.metadataColumns, - }), - async ({ pframe, columns }) => { - const out: Record = {}; - if (!pframe || !columns) return out; - - for (const column of columns) { - const data = await getSingleColumnData(pframe, column.objectId as PObjectId); - const raw: unknown[] = data?.data ?? []; - const values = raw.filter((v): v is string | number => v !== null && v !== undefined); - out[column.value] = [...new Set(values.map((v) => String(v)))].sort(); - } - return out; - }, -); +function valueOptionsOf(column: ColumnUniversalId | undefined): ColumnValueOption[] | undefined { + if (column === undefined) return undefined; + return app.model.outputs.metadataValues?.find((entry) => entry.column === column)?.options; +} -function valuesFor(ref: SUniversalPColumnId | undefined): string[] { - if (!ref) return []; - return valuesByRef.value?.[ref] ?? []; +/** The values of a column, in the order the model offers them. */ +function valuesOf(column: ColumnUniversalId | undefined): ColumnValueId[] { + return (valueOptionsOf(column) ?? []).map((option) => option.value); } -const conditionValueOptions = computed(() => - valuesFor(app.model.data.conditionColumnRef).map((value) => ({ value, label: value })), -); +const conditionValueOptions = computed(() => valueOptionsOf(app.model.data.conditionColumnRef)); + +/** + * Every condition excluded leaves nothing to score: the run would produce no results, which + * reads like a failed run. + */ +const everyConditionExcluded = computed(() => { + const options = conditionValueOptions.value; + if (options === undefined || options.length === 0) return false; + return options.every((option) => app.model.data.excludedConditions.includes(option.value)); +}); -const gateValues = computed(() => app.model.data.gateValues); +const gateValueOptions = computed(() => valueOptionsOf(app.model.data.gateColumnRef)); /** `undefined` means ordered, which is the ordinary case and every block made before this. */ const gatesOrdered = computed({ @@ -91,27 +90,30 @@ const gatesOrdered = computed({ * the control offers what the gate-order list has had removed. */ const inputGateOptions = computed(() => - gateValues.value - .filter((value) => !app.model.data.gateOrder.includes(value)) - .map((value) => ({ label: value, value })), + gateValueOptions.value?.filter((option) => !app.model.data.gateOrder.includes(option.value)), ); /** * What `setGateColumn` seeds, minus the input gate — the input can never be a ranked gate, so - * removing it is not a modification to offer undoing. + * removing it is not a modification to offer undoing. `undefined` while the gate column's values + * are not known, so a reset cannot wipe the order before they arrive. */ const defaultGateOrder = computed(() => - gateValues.value.filter((value) => value !== app.model.data.inputGate), + gateValueOptions.value + ?.map((option) => option.value) + .filter((value) => value !== app.model.data.inputGate), ); const gateOrderModified = computed(() => { const current = app.model.data.gateOrder; const base = defaultGateOrder.value; + if (base === undefined) return false; return current.length !== base.length || current.some((value, i) => value !== base[i]); }); function resetGateOrder() { - app.model.data.gateOrder = [...defaultGateOrder.value]; + const base = defaultGateOrder.value; + if (base !== undefined) app.model.data.gateOrder = [...base]; } /** `undefined` before a dataset is picked, so an unknown grain never hides a valid option. */ @@ -149,29 +151,22 @@ const baselineAvailableHere = computed( const abundanceSelection = computed({ get: () => { const { abundanceRef, filterRef } = app.model.data; - if (abundanceRef === undefined) return undefined; - return createDatasetSelection(createPrimaryRef(abundanceRef, filterRef)); + return toAbundanceSelection({ abundanceRef, filterRef }); }, set: (selection) => { - const ref = selection?.primary.column; - const current = app.model.data.abundanceRef; - const sameDataset = - ref === undefined - ? current === undefined - : current !== undefined && plRefsEqual(ref, current, true); - if (!sameDataset) setAbundance(ref); - app.model.data.filterRef = selection?.primary.filter; + const { abundanceRef, filterRef } = fromAbundanceSelection(selection); + if (abundanceRef !== app.model.data.abundanceRef) setAbundance(abundanceRef); + app.model.data.filterRef = filterRef; }, }); -function setAbundance(ref: typeof app.model.data.abundanceRef) { - // A stored anchored id is meaningless against a different anchor. +function setAbundance(ref: ColumnUniversalId | undefined) { + // The metadata columns are picked among those on the dataset's sample axis, so another + // dataset's picks do not carry over. app.model.data.abundanceRef = ref; app.model.data.conditionColumnRef = undefined; app.model.data.gateColumnRef = undefined; app.model.data.sortFractionColumnRef = undefined; - app.model.data.conditionValues = []; - app.model.data.gateValues = []; app.model.data.gateColumnLabel = undefined; app.model.data.gateOrder = []; app.model.data.excludedConditions = []; @@ -183,22 +178,20 @@ function setAbundance(ref: typeof app.model.data.abundanceRef) { app.model.data.baselineSequence = undefined; } -function setConditionColumn(ref: SUniversalPColumnId | undefined) { - // Ref and snapshot in one gesture. The snapshot may go stale; re-picking refreshes it. +function setConditionColumn(ref: ColumnUniversalId | undefined) { + // The exclusions are values of the old column. app.model.data.conditionColumnRef = ref; - app.model.data.conditionValues = valuesFor(ref); app.model.data.excludedConditions = []; } -function setGateColumn(ref: SUniversalPColumnId | undefined) { +function setGateColumn(ref: ColumnUniversalId | undefined) { app.model.data.gateColumnRef = ref; - app.model.data.gateValues = valuesFor(ref); // The label too: only the option list knows it, and the subtitle derives from `data` alone. app.model.data.gateColumnLabel = app.model.outputs.gateOptions?.find( (option) => option.value === ref, )?.label; // Seed the order from the column; a previous ordering is meaningless against a new column. - app.model.data.gateOrder = valuesFor(ref); + app.model.data.gateOrder = valuesOf(ref); // Same gesture, same reason: the old input was a value of the old column. app.model.data.inputGate = undefined; } @@ -224,7 +217,7 @@ function setGateColumn(ref: SUniversalPColumnId | undefined) { - + Reset to default @@ -288,7 +283,7 @@ function setGateColumn(ref: SUniversalPColumnId | undefined) { + + + Every level is excluded, so the run would produce no results. Keep at least one. + @@ -343,7 +342,7 @@ function setGateColumn(ref: SUniversalPColumnId | undefined) { diff --git a/ui/src/pages/DistributionPage.vue b/ui/src/pages/DistributionPage.vue index ff0f369..dd46c60 100644 --- a/ui/src/pages/DistributionPage.vue +++ b/ui/src/pages/DistributionPage.vue @@ -19,6 +19,7 @@ import { distributionPlotTitle, } from "@platforma-open/milaboratories.sort-seq-analysis.model"; import type { AxisSpec } from "@platforma-sdk/model"; +import { columnValueLabel } from "@platforma-sdk/model"; import { PlAlert } from "@platforma-sdk/ui-vue"; import { computed, watch } from "vue"; import { useApp } from "../app"; @@ -88,6 +89,9 @@ const gateAxis = computed((): AxisSpec | undefined => { * Seeded once, so a user reordering gates in the chart keeps their choice; a gate the snapshot * missed is appended by graph-maker rather than lost. Watching the route and `data` rather * than an output keeps this clear of the hairpin. + * + * The gate axis carries the gate values as the run wrote them, as text; the order holds them as + * column value ids. */ watch( [condition, gateAxis, () => app.model.data.gateOrder], @@ -106,7 +110,7 @@ watch( ...state, dataBindAes: { ...state.dataBindAes, - [key]: createDefaultMapping([...gateOrder], "light"), + [key]: createDefaultMapping(gateOrder.map(columnValueLabel), "light"), }, }; }, diff --git a/workflow/src/main.tpl.tengo b/workflow/src/main.tpl.tengo index 2c61bc8..a1b9d7a 100644 --- a/workflow/src/main.tpl.tengo +++ b/workflow/src/main.tpl.tengo @@ -21,6 +21,8 @@ assets := import("@platforma-sdk/workflow-tengo:assets") pframes := import("@platforma-sdk/workflow-tengo:pframes") render := import("@platforma-sdk/workflow-tengo:render") canonical := import("@platforma-sdk/workflow-tengo:canonical") +columnValue := import("@platforma-sdk/workflow-tengo:workflow.column-value") +ll := import("@platforma-sdk/workflow-tengo:ll") json := import("json") scoreSw := assets.importSoftware("@platforma-open/milaboratories.sort-seq-analysis.software:main") @@ -43,18 +45,34 @@ DISTRIBUTION_FILE_REGEX := "^dist_.*\\.tsv$" // `score_` name. BASELINE_FILE_REGEX := "^baseline_.*\\.tsv$" +// The ref a result-pool column id names: the block and output it was taken from. +columnIdToRef := func(id) { + ref := json.decode(id) + if !is_map(ref) || ref.__isRef != true { + ll.panic("expected a result-pool column id, got %v", id) + } + return ref +} + +// The plain value a column value id carries, as text: the computation compares gate and +// condition values with the cells of the reads table, which carries them as text, numeric +// values too. +pickedValue := func(id) { + return string(columnValue.valueOf(id)) +} + wf.prepare(func(args) { bb := wf.createPBundleBuilder() bb.ignoreMissingDomains() // The anchor: every other input resolves against it, so columns cannot be mixed across runs. - // - // It MUST be named "main" — the model's stored anchored ids embed `{"anchor":"main"}`, and - // any other name fails with "anchor 'main' not found". Part of the id's contract. - bb.addAnchor("main", args.abundanceRef) + // It arrives as a result-pool column id; the anchored queries below bind their axes to it + // by the name "main". + bb.addAnchor("main", columnIdToRef(args.abundanceRef)) // One predicate, one option list, three independent picks: no spec predicate can tell which - // role a metadata column plays, so the user assigns them. + // role a metadata column plays, so the user assigns them. Each arrives as a result-pool + // column id. bb.addSingle(args.conditionColumnRef, "condition") bb.addSingle(args.gateColumnRef, "gate") if !is_undefined(args.sortFractionColumnRef) { @@ -110,7 +128,7 @@ wf.prepare(func(args) { // Optional subset column picked alongside the dataset (PlDatasetSelector) if !is_undefined(args.inputFilter) { - bb.addRef(json.decode(args.inputFilter)) + bb.addRef(columnIdToRef(args.inputFilter)) } // Full await (spec and data) delays this block's spec emission, but the body exports these @@ -122,6 +140,18 @@ wf.body(func(args) { blockId := wf.blockId().getDataAsJson() columns := args.columns + // Picked gates, excluded conditions and the input arrive as column value ids; the + // computation takes the plain values they carry. `gateRanks` is keyed by the ids. + gateRanks := {} + for id, rank in args.gateRanks { + gateRanks[pickedValue(id)] = rank + } + excludedConditions := [] + for id in args.excludedConditions { + excludedConditions = append(excludedConditions, pickedValue(id)) + } + inputGate := is_undefined(args.inputGate) ? undefined : pickedValue(args.inputGate) + abundanceSpec := columns.getSpec("main") sampleAxisSpec := abundanceSpec.axesSpec[0] variantAxisSpec := abundanceSpec.axesSpec[1] @@ -132,7 +162,7 @@ wf.body(func(args) { // filter so downstream labels name it. filterColumn := undefined if !is_undefined(args.inputFilter) { - f := columns.getColumn(json.decode(args.inputFilter)) + f := columns.getColumn(columnIdToRef(args.inputFilter)) filterColumn = { spec: f.spec, data: f.data } } @@ -289,8 +319,8 @@ wf.body(func(args) { // Omitted rather than nulled; the computation reads an absent key as the behaviour. paramsPayload := { - gateRanks: args.gateRanks, - excludedConditions: args.excludedConditions + gateRanks: gateRanks, + excludedConditions: excludedConditions } if !is_undefined(args.readFloor) { paramsPayload.readFloor = args.readFloor @@ -299,8 +329,8 @@ wf.body(func(args) { paramsPayload.sortFractionColumn = SORT_FRACTION_HEADER } // Naming an input is what asks for the enrichment. There is no mode to carry. - if !is_undefined(args.inputGate) { - paramsPayload.inputGate = args.inputGate + if !is_undefined(inputGate) { + paramsPayload.inputGate = inputGate } // Absent means ordered, which is every document written before the flag existed. if !is_undefined(args.gatesOrdered) { From 901d08cad3bf0911cf76ef8cac5a6032a3426a7c Mon Sep 17 00:00:00 2001 From: Alexandr Date: Wed, 21 Oct 2026 14:05:46 +0200 Subject: [PATCH 02/17] MILAB-7194: keep the gate and condition value snapshots and the checks that use them --- .changeset/column-value-refs.md | 6 ++-- kind/src/index.ts | 37 ++++++++++++++++------- model/src/dataModel.ts | 17 +++++++---- model/src/index.ts | 43 ++++++++++++++++++++------- model/src/metadata.ts | 4 +-- model/src/types.ts | 18 ++++++++++++ ui/src/components/SettingsDrawer.vue | 44 ++++++++++++---------------- 7 files changed, 112 insertions(+), 57 deletions(-) diff --git a/.changeset/column-value-refs.md b/.changeset/column-value-refs.md index 0aadb6e..b73da7c 100644 --- a/.changeset/column-value-refs.md +++ b/.changeset/column-value-refs.md @@ -6,6 +6,6 @@ "@platforma-open/milaboratories.sort-seq-analysis.workflow": major --- -Columns are stored by their result-pool column ids: the dataset and the condition, gate and sort-fraction columns. The gates of the gate order, the unsorted input and the excluded conditions are stored as column value references of the gate and condition columns, so the block that produced the metadata knows which of its values this block uses; the ranks the workflow receives are keyed by the same references. The model finds columns, builds the options of every column and value picker and reads the sample names through the column collection API instead of the deprecated result pool API, the values are read by the model instead of fetched by the settings panel, and the workflow takes every column through a column bundle. The block no longer keeps snapshots of the gate and condition columns' values. -Opening a project created before this change keeps its dataset, and clears its condition, gate and sort-fraction columns, the gate order, the unsorted input and the excluded conditions, since they were stored by ids anchored to the dataset and as plain values, which name no producing block; they have to be picked again before the block runs. The initialization params of the kind carry the same ids and references and no longer carry the value snapshots, so templates made for an earlier version of the kind cannot be applied. -Gates, the input and excluded conditions that are no longer among the values of their column stay selected and are marked as not available instead of being removed silently, with a tooltip naming the block that was to provide them, as a link to it, and what went wrong. Picking another gate or condition column still resets the values picked in it. Excluding every condition is shown as a warning in the settings instead of disabling the run. +Columns are stored by their result-pool column ids: the dataset and the condition, gate and sort-fraction columns. The gates of the gate order, the unsorted input and the excluded conditions are stored as column value references of the gate and condition columns, so the block that produced the metadata knows which of its values this block uses; the ranks the workflow receives are keyed by the same references. The model finds columns, builds the options of every column and value picker and reads the sample names through the column collection API instead of the deprecated result pool API, the values are read by the model instead of fetched by the settings panel, and the workflow takes every column through a column bundle. The snapshots of the gate and condition columns' values, written when a column is picked, are stored as column value references of that column too. +Opening a project created before this change keeps its dataset, and clears its condition, gate and sort-fraction columns, the gate order, the unsorted input, the excluded conditions and the value snapshots, since they were stored by ids anchored to the dataset and as plain values, which name no producing block; they have to be picked again before the block runs. The initialization params of the kind carry the same ids and references, the value snapshots included, so templates made for an earlier version of the kind cannot be applied. +Gates, the input and excluded conditions that are no longer among the values of their column stay selected and are marked as not available instead of being removed silently, with a tooltip naming the block that was to provide them, as a link to it, and what went wrong. Picking another gate or condition column still resets the values picked in it and rewrites its snapshot. No check that disables the run is removed: a gate column with no values, a gate or an input the gate column does not carry, and every condition excluded still disable it. diff --git a/kind/src/index.ts b/kind/src/index.ts index 2002a57..07c81b3 100644 --- a/kind/src/index.ts +++ b/kind/src/index.ts @@ -12,12 +12,18 @@ import { name, version } from "../package.json" with { type: "json" }; * FACS ladder over library after library pins that once and then only picks the dataset. * * The three columns are result-pool column ids, each naming the block that produced the column. - * The gates of the ladder are column value ids of the gate column: each names the column it was - * picked from, and through it the block that produced the value. A gate the column no longer - * carries stays in the ladder and is shown as not available. + * The gates of the ladder and the two value snapshots are column value ids of their columns: + * each names the column it was picked from, and through it the block that produced the value. * - * `gateColumnLabel` travels with the gate column because the subtitle is a pure function of the - * block's data, and only the column's option knows its label. + * **The three value snapshots are params for a reason that is easy to miss.** `gateValues`, + * `conditionValues` and `gateColumnLabel` are snapshots the UI writes when a column is picked, + * and they look like derived state that a fresh block should rebuild. But the model's + * `settingsIssues` validates `gateOrder` against `gateValues`, so a template carrying a gate + * ladder and an empty snapshot arrives with Run disabled and two complaints; and the only way + * to refill the snapshot from the UI is to re-pick the gate column, which overwrites + * `gateOrder` with every value of the column. The templated ladder would be destroyed by the + * act of making the block runnable. Carrying the snapshots keeps the template usable on + * arrival. * * Left out, and why: * @@ -37,7 +43,9 @@ export type BlockParams = { gateColumnRef?: ColumnUniversalId; sortFractionColumnRef?: ColumnUniversalId; gateOrder?: ColumnValueId[]; + gateValues?: ColumnValueId[]; gateColumnLabel?: string; + conditionValues?: ColumnValueId[]; }; // Identity (`name`/`version`) comes from this package's own `package.json`, so the on-wire @@ -62,22 +70,31 @@ export const kind = defineBlockKind({ * that list in step with the type above. * * The checks stop at the form of a value. That a gate column is not also the condition column, - * that the ladder holds values of the gate column — those are refused by `settingsIssues` in the - * model, where the whole configuration is in view. A parser stricter than the settings drawer - * would make this block export a template its own kind then refuses to apply. + * that `gateOrder` names only values `gateValues` carries — those are refused by + * `settingsIssues` in the model, where the whole configuration is in view. A parser stricter than + * the settings drawer would make this block export a template its own kind then refuses to apply. */ function parseInitializationParams(value: unknown): BlockParams { assertParamsObject(value); - const { conditionColumnRef, gateColumnRef, sortFractionColumnRef, gateOrder, gateColumnLabel } = - value; + const { + conditionColumnRef, + gateColumnRef, + sortFractionColumnRef, + gateOrder, + gateValues, + gateColumnLabel, + conditionValues, + } = value; return { conditionColumnRef: optionalColumnRef(conditionColumnRef, "conditionColumnRef"), gateColumnRef: optionalColumnRef(gateColumnRef, "gateColumnRef"), sortFractionColumnRef: optionalColumnRef(sortFractionColumnRef, "sortFractionColumnRef"), gateOrder: optionalValueList(gateOrder, "gateOrder"), + gateValues: optionalValueList(gateValues, "gateValues"), gateColumnLabel: optionalString(gateColumnLabel, "gateColumnLabel"), + conditionValues: optionalValueList(conditionValues, "conditionValues"), }; } diff --git a/model/src/dataModel.ts b/model/src/dataModel.ts index e0895d5..6480414 100644 --- a/model/src/dataModel.ts +++ b/model/src/dataModel.ts @@ -45,7 +45,9 @@ export const blockDataModel = new DataModelBuilder({ kind }) gateColumnRef: params?.gateColumnRef, sortFractionColumnRef: params?.sortFractionColumnRef, gateOrder: params?.gateOrder ?? [], + gateValues: params?.gateValues ?? [], gateColumnLabel: params?.gateColumnLabel, + conditionValues: params?.conditionValues ?? [], // Not init params — see the kind. The two facts and the baseline are absent rather than // defaulted: an absent input means no enrichment, and an absent order flag means ordered. @@ -64,23 +66,26 @@ export const blockDataModel = new DataModelBuilder({ kind }) * were picked by ids anchored against the dataset and the gates, excluded conditions and input * gate stored as plain values; neither names the block that produced the metadata, so they * cannot become column ids and column value ids and are dropped, to be picked again. The - * snapshots of the gate and condition columns' values are dropped too: the model reads the - * values of the picked columns itself. + * snapshots of the gate and condition columns' values were plain values too and go with their + * columns; the next pick of a column writes its snapshot again. */ function toColumnIds(data: BlockDataV2): BlockData { - const { gateValues: _gateValues, conditionValues: _conditionValues, ...kept } = data; const column = (stored: string | undefined) => (isColumnUniversalId(stored) ? stored : undefined); const value = (picked: string | undefined) => (isColumnValueId(picked) ? picked : undefined); + const conditionColumnRef = column(data.conditionColumnRef); const gateColumnRef = column(data.gateColumnRef); return { - ...kept, + ...data, abundanceRef: data.abundanceRef === undefined ? undefined : toColumnId(data.abundanceRef), filterRef: data.filterRef === undefined ? undefined : toColumnId(data.filterRef), - conditionColumnRef: column(data.conditionColumnRef), + conditionColumnRef, gateColumnRef, sortFractionColumnRef: column(data.sortFractionColumnRef), - // The label names the gate column, so it goes with it. + // The label and the snapshots describe their column, so they go with it. gateColumnLabel: gateColumnRef === undefined ? undefined : data.gateColumnLabel, + gateValues: gateColumnRef === undefined ? [] : data.gateValues.filter(isColumnValueId), + conditionValues: + conditionColumnRef === undefined ? [] : data.conditionValues.filter(isColumnValueId), gateOrder: data.gateOrder.filter(isColumnValueId), excludedConditions: data.excludedConditions.filter(isColumnValueId), inputGate: value(data.inputGate), diff --git a/model/src/index.ts b/model/src/index.ts index 35be8c7..029aa20 100644 --- a/model/src/index.ts +++ b/model/src/index.ts @@ -55,17 +55,21 @@ export function settingsIssues(data: BlockData): string[] { } // The order is a selection, so coverage is deliberately NOT checked: a gate column carrying - // an input or a specificity arm is the ordinary case. Only non-emptiness and that every gate - // was picked from the gate column. A gate the column no longer carries is shown as not - // available in the drawer; `data` does not hold the column's values, so it is not refused - // here, and neither is excluding every condition. + // an input or a specificity arm is the ordinary case. Only non-emptiness and that it names + // nothing outside the column. // // Guarded on the pick so a fresh block does not get two complaints for one unmade choice. const gateColumn = data.gateColumnRef; if (gateColumn !== undefined) { - if (data.gateOrder.length === 0) { + if (data.gateValues.length === 0) { + issues.push("The gate column has no values to rank"); + } else if (data.gateOrder.length === 0) { + issues.push("Keep at least one gate in the order — every gate has been removed"); + } + const unknown = data.gateOrder.filter((value) => !data.gateValues.includes(value)); + if (unknown.length > 0) { issues.push( - "Keep at least one gate in the order — the gate column has none, or every gate has been removed", + `Ordered value(s) the gate column does not carry: ${unknown.map(columnValueLabel).join(", ")}`, ); } const foreign = [...data.gateOrder, ...(data.inputGate === undefined ? [] : [data.inputGate])] @@ -76,6 +80,15 @@ export function settingsIssues(data: BlockData): string[] { } } + // Refused rather than producing nothing: an empty result is indistinguishable from a + // failed run. + if ( + data.conditionValues.length > 0 && + data.conditionValues.every((value) => data.excludedConditions.includes(value)) + ) { + issues.push("At least one condition must remain — every value is currently excluded"); + } + const conditionColumn = data.conditionColumnRef; if (conditionColumn !== undefined) { const foreign = data.excludedConditions @@ -104,6 +117,10 @@ export function settingsIssues(data: BlockData): string[] { issues.push( `The input '${columnValueLabel(data.inputGate)}' is also a ranked gate — remove it from the gate order`, ); + } else if (data.gateValues.length > 0 && !data.gateValues.includes(data.inputGate)) { + issues.push( + `The gate column does not carry the input value '${columnValueLabel(data.inputGate)}'`, + ); } } @@ -217,9 +234,9 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } // --------------------------------------------------------------------------- /** - * The values of every metadata column on offer, so the gate order can be seeded in the same - * gesture as the gate pick, and the picked gates, input and excluded conditions be shown by - * the values they pick. + * The values of every metadata column on offer, so a column's values can be snapshotted and + * the gate order seeded in the same gesture as the column pick, and the picked gates, input and + * excluded conditions be shown by the values they pick. */ .output("metadataValues", (ctx) => { const abundanceRef = ctx.data.abundanceRef; @@ -333,13 +350,19 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } /** Exposed so the UI can show it as the subtitle field's placeholder. */ .output("defaultBlockLabel", (ctx) => deriveBlockLabel(ctx.data)) - /** The inverse of the data model's `init`, field for field. Mandatory — `done()` throws without it. */ + /** + * The inverse of the data model's `init`, field for field. Mandatory — `done()` throws + * without it. The value snapshots are included: without them a templated gate ladder arrives + * unrunnable, and making it runnable destroys the ladder. + */ .templateParams((data) => ({ conditionColumnRef: data.conditionColumnRef, gateColumnRef: data.gateColumnRef, sortFractionColumnRef: data.sortFractionColumnRef, gateOrder: data.gateOrder, + gateValues: data.gateValues, gateColumnLabel: data.gateColumnLabel, + conditionValues: data.conditionValues, })) /** Constant. What an instance is configured for belongs in the subtitle. */ diff --git a/model/src/metadata.ts b/model/src/metadata.ts index 6a21576..e94f781 100644 --- a/model/src/metadata.ts +++ b/model/src/metadata.ts @@ -61,8 +61,8 @@ export function narrowToRole( * columns, each value a column value id naming its column, and through it the block that * produced the value. * - * Every offered column rather than the picked ones: the gate order is seeded from the gate - * column's values in the same gesture as the pick, so they must be in hand before it. + * Every offered column rather than the picked ones: a column's values are snapshotted, and the + * gate order seeded, in the same gesture as the pick, so they must be in hand before it. * * `undefined` while the metadata options are. A column whose values cannot be read now — still * resolving, not computed, gone, or not stored inline — offers no values, so its picks show as diff --git a/model/src/types.ts b/model/src/types.ts index 37e1252..62aebfa 100644 --- a/model/src/types.ts +++ b/model/src/types.ts @@ -96,9 +96,27 @@ export type BlockData = { /** The variant key for the `sequence` baseline. */ baselineSequence?: string; + // --- Snapshots of the picked columns' distinct values --------------------- + // + // The args lambda sees only `data`, but the checks of the gate order, the input and the + // exclusions need a picked column's VALUES, which only an output of the model reads — so the + // UI writes ref and values in one gesture. + // + // Allowed to go stale: keeping it fresh means a watcher on an output writing back to shared + // data, and the computation re-derives the real values anyway. + /** + * Distinct values of the picked gate column at the moment it was picked, as column value ids + * of that column. + */ + gateValues: ColumnValueId[]; /** Snapshotted so the subtitle stays a pure function of `data`: only the option list knows a * column's label, and that list is an output. */ gateColumnLabel?: string; + /** + * Distinct values of the picked condition column at the moment it was picked, as column value + * ids of that column. + */ + conditionValues: ColumnValueId[]; /** The user's override for the block subtitle. Empty means use the derived label. */ customBlockLabel: string; diff --git a/ui/src/components/SettingsDrawer.vue b/ui/src/components/SettingsDrawer.vue index 4ffe948..348ad9d 100644 --- a/ui/src/components/SettingsDrawer.vue +++ b/ui/src/components/SettingsDrawer.vue @@ -3,8 +3,9 @@ * One control per argument. Two things are easy to "fix" wrongly: * * 1. The read-count floor is clearable — cleared IS the answer, and the normal first run. - * 2. The gate order is seeded on the user's gesture, never by a watcher: a watcher on an - * output writing to `data` is the hairpin, and two clients would race. + * 2. Column values are snapshotted and the gate order seeded on the user's gesture, never by a + * watcher: a watcher on an output writing to `data` is the hairpin, and two clients would + * race. * * Picked gates, the input and excluded conditions are column value ids of their columns. One no * longer among the column's values stays picked and is shown as not available, with the reason @@ -21,6 +22,7 @@ import type { ColumnValueOption, DatasetSelection, } from "@platforma-sdk/model"; +import { columnValueLabel } from "@platforma-sdk/model"; import { PlAccordion, PlAccordionSection, @@ -65,16 +67,6 @@ function valuesOf(column: ColumnUniversalId | undefined): ColumnValueId[] { const conditionValueOptions = computed(() => valueOptionsOf(app.model.data.conditionColumnRef)); -/** - * Every condition excluded leaves nothing to score: the run would produce no results, which - * reads like a failed run. - */ -const everyConditionExcluded = computed(() => { - const options = conditionValueOptions.value; - if (options === undefined || options.length === 0) return false; - return options.every((option) => app.model.data.excludedConditions.includes(option.value)); -}); - const gateValueOptions = computed(() => valueOptionsOf(app.model.data.gateColumnRef)); /** `undefined` means ordered, which is the ordinary case and every block made before this. */ @@ -85,35 +77,34 @@ const gatesOrdered = computed({ }, }); +const gateValues = computed(() => app.model.data.gateValues); + /** * The gate values that are NOT rungs — the reference cannot also be a gate the run ranks. So * the control offers what the gate-order list has had removed. */ const inputGateOptions = computed(() => - gateValueOptions.value?.filter((option) => !app.model.data.gateOrder.includes(option.value)), + gateValues.value + .filter((value) => !app.model.data.gateOrder.includes(value)) + .map((value) => ({ value, label: columnValueLabel(value) })), ); /** * What `setGateColumn` seeds, minus the input gate — the input can never be a ranked gate, so - * removing it is not a modification to offer undoing. `undefined` while the gate column's values - * are not known, so a reset cannot wipe the order before they arrive. + * removing it is not a modification to offer undoing. */ const defaultGateOrder = computed(() => - gateValueOptions.value - ?.map((option) => option.value) - .filter((value) => value !== app.model.data.inputGate), + gateValues.value.filter((value) => value !== app.model.data.inputGate), ); const gateOrderModified = computed(() => { const current = app.model.data.gateOrder; const base = defaultGateOrder.value; - if (base === undefined) return false; return current.length !== base.length || current.some((value, i) => value !== base[i]); }); function resetGateOrder() { - const base = defaultGateOrder.value; - if (base !== undefined) app.model.data.gateOrder = [...base]; + app.model.data.gateOrder = [...defaultGateOrder.value]; } /** `undefined` before a dataset is picked, so an unknown grain never hides a valid option. */ @@ -167,6 +158,8 @@ function setAbundance(ref: ColumnUniversalId | undefined) { app.model.data.conditionColumnRef = undefined; app.model.data.gateColumnRef = undefined; app.model.data.sortFractionColumnRef = undefined; + app.model.data.conditionValues = []; + app.model.data.gateValues = []; app.model.data.gateColumnLabel = undefined; app.model.data.gateOrder = []; app.model.data.excludedConditions = []; @@ -179,13 +172,16 @@ function setAbundance(ref: ColumnUniversalId | undefined) { } function setConditionColumn(ref: ColumnUniversalId | undefined) { - // The exclusions are values of the old column. + // Ref and snapshot in one gesture. The snapshot may go stale; re-picking refreshes it. app.model.data.conditionColumnRef = ref; + app.model.data.conditionValues = valuesOf(ref); + // The exclusions are values of the old column. app.model.data.excludedConditions = []; } function setGateColumn(ref: ColumnUniversalId | undefined) { app.model.data.gateColumnRef = ref; + app.model.data.gateValues = valuesOf(ref); // The label too: only the option list knows it, and the subtitle derives from `data` alone. app.model.data.gateColumnLabel = app.model.outputs.gateOptions?.find( (option) => option.value === ref, @@ -303,10 +299,6 @@ function setGateColumn(ref: ColumnUniversalId | undefined) { Levels to leave out, such as a failed sort; excluded levels produce no results. - - - Every level is excluded, so the run would produce no results. Keep at least one. - From 2e77793a8177f166e0d16114bda5f15d49b51ee1 Mon Sep 17 00:00:00 2001 From: Alexandr Date: Thu, 22 Oct 2026 12:29:26 +0200 Subject: [PATCH 03/17] MILAB-7194: gate Run with argsIssues, read the metadata values through frames args() builds args from whatever is configured and argsIssues() says what keeps the block from running, so the app sees the columns the block references while it is still being set up. The metadata values and the sample names are read in the UI, through a frame of each column, so a column of any storage format can be picked from; a column that is gone or cannot be read says why under its picker. --- .changeset/column-value-refs.md | 4 +- model/package.json | 6 +- model/src/args_issues.test.ts | 205 +++++++++++++++++++++++++++ model/src/dataModel.test.ts | 124 ++++++++++++++++ model/src/index.ts | 54 +++---- model/src/metadata.test.ts | 19 +++ model/src/metadata.ts | 69 +++++---- model/src/types.ts | 21 +-- model/vitest.config.mts | 7 + pnpm-lock.yaml | 3 + ui/src/components/PageHeader.vue | 4 +- ui/src/components/RunStatistics.vue | 27 +++- ui/src/components/SettingsDrawer.vue | 62 ++++++-- ui/src/useColumnValueStates.ts | 88 ++++++++++++ 14 files changed, 600 insertions(+), 93 deletions(-) create mode 100644 model/src/args_issues.test.ts create mode 100644 model/src/dataModel.test.ts create mode 100644 model/src/metadata.test.ts create mode 100644 model/vitest.config.mts create mode 100644 ui/src/useColumnValueStates.ts diff --git a/.changeset/column-value-refs.md b/.changeset/column-value-refs.md index b73da7c..93160b5 100644 --- a/.changeset/column-value-refs.md +++ b/.changeset/column-value-refs.md @@ -6,6 +6,6 @@ "@platforma-open/milaboratories.sort-seq-analysis.workflow": major --- -Columns are stored by their result-pool column ids: the dataset and the condition, gate and sort-fraction columns. The gates of the gate order, the unsorted input and the excluded conditions are stored as column value references of the gate and condition columns, so the block that produced the metadata knows which of its values this block uses; the ranks the workflow receives are keyed by the same references. The model finds columns, builds the options of every column and value picker and reads the sample names through the column collection API instead of the deprecated result pool API, the values are read by the model instead of fetched by the settings panel, and the workflow takes every column through a column bundle. The snapshots of the gate and condition columns' values, written when a column is picked, are stored as column value references of that column too. -Opening a project created before this change keeps its dataset, and clears its condition, gate and sort-fraction columns, the gate order, the unsorted input, the excluded conditions and the value snapshots, since they were stored by ids anchored to the dataset and as plain values, which name no producing block; they have to be picked again before the block runs. The initialization params of the kind carry the same ids and references, the value snapshots included, so templates made for an earlier version of the kind cannot be applied. +Columns are stored by their result-pool column ids: the dataset and the condition, gate and sort-fraction columns. The gates of the gate order, the unsorted input and the excluded conditions are stored as column value references of the gate and condition columns, so the block that produced the metadata knows which of its values this block uses; the ranks the workflow receives are keyed by the same references. The model finds columns and builds the options of every column picker through the column collection API instead of the deprecated result pool API, and the workflow takes every column through a column bundle. The model gives a frame of each metadata column on offer and of the sample label column, and the settings panel and the run statistics read the values and the sample names through it, so a column of any storage format can be picked from; a picked column whose values cannot be read, or that its block no longer produces, says so under its picker. The snapshots of the gate and condition columns' values, written when a column is picked, are stored as column value references of that column too. +Opening a project created before this change keeps its dataset, and clears its condition, gate and sort-fraction columns, the gate order, the unsorted input, the excluded conditions and the value snapshots, since they were stored by ids anchored to the dataset and as plain values, which name no producing block. The condition and gate columns have to be picked again before the block runs; picking the gate column seeds the gate order with every value of that column, so gates removed from the order before have to be removed again. The sort-fraction column, the unsorted input and the excluded conditions are optional, so the block runs without them: until they are picked again, the scores are not corrected for sort yield, no enrichment against the input is computed and every condition is scored. The initialization params of the kind carry the same ids and references, the value snapshots included, so templates made for an earlier version of the kind cannot be applied. Gates, the input and excluded conditions that are no longer among the values of their column stay selected and are marked as not available instead of being removed silently, with a tooltip naming the block that was to provide them, as a link to it, and what went wrong. Picking another gate or condition column still resets the values picked in it and rewrites its snapshot. No check that disables the run is removed: a gate column with no values, a gate or an input the gate column does not carry, and every condition excluded still disable it. diff --git a/model/package.json b/model/package.json index 489d5d1..86f3de3 100644 --- a/model/package.json +++ b/model/package.json @@ -18,7 +18,8 @@ "fmt": "ts-builder format", "watch": "ts-builder build --target block-model --watch", "build": "ts-builder build --target block-model && block-tools build-model", - "check": "ts-builder check --target block-model" + "check": "ts-builder check --target block-model", + "test": "vitest run --passWithNoTests" }, "dependencies": { "@milaboratories/graph-maker": "catalog:", @@ -29,7 +30,8 @@ "devDependencies": { "@milaboratories/ts-builder": "catalog:", "@milaboratories/ts-configs": "catalog:", - "@platforma-sdk/block-tools": "catalog:" + "@platforma-sdk/block-tools": "catalog:", + "vitest": "catalog:" }, "peerDependencies": { "@types/node": "*", diff --git a/model/src/args_issues.test.ts b/model/src/args_issues.test.ts new file mode 100644 index 0000000..2faf297 --- /dev/null +++ b/model/src/args_issues.test.ts @@ -0,0 +1,205 @@ +import { + BlockStorageFacadeCallbacks, + createBlockStorage, + createColumnValueId, + createGlobalPObjectId, + createPlDataTableStateV2, + stringifyJson, +} from "@platforma-sdk/model"; +import { beforeAll, describe, expect, test } from "vitest"; +import type { BlockData } from "./types"; + +const callbackRegistry: Record unknown> = {}; + +beforeAll(async () => { + Object.assign(globalThis, { cfgRenderCtx: { callbackRegistry } }); + await import("./index"); +}); + +const dataset = createGlobalPObjectId("mixcr", "abundance"); +const condition = createGlobalPObjectId("samples", "metadata.condition"); +const gate = createGlobalPObjectId("samples", "metadata.gate"); +const fraction = createGlobalPObjectId("samples", "metadata.fraction"); +const other = createGlobalPObjectId("samples", "metadata.other"); + +const gateValue = (value: string) => createColumnValueId({ column: gate, value }); +const conditionValue = (value: string) => createColumnValueId({ column: condition, value }); +const foreignInput = createColumnValueId({ column: other, value: "INPUT" }); + +const configured: BlockData = { + abundanceRef: dataset, + conditionColumnRef: condition, + gateColumnRef: gate, + sortFractionColumnRef: fraction, + gateOrder: [gateValue("NEG"), gateValue("HIGH")], + excludedConditions: [conditionValue("B")], + inputGate: gateValue("INPUT"), + gateValues: [gateValue("HIGH"), gateValue("INPUT"), gateValue("NEG")], + gateColumnLabel: "Gate", + conditionValues: [conditionValue("A"), conditionValue("B")], + customBlockLabel: "", + resultsTableState: createPlDataTableStateV2(), + ntResultsTableState: createPlDataTableStateV2(), + distributionGraphStates: {}, +}; + +describe("args issues", () => { + test("a configured block derives runnable args", () => { + expect(deriveArgs(configured)).toMatchObject({ + value: { + abundanceRef: dataset, + conditionColumnRef: condition, + gateColumnRef: gate, + gateRanks: { [gateValue("NEG")]: 1, [gateValue("HIGH")]: 2 }, + excludedConditions: [conditionValue("B")], + inputGate: gateValue("INPUT"), + }, + issues: [], + }); + }); + + test("a fresh block gets one complaint per unmade pick, and its args still derive", () => { + const fresh: BlockData = { + ...configured, + abundanceRef: undefined, + conditionColumnRef: undefined, + gateColumnRef: undefined, + sortFractionColumnRef: undefined, + gateOrder: [], + excludedConditions: [], + inputGate: undefined, + gateValues: [], + conditionValues: [], + }; + const messages = [ + "Select an abundance dataset", + "Select the condition column", + "Select the gate column", + ]; + expect(deriveArgs(fresh)).toEqual({ + error: messages.join("; "), + args: expect.objectContaining({ gateRanks: {}, excludedConditions: [] }), + issues: messages.map((message) => ({ severity: "error", message })), + }); + }); + + test.for([ + { + why: "no dataset", + data: { ...configured, abundanceRef: undefined }, + message: "Select an abundance dataset", + }, + { + why: "no condition column", + data: { ...configured, conditionColumnRef: undefined, excludedConditions: [] }, + message: "Select the condition column", + }, + { + why: "no gate column", + data: { ...configured, gateColumnRef: undefined }, + message: "Select the gate column", + }, + { + why: "one column in two roles", + data: { ...configured, sortFractionColumnRef: gate }, + message: "The condition, gate and sort-fraction columns must be three different columns", + }, + { + why: "a gate column without values", + data: { ...configured, gateValues: [], gateOrder: [], inputGate: undefined }, + message: "The gate column has no values to rank", + }, + { + why: "an empty gate order", + data: { ...configured, gateOrder: [] }, + message: "Keep at least one gate in the order — every gate has been removed", + }, + { + why: "an ordered gate the gate column does not carry", + data: { ...configured, gateOrder: [gateValue("NEG"), gateValue("MID")] }, + message: "Ordered value(s) the gate column does not carry: MID", + }, + { + why: "an input gate picked from another column", + data: { + ...configured, + inputGate: foreignInput, + gateValues: [...configured.gateValues, foreignInput], + }, + message: "Gate value(s) picked from another column: INPUT", + }, + { + why: "every condition excluded", + data: { + ...configured, + excludedConditions: [conditionValue("A"), conditionValue("B")], + }, + message: "At least one condition must remain — every value is currently excluded", + }, + { + why: "an excluded condition picked from another column", + data: { + ...configured, + excludedConditions: [createColumnValueId({ column: other, value: "B" })], + }, + message: "Excluded condition(s) picked from another column: B", + }, + { + why: "a negative read-count floor", + data: { ...configured, readFloor: -1 }, + message: "The read-count floor cannot be negative", + }, + { + why: "neither ordered gates nor an input", + data: { ...configured, gatesOrdered: false, inputGate: undefined }, + message: + "Order the gates, or name an unsorted input — with neither there is nothing to compute", + }, + { + why: "an input that is also a ranked gate", + data: { ...configured, inputGate: gateValue("NEG") }, + message: "The input 'NEG' is also a ranked gate — remove it from the gate order", + }, + { + why: "an input the gate column does not carry", + data: { ...configured, inputGate: gateValue("UNSORTED") }, + message: "The gate column does not carry the input value 'UNSORTED'", + }, + ])("$why blocks Run with its message", ({ data, message }) => { + expect(deriveArgs(data)).toMatchObject({ + error: message, + issues: [{ severity: "error", message }], + }); + }); + + test("a gate order picked from another column names each foreign gate", () => { + const foreign = createColumnValueId({ column: other, value: "NEG" }); + expect(deriveArgs({ ...configured, gateOrder: [foreign] })).toMatchObject({ + issues: [ + { severity: "error", message: "Ordered value(s) the gate column does not carry: NEG" }, + { severity: "error", message: "Gate value(s) picked from another column: NEG" }, + ], + }); + }); + + test("an unordered run with an input is runnable", () => { + expect(deriveArgs({ ...configured, gatesOrdered: false })).toMatchObject({ + value: { gatesOrdered: false }, + issues: [], + }); + }); + + test("no exclusions and no sort-fraction column are runnable", () => { + expect( + deriveArgs({ ...configured, excludedConditions: [], sortFractionColumnRef: undefined }), + ).toMatchObject({ issues: [] }); + }); +}); + +// Internals + +function deriveArgs(data: BlockData): unknown { + const derive = callbackRegistry[BlockStorageFacadeCallbacks.ArgsDerive]; + if (derive === undefined) throw new Error("The args derive callback is not registered"); + return derive(stringifyJson(createBlockStorage(data))); +} diff --git a/model/src/dataModel.test.ts b/model/src/dataModel.test.ts new file mode 100644 index 0000000..aaaf85d --- /dev/null +++ b/model/src/dataModel.test.ts @@ -0,0 +1,124 @@ +import { + createColumnValueId, + createGlobalPObjectId, + createPlDataTableStateV2, +} from "@platforma-sdk/model"; +import { describe, expect, test } from "vitest"; +import { blockDataModel } from "./dataModel"; + +const datasetRef = { __isRef: true, blockId: "mixcr", name: "abundance" }; +const dataset = createGlobalPObjectId("mixcr", "abundance"); + +/** An id anchored against the dataset, the way the condition, gate and fraction were stored. */ +const anchored = (name: string) => + JSON.stringify({ axes: [{ anchor: "main", idx: 0 }], name, domain: { column: name } }); + +const tableState = createPlDataTableStateV2(); +const graphState = { title: "Variant Frequency — A", template: "line", currentTab: null }; + +const storedAtV2 = { + abundanceRef: datasetRef, + conditionColumnRef: anchored("condition"), + gateColumnRef: anchored("gate"), + sortFractionColumnRef: anchored("fraction"), + gateOrder: ["NEG", "LOW", "HIGH"], + excludedConditions: ["B"], + readFloor: 10, + gatesOrdered: false, + inputGate: "INPUT", + baseline: "wild-type", + gateValues: ["HIGH", "INPUT", "LOW", "NEG"], + gateColumnLabel: "Gate", + conditionValues: ["A", "B"], + customBlockLabel: "My sort", + resultsTableState: tableState, + ntResultsTableState: tableState, + distributionGraphStates: { A: graphState }, +}; + +describe("Ver_2026_10_21 migration", () => { + const { data } = blockDataModel.migrate({ version: "Ver_2026_09_21", data: storedAtV2 }); + + test("the dataset ref becomes the result-pool id of the same output", () => { + expect(data.abundanceRef).toBe(dataset); + }); + + test("the anchored condition, gate and sort-fraction columns are reset", () => { + expect(data.conditionColumnRef).toBeUndefined(); + expect(data.gateColumnRef).toBeUndefined(); + expect(data.sortFractionColumnRef).toBeUndefined(); + }); + + test("the plain gate order, excluded conditions and input gate are reset", () => { + expect(data.gateOrder).toEqual([]); + expect(data.excludedConditions).toEqual([]); + expect(data.inputGate).toBeUndefined(); + }); + + test("the value snapshots and the gate column label go with their columns", () => { + expect(data.gateValues).toEqual([]); + expect(data.conditionValues).toEqual([]); + expect(data.gateColumnLabel).toBeUndefined(); + }); + + test("settings that are not picks are kept", () => { + expect(data).toMatchObject({ + readFloor: 10, + gatesOrdered: false, + baseline: "wild-type", + customBlockLabel: "My sort", + resultsTableState: tableState, + ntResultsTableState: tableState, + distributionGraphStates: { A: graphState }, + }); + }); + + test("picks already stored as column ids and column value ids are kept", () => { + const gate = createGlobalPObjectId("samples", "metadata.gate"); + const condition = createGlobalPObjectId("samples", "metadata.condition"); + const fraction = createGlobalPObjectId("samples", "metadata.fraction"); + const gateValue = (value: string) => createColumnValueId({ column: gate, value }); + const conditionValue = (value: string) => createColumnValueId({ column: condition, value }); + const stored = { + ...storedAtV2, + conditionColumnRef: condition, + gateColumnRef: gate, + sortFractionColumnRef: fraction, + gateOrder: [gateValue("NEG"), gateValue("HIGH")], + excludedConditions: [conditionValue("B")], + inputGate: gateValue("INPUT"), + gateValues: [gateValue("HIGH"), gateValue("INPUT"), gateValue("NEG")], + conditionValues: [conditionValue("A"), conditionValue("B")], + }; + expect(blockDataModel.migrate({ version: "Ver_2026_09_21", data: stored }).data).toEqual({ + ...stored, + abundanceRef: dataset, + }); + }); + + test("migrating its own output again changes nothing", () => { + // The stored type of the dataset is a ref, so the output's dataset goes back in as one. + const again = blockDataModel.migrate({ + version: "Ver_2026_09_21", + data: { ...data, abundanceRef: datasetRef }, + }).data; + expect(again).toEqual(data); + }); + + test("a block without a dataset stays without one", () => { + const { abundanceRef: _, ...withoutDataset } = storedAtV2; + const migrated = blockDataModel.migrate({ + version: "Ver_2026_09_21", + data: withoutDataset, + }).data; + expect(migrated.abundanceRef).toBeUndefined(); + }); + + test("a Ver_2026_08_07 block reaches the current shape through every step", () => { + const { ntResultsTableState: _, ...storedAtV1 } = storedAtV2; + const migrated = blockDataModel.migrate({ version: "Ver_2026_08_07", data: storedAtV1 }).data; + expect(migrated.abundanceRef).toBe(dataset); + expect(migrated.gateOrder).toEqual([]); + expect(migrated.ntResultsTableState).toEqual(createPlDataTableStateV2()); + }); +}); diff --git a/model/src/index.ts b/model/src/index.ts index 029aa20..5595221 100644 --- a/model/src/index.ts +++ b/model/src/index.ts @@ -8,6 +8,7 @@ import { discoverTableColumnSnaphots, type InferOutputsType, parseColumnValueId, + type ArgsIssue, } from "@platforma-sdk/model"; import { kind } from "@platforma-open/milaboratories.sort-seq-analysis.kind"; import { getAbundanceOptions, isNucleotideDataset } from "./abundance"; @@ -16,7 +17,12 @@ import { exact, getOutputColumns, toPColumns } from "./column_access"; import { Alphabet, AlphabetDomain, FacsBin, PColumnName } from "./columns"; import { blockDataModel } from "./dataModel"; import type { MetadataRole } from "./metadata"; -import { getMetadataOptions, getMetadataValues, getSampleLabels, narrowToRole } from "./metadata"; +import { + getMetadataOptions, + getMetadataValueSources, + getSampleLabelSource, + narrowToRole, +} from "./metadata"; import type { BlockArgs, BlockData, RunManifest } from "./types"; export { fromAbundanceSelection, toAbundanceSelection } from "./abundance"; @@ -25,7 +31,8 @@ export { blockDataModel, defaultDistributionGraphState } from "./dataModel"; export * from "./columns"; export * from "./types"; export type { ColumnPickerOption } from "./column_access"; -export type { MetadataColumnValues } from "./metadata"; +export { pairSampleLabels } from "./metadata"; +export type { SampleLabelCell } from "./metadata"; /** * Whether the baseline is offered. Pairs with `EMIT_BASELINE_COLUMNS` in @@ -146,29 +153,16 @@ export function distributionPlotTitle( export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind }) .args((data) => { - // Throwing disables Run but carries no reason to the user; `settingsIssues` names it. - const issues = settingsIssues(data); - if (issues.length > 0) throw new Error(issues.join("; ")); - - // `settingsIssues` refuses each of these absent; checked again so the type says so. - const { abundanceRef, conditionColumnRef, gateColumnRef } = data; - if ( - abundanceRef === undefined || - conditionColumnRef === undefined || - gateColumnRef === undefined - ) { - throw new Error("Select the dataset, the condition column and the gate column"); - } - // Two facts, not a mode. An enrichment needs a reference, so naming one is what asks for // it; ranks need an order, so the toggle is what asks for those. `inputGate` carries the // first straight through, so only the second needs a local. const ordered = data.gatesOrdered !== false; return { - abundanceRef, - conditionColumnRef, - gateColumnRef, + // Absent on an incomplete configuration; `argsIssues` keeps such args from running. + abundanceRef: data.abundanceRef, + conditionColumnRef: data.conditionColumnRef, + gateColumnRef: data.gateColumnRef, // Position becomes the rank, contiguous over the gates the list holds — a gap would // move every score, since ranks enter the weighted mean as numbers. The key set also // tells the computation which gates the run covers. @@ -203,6 +197,12 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } }; }) + // An error disables Run but its message does not reach the user; the `settingsIssues` + // output names it. + .argsIssues(({ data }) => + settingsIssues(data).map((message): ArgsIssue => ({ severity: "error", message })), + ) + // --------------------------------------------------------------------------- // Option lists. Four pickers, two predicates. // --------------------------------------------------------------------------- @@ -234,21 +234,21 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } // --------------------------------------------------------------------------- /** - * The values of every metadata column on offer, so a column's values can be snapshotted and - * the gate order seeded in the same gesture as the column pick, and the picked gates, input and - * excluded conditions be shown by the values they pick. + * Where the UI reads the values of every metadata column on offer, so a column's values can be + * snapshotted and the gate order seeded in the same gesture as the column pick, and the picked + * gates, input and excluded conditions be shown by the values they pick. */ - .output("metadataValues", (ctx) => { + .output("metadataValueSources", (ctx) => { const abundanceRef = ctx.data.abundanceRef; if (abundanceRef === undefined) return undefined; - return getMetadataValues(ctx, abundanceRef, ctx.data); + return getMetadataValueSources(ctx, abundanceRef, ctx.data); }) - /** Sample names by sample id, for the pooling report's sample ids. */ - .output("sampleLabels", (ctx) => { + /** Where the UI reads the sample names from, for the pooling report's sample ids. */ + .output("sampleLabelSource", (ctx) => { const abundanceRef = ctx.data.abundanceRef; if (abundanceRef === undefined) return undefined; - return getSampleLabels(ctx, abundanceRef); + return getSampleLabelSource(ctx, abundanceRef); }) // --------------------------------------------------------------------------- diff --git a/model/src/metadata.test.ts b/model/src/metadata.test.ts new file mode 100644 index 0000000..b95c131 --- /dev/null +++ b/model/src/metadata.test.ts @@ -0,0 +1,19 @@ +import { describe, expect, test } from "vitest"; +import { pairSampleLabels } from "./metadata"; + +describe("pairSampleLabels", () => { + test("pairs each sample id with the label of its row", () => { + expect(pairSampleLabels(["s1", "s2"], ["Donor A", "Donor B"])).toEqual({ + s1: "Donor A", + s2: "Donor B", + }); + }); + + test("keys and labels read as numbers become strings", () => { + expect(pairSampleLabels([7], [42])).toEqual({ "7": "42" }); + }); + + test("a row missing its id or its label is left out", () => { + expect(pairSampleLabels(["s1", null, "s3", "s4"], ["A", "B", null])).toEqual({ s1: "A" }); + }); +}); diff --git a/model/src/metadata.ts b/model/src/metadata.ts index e94f781..d96d18c 100644 --- a/model/src/metadata.ts +++ b/model/src/metadata.ts @@ -1,9 +1,5 @@ -import type { ColumnUniversalId, ColumnValueOption, RenderCtxBase } from "@platforma-sdk/model"; -import { - deriveColumnOptions, - deriveColumnValueOptions, - readColumnValues, -} from "@platforma-sdk/model"; +import type { ColumnUniversalId, ColumnValuesSource, RenderCtxBase } from "@platforma-sdk/model"; +import { createColumnValuesSource, deriveColumnOptions } from "@platforma-sdk/model"; import type { ColumnPickerOption } from "./column_access"; import { axisSelector, findColumn, resultPool } from "./column_access"; import { metadataSelector, sampleLabelSelector } from "./columns"; @@ -15,12 +11,6 @@ export type MetadataRole = "conditionColumnRef" | "gateColumnRef" | "sortFractio /** The column picked for each role. */ export type MetadataPicks = Pick; -/** The values of one sample-metadata column, as options of the value pickers. */ -export type MetadataColumnValues = { - column: ColumnUniversalId; - options: ColumnValueOption[]; -}; - /** * Sample-metadata columns of upstream blocks whose only axis is the dataset's sample axis * (axis 0), as options of the three role pickers. Every option id is a result-pool leaf, so it @@ -57,22 +47,20 @@ export function narrowToRole( } /** - * The values of every offered sample-metadata column and of the picked condition and gate - * columns, each value a column value id naming its column, and through it the block that - * produced the value. + * Where the UI reads the values of every offered sample-metadata column and of the picked + * condition and gate columns: one source per column, each a frame of that column alone. * * Every offered column rather than the picked ones: a column's values are snapshotted, and the * gate order seeded, in the same gesture as the pick, so they must be in hand before it. * - * `undefined` while the metadata options are. A column whose values cannot be read now — still - * resolving, not computed, gone, or not stored inline — offers no values, so its picks show as - * not available. + * `undefined` while the metadata options are. A picked column that is gone has an `absent` + * source, so its picks show as not available. */ -export function getMetadataValues( +export function getMetadataValueSources( ctx: RenderCtxBase, abundanceRef: ColumnUniversalId, picks: MetadataPicks, -): MetadataColumnValues[] | undefined { +): ColumnValuesSource[] | undefined { const options = getMetadataOptions(ctx, abundanceRef); if (options === undefined) return undefined; @@ -80,17 +68,17 @@ export function getMetadataValues( for (const picked of [picks.conditionColumnRef, picks.gateColumnRef]) { if (picked !== undefined) columns.add(picked); } - return [...columns].map((column) => ({ column, options: readValueOptions(ctx, column) })); + return [...columns].map((column) => createColumnValuesSource(ctx, column)); } /** - * Sample names by sample id, read off the label column of the dataset's sample axis. - * `undefined` while the dataset or its label column is not known or not readable. + * Where the UI reads the sample names from: a frame of the label column of the dataset's sample + * axis alone. `undefined` while the dataset or its label column is not known. */ -export function getSampleLabels( +export function getSampleLabelSource( ctx: RenderCtxBase, abundanceRef: ColumnUniversalId, -): Record | undefined { +): ColumnValuesSource | undefined { const sampleAxis = findColumn(ctx, abundanceRef)?.getSpec().axesSpec[0]; if (sampleAxis === undefined) return undefined; @@ -104,13 +92,30 @@ export function getSampleLabels( }) .getColumns(); if (column === undefined) return undefined; + return createColumnValuesSource(ctx, column.id); +} - const entries = readColumnValues(column); - if (entries === undefined) return undefined; - // One axis, so the key's only entry is the sample id. - return Object.fromEntries(entries.map((entry) => [String(entry.key[0]), String(entry.value)])); +/** + * Sample names by sample id, from the rows of the label column: `sampleIds[i]` is the key of the + * row whose label is `labels[i]`. A row missing either is left out. + */ +export function pairSampleLabels( + sampleIds: readonly SampleLabelCell[], + labels: readonly SampleLabelCell[], +): Record { + const pairs: Record = {}; + for (const [index, sampleId] of sampleIds.entries()) { + const label = labels[index]; + if (sampleId !== null && label !== null && label !== undefined) { + pairs[String(sampleId)] = String(label); + } + } + return pairs; } +/** One cell of the label column as a frame reads it: a key or a label, `null` where missing. */ +export type SampleLabelCell = string | number | null; + // Internals const METADATA_ROLES: readonly MetadataRole[] = [ @@ -118,9 +123,3 @@ const METADATA_ROLES: readonly MetadataRole[] = [ "gateColumnRef", "sortFractionColumnRef", ]; - -function readValueOptions(ctx: RenderCtxBase, columnRef: ColumnUniversalId): ColumnValueOption[] { - const column = findColumn(ctx, columnRef); - const entries = column === undefined ? undefined : readColumnValues(column); - return deriveColumnValueOptions(entries ?? []); -} diff --git a/model/src/types.ts b/model/src/types.ts index 62aebfa..f7f7816 100644 --- a/model/src/types.ts +++ b/model/src/types.ts @@ -19,12 +19,15 @@ export type BaselineOption = "wild-type" | "synonymous" | "sequence"; * back out at its entry. */ export type BlockArgs = { - /** 1. The dataset selection that anchors every other input. */ - abundanceRef: ColumnUniversalId; - /** 2. A per-sample metadata column, picked from the option list. */ - conditionColumnRef: ColumnUniversalId; - /** 3. A per-sample metadata column, picked for the other role. */ - gateColumnRef: ColumnUniversalId; + /** 1. The dataset selection that anchors every other input. Absent only on a block not yet + * allowed to run. */ + abundanceRef?: ColumnUniversalId; + /** 2. A per-sample metadata column, picked from the option list. Absent only on a block not + * yet allowed to run. */ + conditionColumnRef?: ColumnUniversalId; + /** 3. A per-sample metadata column, picked for the other role. Absent only on a block not yet + * allowed to run. */ + gateColumnRef?: ColumnUniversalId; /** * 4. A rank per selected gate, contiguous from 1, derived from `gateOrder` by position. Keyed * by the gate's column value id, so each key still names the gate column it was picked from. @@ -99,8 +102,8 @@ export type BlockData = { // --- Snapshots of the picked columns' distinct values --------------------- // // The args lambda sees only `data`, but the checks of the gate order, the input and the - // exclusions need a picked column's VALUES, which only an output of the model reads — so the - // UI writes ref and values in one gesture. + // exclusions need a picked column's VALUES, which only the UI reads, through a frame of the + // column — so the UI writes ref and values in one gesture. // // Allowed to go stale: keeping it fresh means a watcher on an output writing back to shared // data, and the computation re-derives the real values anyway. @@ -147,7 +150,7 @@ export type GateCollected = { export type PooledGroup = { condition: string; gate: string; - /** Sample **ids**, sorted. The UI resolves them to labels via `sampleLabelPframe`. */ + /** Sample **ids**, sorted. The UI resolves them to labels via `sampleLabelSource`. */ samples: string[]; /** Replicates supplied different fractions and were averaged. Absent when uncorrected. */ sortFractionsDiffer?: boolean; diff --git a/model/vitest.config.mts b/model/vitest.config.mts new file mode 100644 index 0000000..609455d --- /dev/null +++ b/model/vitest.config.mts @@ -0,0 +1,7 @@ +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + test: { + watch: false, + }, +}); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 83d6785..585a739 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -176,6 +176,9 @@ importers: '@platforma-sdk/block-tools': specifier: 'catalog:' version: 2.16.14(@types/node@26.1.2) + vitest: + specifier: 'catalog:' + version: 4.0.18(@types/node@26.1.2)(lightningcss@1.33.0)(yaml@2.9.0) software: devDependencies: diff --git a/ui/src/components/PageHeader.vue b/ui/src/components/PageHeader.vue index d2dd19c..d78d758 100644 --- a/ui/src/components/PageHeader.vue +++ b/ui/src/components/PageHeader.vue @@ -11,7 +11,7 @@ * button, one drawer, one place. Mounting it per page gave three `PlSlideModal`s racing * over one shared open flag. */ -import { PlBtnGhost, PlIcon24 } from "@platforma-sdk/ui-vue"; +import { PlBtnGhost, PlMaskIcon24 } from "@platforma-sdk/ui-vue"; import { useApp } from "../app"; import { useSettingsDrawer } from "../useSettingsDrawer"; import SettingsDrawer from "./SettingsDrawer.vue"; @@ -23,7 +23,7 @@ const { isOpen } = useSettingsDrawer(useApp()); Settings diff --git a/ui/src/components/RunStatistics.vue b/ui/src/components/RunStatistics.vue index 442a243..1ed4419 100644 --- a/ui/src/components/RunStatistics.vue +++ b/ui/src/components/RunStatistics.vue @@ -5,13 +5,17 @@ * `@click.stop` is required: the dialog closes on an outside click, and the opening click would * bubble up and be read as outside. Open state is a local ref — in `data` it would be shared. */ +import { pairSampleLabels } from "@platforma-open/milaboratories.sort-seq-analysis.model"; +import type { PresentColumnValuesSource } from "@platforma-sdk/model"; +import { getSingleColumnData, PFrameImpl } from "@platforma-sdk/model"; import { PlAgOverlayLoading, PlAlert, PlBtnGhost, PlDialogModal, PlLogView, - PlIcon24, + PlMaskIcon24, + useWatchFetch, } from "@platforma-sdk/ui-vue"; import { computed, ref } from "vue"; import { useApp } from "../app"; @@ -74,9 +78,26 @@ const inputDepths = computed(() => { })); }); +/** Sample names by sample id, read off the label column's frame. */ +const sampleLabels = useWatchFetch( + () => app.model.outputs.sampleLabelSource, + async (source) => (source?.type === "present" ? readSampleLabels(source) : undefined), +); + /** The sample's name, falling back to the raw id. */ function labelFor(sampleId: string): string { - return app.model.outputs.sampleLabels?.[sampleId] ?? sampleId; + return sampleLabels.value?.[sampleId] ?? sampleId; +} + +/** The frame holds the label column alone, and it has one axis: the sample id. */ +async function readSampleLabels( + source: PresentColumnValuesSource, +): Promise> { + const [column] = await new PFrameImpl(source.frame).listColumns(); + if (column === undefined) return {}; + const { axesData, data } = await getSingleColumnData(source.frame, column.columnId); + const [sampleIds] = Object.values(axesData); + return pairSampleLabels(sampleIds ?? [], data); } /** @@ -138,7 +159,7 @@ function binScoreCell(entry: { Statistics diff --git a/ui/src/components/SettingsDrawer.vue b/ui/src/components/SettingsDrawer.vue index 348ad9d..daada87 100644 --- a/ui/src/components/SettingsDrawer.vue +++ b/ui/src/components/SettingsDrawer.vue @@ -23,6 +23,7 @@ import type { DatasetSelection, } from "@platforma-sdk/model"; import { columnValueLabel } from "@platforma-sdk/model"; +import type { ColumnValueOptionsState } from "@platforma-sdk/ui-vue"; import { PlAccordion, PlAccordionSection, @@ -33,7 +34,7 @@ import { PlElementList, PlDatasetSelector, PlDropdownMulti, - PlIcon24, + PlMaskIcon24, PlNumberField, PlSlideModal, PlTooltip, @@ -41,6 +42,7 @@ import { } from "@platforma-sdk/ui-vue"; import { computed, ref } from "vue"; import { useApp } from "../app"; +import { useColumnValueStates } from "../useColumnValueStates"; const app = useApp(); @@ -51,23 +53,54 @@ const armsOpen = ref(true); // Open state belongs to the parent, which mounts this beside the button that opens it. const isOpen = defineModel({ required: true }); +/** The values of every metadata column on offer and of the picked ones, by column. */ +const valueStates = useColumnValueStates(() => app.model.outputs.metadataValueSources); + /** - * Values of a metadata column, as the model read them. `undefined` while they are not known, so - * picks are not marked as not available before the model has caught up. + * How far the values of a metadata column are read. `undefined` while no column is picked; + * loading until the model gives a source for it. */ -function valueOptionsOf(column: ColumnUniversalId | undefined): ColumnValueOption[] | undefined { +function valueStateOf(column: ColumnUniversalId | undefined): ColumnValueOptionsState | undefined { if (column === undefined) return undefined; - return app.model.outputs.metadataValues?.find((entry) => entry.column === column)?.options; + return valueStates.value.get(column) ?? { type: "loading" }; +} + +/** + * Values of a metadata column as options of a value picker. `undefined` while they are not + * known, so picks are not marked as not available before they are read. None for a column that + * is gone, so every pick of it is. + */ +function valueOptionsOf( + state: ColumnValueOptionsState | undefined, +): ColumnValueOption[] | undefined { + if (state?.type === "read") return state.options; + if (state?.type === "absent") return []; + return undefined; } -/** The values of a column, in the order the model offers them. */ +/** Why a picked column offers no values, shown under the control that picks it. */ +function valuesProblemOf(state: ColumnValueOptionsState | undefined): string | undefined { + if (state?.type === "absent") { + return "The column is no longer produced by its block, so it has no values to pick"; + } + if (state?.type === "failed") { + return `The values of the column could not be read: ${state.message}`; + } + return undefined; +} + +/** The values of a column, in natural order, as far as they are read now. */ function valuesOf(column: ColumnUniversalId | undefined): ColumnValueId[] { - return (valueOptionsOf(column) ?? []).map((option) => option.value); + return (valueOptionsOf(valueStateOf(column)) ?? []).map((option) => option.value); } -const conditionValueOptions = computed(() => valueOptionsOf(app.model.data.conditionColumnRef)); +const conditionValueState = computed(() => valueStateOf(app.model.data.conditionColumnRef)); + +const gateValueState = computed(() => valueStateOf(app.model.data.gateColumnRef)); + +const conditionValueOptions = computed(() => valueOptionsOf(conditionValueState.value)); -const gateValueOptions = computed(() => valueOptionsOf(app.model.data.gateColumnRef)); +const gateValueOptions = computed(() => valueOptionsOf(gateValueState.value)); /** `undefined` means ordered, which is the ordinary case and every block made before this. */ const gatesOrdered = computed({ @@ -213,8 +246,9 @@ function setGateColumn(ref: ColumnUniversalId | undefined) { Reset to default @@ -279,8 +313,9 @@ function setGateColumn(ref: ColumnUniversalId | undefined) {