Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
04203fc
MILAB-7194: store columns as result-pool ids and gates and conditions…
AStaroverov Oct 21, 2026
901d08c
MILAB-7194: keep the gate and condition value snapshots and the check…
AStaroverov Oct 21, 2026
2e77793
MILAB-7194: gate Run with argsIssues, read the metadata values throug…
AStaroverov Oct 22, 2026
1ddd6b9
MILAB-7194: read the metadata values through the block's own frames
AStaroverov Oct 22, 2026
5001e7b
MILAB-7194: read columns through the default render context, not a ct…
AStaroverov Oct 22, 2026
3ce06c6
MILAB-7194: offer the unsorted input from the gate column's live values
AStaroverov Oct 22, 2026
8361aac
MILAB-7194: update SDK to 1.88.0
AStaroverov Nov 5, 2026
be08fe8
MILAB-7194: accept only result-pool ids of other blocks' outputs in t…
AStaroverov Nov 5, 2026
0a7ecda
MILAB-7194: decode the column ids in the workflow as on main
AStaroverov Nov 5, 2026
8a9d400
MILAB-7194: read the metadata values with the SDK value options
AStaroverov Nov 5, 2026
667e0f9
MILAB-7194: read the sample labels in the model
AStaroverov Nov 5, 2026
82a2680
MILAB-7194: offer the unsorted input from the gate value snapshot, as…
AStaroverov Nov 5, 2026
78b8859
MILAB-7194: use PlIcon24 instead of the deprecated PlMaskIcon24
AStaroverov Nov 5, 2026
8d3303d
MILAB-7194: cover the subset, the role distinctness and the subtitle …
AStaroverov Nov 5, 2026
a4b7755
MILAB-7194: describe the value options and the sample names in the ch…
AStaroverov Nov 5, 2026
d3b438f
MILAB-7194: keep in the migration only the column ids the kind accepts
AStaroverov Nov 5, 2026
1c32d2c
MILAB-7194: read the picked condition and gate columns' values withou…
AStaroverov Nov 5, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .changeset/column-value-refs.md
Original file line number Diff line number Diff line change
@@ -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 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 the value options of each metadata column on offer, and the settings panel reads the values through them, 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 run statistics take the sample names from the model. 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.
6 changes: 4 additions & 2 deletions kind/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,8 @@
"fmt": "ts-builder format",
"watch": "ts-builder build --target block-kind --watch",
"build": "ts-builder build --target block-kind && block-tools build-kind-manifest",
"check": "ts-builder check --target block-kind"
"check": "ts-builder check --target block-kind",
"test": "vitest run --passWithNoTests"
},
"dependencies": {
"@platforma-sdk/block-kind": "catalog:",
Expand All @@ -28,7 +29,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": "*",
Expand Down
101 changes: 101 additions & 0 deletions kind/src/index.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
import {
createColumnValueId,
createColumnValueIds,
createGlobalPObjectId,
createLocalPObjectId,
} from "@platforma-sdk/model";
import { describe, expect, it } from "vitest";
import { kind } from "./index";

const parse = (params: unknown) => kind.parseInitializationParams(params);

/** A metadata column of an upstream block, as the settings drawer stores it. */
const GATE = createGlobalPObjectId("samples", "metadata.gate");
const CONDITION = createGlobalPObjectId("samples", "metadata.condition");

/** The id the drawer stored before columns became result-pool ids: anchored to the dataset. */
const ANCHORED_ID =
'{"axes":[{"anchor":"main","idx":0}],"domain":{"pl7.app/columnId":"Gate"},"name":"pl7.app/metadata","type":"String"}';
/** Other column id forms, which name no single output of an upstream block. */
const LOCAL_ID = createLocalPObjectId(["a", "b"], "pl7.app/metadata");
const FILTERED_ID = `{"__isFiltered":true,"axisFilters":[[0,"s1"]],"source":${JSON.stringify(GATE)}}`;

const COLUMN_FIELDS = ["conditionColumnRef", "gateColumnRef", "sortFractionColumnRef"] as const;
const VALUE_FIELDS = ["gateOrder", "gateValues", "conditionValues"] as const;

describe.each(COLUMN_FIELDS)("%s", (field) => {
it("accepts the result-pool id of an upstream output", () => {
expect(parse({ [field]: GATE })).toEqual({ [field]: GATE });
});

it.each([
["an anchored id", ANCHORED_ID],
["a local id", LOCAL_ID],
["a filtered id", FILTERED_ID],
["a ref object rather than its id", { __isRef: true, blockId: "samples", name: "metadata" }],
["a string that is not JSON", "Gate"],
["a number", 42],
["null", null],
])("rejects %s", (_label, id) => {
expect(() => parse({ [field]: id })).toThrow(`'${field}' must be a metadata column`);
});
});

describe.each(VALUE_FIELDS)("%s", (field) => {
it.each([
["an empty list", []],
["column value ids", createColumnValueIds({ column: GATE, values: ["NEG", "LOW", "HIGH"] })],
])("accepts %s", (_label, values) => {
expect(parse({ [field]: values })).toEqual({ [field]: values });
});

it("rejects plain values, as stored before column value ids", () => {
expect(() => parse({ [field]: ["NEG", "LOW"] })).toThrow(
`'${field}[0]' must be a column value`,
);
});

it("rejects a list with a hole", () => {
const values = [createColumnValueId({ column: GATE, value: "NEG" }), null];
expect(() => parse({ [field]: values })).toThrow(`'${field}[1]' must be a column value`);
});

it("rejects a bare value rather than a list", () => {
expect(() => parse({ [field]: createColumnValueId({ column: GATE, value: "NEG" }) })).toThrow(
`'${field}' must be a list.`,
);
});
});

describe("the params envelope", () => {
it("accepts an empty object — every field is optional", () => {
expect(parse({})).toEqual({});
});

it("accepts a fully configured metadata reading", () => {
const gates = createColumnValueIds({ column: GATE, values: ["NEG", "LOW", "HIGH", "INPUT"] });
const params = {
conditionColumnRef: CONDITION,
gateColumnRef: GATE,
sortFractionColumnRef: createGlobalPObjectId("samples", "metadata.fraction"),
gateOrder: gates.slice(0, 3),
gateValues: gates,
gateColumnLabel: "Gate",
conditionValues: createColumnValueIds({ column: CONDITION, values: ["CD4+", "CD8+"] }),
};
expect(parse(params)).toEqual(params);
});

it("drops keys the contract does not name", () => {
expect(parse({ gateColumnLabel: "Gate", readFloor: 10 })).toEqual({ gateColumnLabel: "Gate" });
});

it("rejects a gateColumnLabel that is not a string", () => {
expect(() => parse({ gateColumnLabel: 1 })).toThrow("'gateColumnLabel' must be a string.");
});

it("rejects params that are not an object", () => {
expect(() => parse(null)).toThrow();
expect(() => parse([GATE])).toThrow();
});
});
130 changes: 52 additions & 78 deletions kind/src/index.ts
Original file line number Diff line number Diff line change
@@ -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 { isColumnValueId, isGlobalPObjectId } from "@platforma-sdk/model";
import { name, version } from "../package.json" with { type: "json" };

/**
Expand All @@ -14,16 +11,9 @@ 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 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.
*
* **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,
Expand All @@ -37,26 +27,38 @@ import { name, version } from "../package.json" with { type: "json" };
*
* 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.
*
* Every field is optional. A block may be created with no template at all, so the model's
* `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[];
gateValues?: ColumnValueId[];
gateColumnLabel?: string;
conditionValues?: string[];
conditionValues?: ColumnValueId[];
};

// 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<BlockParams>({
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.
Expand All @@ -67,11 +69,10 @@ 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 `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);
Expand All @@ -90,69 +91,42 @@ function parseInitializationParams(value: unknown): BlockParams {
conditionColumnRef: optionalColumnRef(conditionColumnRef, "conditionColumnRef"),
gateColumnRef: optionalColumnRef(gateColumnRef, "gateColumnRef"),
sortFractionColumnRef: optionalColumnRef(sortFractionColumnRef, "sortFractionColumnRef"),
gateOrder: optionalStringList(gateOrder, "gateOrder"),
gateValues: optionalStringList(gateValues, "gateValues"),
gateOrder: optionalValueList(gateOrder, "gateOrder"),
gateValues: optionalValueList(gateValues, "gateValues"),
gateColumnLabel: optionalString(gateColumnLabel, "gateColumnLabel"),
conditionValues: optionalStringList(conditionValues, "conditionValues"),
conditionValues: optionalValueList(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.
* A metadata column of another block: the pickers offer upstream outputs only, so the
* result-pool id of one is the only column id a template can carry. 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 (!isGlobalPObjectId(value)) {
throw new Error(`'${field}' must be a metadata column, written as ${OUTPUT_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<BlockParams>({
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;
}

const OUTPUT_ID = "the result-pool id of another block's output";
6 changes: 4 additions & 2 deletions model/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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:",
Expand All @@ -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": "*",
Expand Down
Loading
Loading