From fa8d1ec9235c790f019c82e947b1a17e18761d36 Mon Sep 17 00:00:00 2001 From: Alexandr Date: Mon, 16 Nov 2026 10:45:16 +0100 Subject: [PATCH] Keep the dataset and the run recipe in a project template A project made from a template came with Sort-Seq Analysis without its dataset, so the block could not run and everything below it waited. The kind left `abundanceRef` out as a pick against one project's result pool. A template names its blocks, and applying one points a column id at the block made from the same entry, as it already does for the three metadata columns this kind carries. The run recipe was out of the contract too: the exclusions, the read floor, the gate order flag, the input and the baseline. A project made from a template then ran on defaults under the original's name, and the columns the blocks below ask for depend on those settings. The kind now carries the dataset, its subset and the run recipe; `init` reads them and `templateParams` writes them back. `BaselineOption` moves to the kind, which names it now. --- .changeset/template-keeps-dataset.md | 6 ++ kind/src/index.test.ts | 65 ++++++++++++++-- kind/src/index.ts | 110 ++++++++++++++++++++++----- model/src/dataModel.ts | 14 +++- model/src/index.ts | 8 ++ model/src/stored_data.ts | 2 +- model/src/types.ts | 4 +- 7 files changed, 174 insertions(+), 35 deletions(-) create mode 100644 .changeset/template-keeps-dataset.md diff --git a/.changeset/template-keeps-dataset.md b/.changeset/template-keeps-dataset.md new file mode 100644 index 0000000..a470c3a --- /dev/null +++ b/.changeset/template-keeps-dataset.md @@ -0,0 +1,6 @@ +--- +"@platforma-open/milaboratories.sort-seq-analysis.kind": minor +"@platforma-open/milaboratories.sort-seq-analysis.model": patch +--- + +Keep the dataset and the run recipe in a project template. A project made from a template came with Sort-Seq Analysis without its dataset, so the block could not run, and with its exclusions, read floor, gate order flag, input and baseline back on their defaults. The kind now carries all of them, and the block made from a template points at the columns of the project being made. diff --git a/kind/src/index.test.ts b/kind/src/index.test.ts index 5531d4c..0112bd9 100644 --- a/kind/src/index.test.ts +++ b/kind/src/index.test.ts @@ -20,10 +20,17 @@ const ANCHORED_ID = 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; +/** Each column field, with what its refusal calls the column. */ +const COLUMN_FIELDS = [ + ["abundanceRef", "a dataset"], + ["filterRef", "a subset column"], + ["conditionColumnRef", "a metadata column"], + ["gateColumnRef", "a metadata column"], + ["sortFractionColumnRef", "a metadata column"], +] as const; +const VALUE_FIELDS = ["gateOrder", "gateValues", "conditionValues", "excludedConditions"] as const; -describe.each(COLUMN_FIELDS)("%s", (field) => { +describe.each(COLUMN_FIELDS)("%s", (field, what) => { it("accepts the result-pool id of an upstream output", () => { expect(parse({ [field]: GATE })).toEqual({ [field]: GATE }); }); @@ -37,7 +44,7 @@ describe.each(COLUMN_FIELDS)("%s", (field) => { ["a number", 42], ["null", null], ])("rejects %s", (_label, id) => { - expect(() => parse({ [field]: id })).toThrow(`'${field}' must be a metadata column`); + expect(() => parse({ [field]: id })).toThrow(`'${field}' must be ${what}`); }); }); @@ -67,27 +74,71 @@ describe.each(VALUE_FIELDS)("%s", (field) => { }); }); +describe("inputGate", () => { + it("accepts a column value id", () => { + const input = createColumnValueId({ column: GATE, value: "INPUT" }); + expect(parse({ inputGate: input })).toEqual({ inputGate: input }); + }); + + it("rejects a plain value", () => { + expect(() => parse({ inputGate: "INPUT" })).toThrow("'inputGate' must be a column value"); + }); +}); + +describe("the run recipe's plain values", () => { + it.each([ + ["readFloor", 10], + ["readFloor", 0], + ["gatesOrdered", false], + ["baseline", "synonymous"], + ["baselineSequence", "ACGT"], + ])("accepts %s: %s", (field, value) => { + expect(parse({ [field]: value })).toEqual({ [field]: value }); + }); + + it.each([ + ["readFloor", "10", "'readFloor' must be a number."], + ["readFloor", Number.NaN, "'readFloor' must be a number."], + ["gatesOrdered", "no", "'gatesOrdered' must be true or false."], + ["baseline", "parent", "'baseline' must be one of wild-type, synonymous, sequence."], + ["baselineSequence", 1, "'baselineSequence' must be a string."], + ])("rejects %s: %s", (field, value, message) => { + expect(() => parse({ [field]: value })).toThrow(message); + }); +}); + describe("the params envelope", () => { it("accepts an empty object — every field is optional", () => { expect(parse({})).toEqual({}); }); - it("accepts a fully configured metadata reading", () => { + it("accepts a fully configured block", () => { const gates = createColumnValueIds({ column: GATE, values: ["NEG", "LOW", "HIGH", "INPUT"] }); + const conditions = createColumnValueIds({ column: CONDITION, values: ["CD4+", "CD8+"] }); const params = { + abundanceRef: createGlobalPObjectId("profiler", "variants.read-count"), + filterRef: createGlobalPObjectId("labeling", "subset.leads"), 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+"] }), + conditionValues: conditions, + excludedConditions: conditions.slice(1), + readFloor: 5, + gatesOrdered: false, + inputGate: gates[3], + baseline: "synonymous", + baselineSequence: undefined, }; expect(parse(params)).toEqual(params); }); it("drops keys the contract does not name", () => { - expect(parse({ gateColumnLabel: "Gate", readFloor: 10 })).toEqual({ gateColumnLabel: "Gate" }); + expect(parse({ gateColumnLabel: "Gate", customBlockLabel: "Mine" })).toEqual({ + gateColumnLabel: "Gate", + }); }); it("rejects a gateColumnLabel that is not a string", () => { diff --git a/kind/src/index.ts b/kind/src/index.ts index 8b7177a..ee2327a 100644 --- a/kind/src/index.ts +++ b/kind/src/index.ts @@ -3,17 +3,27 @@ import type { ColumnUniversalId, ColumnValueId } from "@platforma-sdk/model"; import { isColumnValueId, isGlobalPObjectId } from "@platforma-sdk/model"; import { name, version } from "../package.json" with { type: "json" }; +/** What a per-gate enrichment is read against. `synonymous` needs the nucleotide grain. */ +export type BaselineOption = "wild-type" | "synonymous" | "sequence"; + /** * This block's init-params contract — what a creator, or a project template, supplies to seed a - * new instance. A subset of the model's `BlockData`. + * new instance. A subset of the model's `BlockData`: everything the user sets in the drawer. * - * The subset is **the metadata reading of a sort-seq run**: which column says condition, which - * 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 dataset** — `abundanceRef`, and `filterRef` when the run is narrowed to a subset of it. + * - **The metadata reading** — which column says condition, which says gate, which says sort + * fraction, and what the gate ladder is. + * - **The run recipe** — the excluded conditions, the read-count floor, whether the gates are + * ordered, the unsorted input, and the baseline. * - * 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 dataset, the subset and the three columns are result-pool column ids, each naming the block + * that produced the column. The gates of the ladder, the input, the exclusions 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. A project template names its blocks, and a block + * created from one receives every one of these pointing at the blocks made from the same entries, + * so a project made from a template computes what the original one did. A lab that runs the same + * FACS ladder over library after library may leave the dataset out of a template and pick it + * afterwards. * * **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, @@ -25,20 +35,15 @@ import { name, version } from "../package.json" with { type: "json" }; * act of making the block runnable. Carrying the snapshots keeps the template usable on * arrival. * - * Left out, and why: - * - * - **`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. + * Left out: view state — `customBlockLabel`, the table states and `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 = { + abundanceRef?: ColumnUniversalId; + filterRef?: ColumnUniversalId; conditionColumnRef?: ColumnUniversalId; gateColumnRef?: ColumnUniversalId; sortFractionColumnRef?: ColumnUniversalId; @@ -46,6 +51,12 @@ export type BlockParams = { gateValues?: ColumnValueId[]; gateColumnLabel?: string; conditionValues?: ColumnValueId[]; + excludedConditions?: ColumnValueId[]; + readFloor?: number; + gatesOrdered?: boolean; + inputGate?: ColumnValueId; + baseline?: BaselineOption; + baselineSequence?: string; }; // Identity (`name`/`version`) comes from this package's own `package.json`, so the on-wire @@ -78,6 +89,8 @@ function parseInitializationParams(value: unknown): BlockParams { assertParamsObject(value); const { + abundanceRef, + filterRef, conditionColumnRef, gateColumnRef, sortFractionColumnRef, @@ -85,9 +98,17 @@ function parseInitializationParams(value: unknown): BlockParams { gateValues, gateColumnLabel, conditionValues, + excludedConditions, + readFloor, + gatesOrdered, + inputGate, + baseline, + baselineSequence, } = value; return { + abundanceRef: optionalColumnRef(abundanceRef, "abundanceRef", "a dataset"), + filterRef: optionalColumnRef(filterRef, "filterRef", "a subset column"), conditionColumnRef: optionalColumnRef(conditionColumnRef, "conditionColumnRef"), gateColumnRef: optionalColumnRef(gateColumnRef, "gateColumnRef"), sortFractionColumnRef: optionalColumnRef(sortFractionColumnRef, "sortFractionColumnRef"), @@ -95,18 +116,37 @@ function parseInitializationParams(value: unknown): BlockParams { gateValues: optionalValueList(gateValues, "gateValues"), gateColumnLabel: optionalString(gateColumnLabel, "gateColumnLabel"), conditionValues: optionalValueList(conditionValues, "conditionValues"), + excludedConditions: optionalValueList(excludedConditions, "excludedConditions"), + readFloor: optionalNumber(readFloor, "readFloor"), + gatesOrdered: optionalBoolean(gatesOrdered, "gatesOrdered"), + inputGate: optionalValue(inputGate, "inputGate"), + baseline: optionalEnum(baseline, BASELINE_OPTIONS, "baseline"), + baselineSequence: optionalString(baselineSequence, "baselineSequence"), }; } /** - * 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. + * A 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): ColumnUniversalId | undefined { +function optionalColumnRef( + value: unknown, + field: string, + what = "a metadata column", +): ColumnUniversalId | undefined { if (value === undefined) return undefined; if (!isGlobalPObjectId(value)) { - throw new Error(`'${field}' must be a metadata column, written as ${OUTPUT_ID}.`); + throw new Error(`'${field}' must be ${what}, written as ${OUTPUT_ID}.`); + } + return value; +} + +/** One picked value of a column, written as a column value id; a plain value is refused. */ +function optionalValue(value: unknown, field: string): ColumnValueId | undefined { + if (value === undefined) return undefined; + if (!isColumnValueId(value)) { + throw new Error(`'${field}' must be a column value, written as a column value id.`); } return value; } @@ -129,4 +169,32 @@ function optionalString(value: unknown, field: string): string | undefined { return value; } +function optionalNumber(value: unknown, field: string): number | undefined { + if (value === undefined) return undefined; + if (typeof value !== "number" || !Number.isFinite(value)) { + throw new Error(`'${field}' must be a number.`); + } + return value; +} + +function optionalBoolean(value: unknown, field: string): boolean | undefined { + if (value === undefined) return undefined; + if (typeof value !== "boolean") throw new Error(`'${field}' must be true or false.`); + return value; +} + +function optionalEnum( + value: unknown, + allowed: readonly T[], + field: string, +): T | undefined { + if (value === undefined) return undefined; + if (typeof value !== "string" || !(allowed as readonly string[]).includes(value)) { + throw new Error(`'${field}' must be one of ${allowed.join(", ")}.`); + } + return value as T; +} + +const BASELINE_OPTIONS: readonly BaselineOption[] = ["wild-type", "synonymous", "sequence"]; + const OUTPUT_ID = "the result-pool id of another block's output"; diff --git a/model/src/dataModel.ts b/model/src/dataModel.ts index 8337393..d1ab677 100644 --- a/model/src/dataModel.ts +++ b/model/src/dataModel.ts @@ -41,6 +41,8 @@ export const blockDataModel = new DataModelBuilder({ kind }) // projects the same fields back out; the two must name the same set. `params` is optional, // so every field keeps a default. .init(({ params }) => ({ + abundanceRef: params?.abundanceRef, + filterRef: params?.filterRef, conditionColumnRef: params?.conditionColumnRef, gateColumnRef: params?.gateColumnRef, sortFractionColumnRef: params?.sortFractionColumnRef, @@ -48,10 +50,16 @@ export const blockDataModel = new DataModelBuilder({ kind }) gateValues: params?.gateValues ?? [], gateColumnLabel: params?.gateColumnLabel, conditionValues: params?.conditionValues ?? [], + // The two facts and the baseline are absent rather than defaulted: an absent input means + // no enrichment, and an absent order flag means ordered. + excludedConditions: params?.excludedConditions ?? [], + readFloor: params?.readFloor, + gatesOrdered: params?.gatesOrdered, + inputGate: params?.inputGate, + baseline: params?.baseline, + baselineSequence: params?.baselineSequence, - // 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. - excludedConditions: [], + // Not init params: view state. See the kind. customBlockLabel: "", resultsTableState: createPlDataTableStateV2(), ntResultsTableState: createPlDataTableStateV2(), diff --git a/model/src/index.ts b/model/src/index.ts index a007306..7e1bffe 100644 --- a/model/src/index.ts +++ b/model/src/index.ts @@ -350,6 +350,8 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } * unrunnable, and making it runnable destroys the ladder. */ .templateParams((data) => ({ + abundanceRef: data.abundanceRef, + filterRef: data.filterRef, conditionColumnRef: data.conditionColumnRef, gateColumnRef: data.gateColumnRef, sortFractionColumnRef: data.sortFractionColumnRef, @@ -357,6 +359,12 @@ export const platforma = BlockModelV3.create({ dataModel: blockDataModel, kind } gateValues: data.gateValues, gateColumnLabel: data.gateColumnLabel, conditionValues: data.conditionValues, + excludedConditions: data.excludedConditions, + readFloor: data.readFloor, + gatesOrdered: data.gatesOrdered, + inputGate: data.inputGate, + baseline: data.baseline, + baselineSequence: data.baselineSequence, })) /** Constant. What an instance is configured for belongs in the subtitle. */ diff --git a/model/src/stored_data.ts b/model/src/stored_data.ts index c070892..bc86898 100644 --- a/model/src/stored_data.ts +++ b/model/src/stored_data.ts @@ -1,6 +1,6 @@ import type { GraphMakerState } from "@milaboratories/graph-maker"; import type { PlDataTableStateV2, PlRef } from "@platforma-sdk/model"; -import type { BaselineOption } from "./types"; +import type { BaselineOption } from "@platforma-open/milaboratories.sort-seq-analysis.kind"; /** * Data as stored at `Ver_2026_09_21`: the dataset as a ref to an upstream output, the condition, diff --git a/model/src/types.ts b/model/src/types.ts index acfe264..8f8c07f 100644 --- a/model/src/types.ts +++ b/model/src/types.ts @@ -1,4 +1,5 @@ import type { GraphMakerState } from "@milaboratories/graph-maker"; +import type { BaselineOption } from "@platforma-open/milaboratories.sort-seq-analysis.kind"; import type { ColumnUniversalId, ColumnValueId, PlDataTableStateV2 } from "@platforma-sdk/model"; /** @@ -7,9 +8,6 @@ import type { ColumnUniversalId, ColumnValueId, PlDataTableStateV2 } from "@plat */ export type RunMode = "gate-ranking" | "enrichment"; -/** What a per-gate enrichment is read against. `synonymous` needs the nucleotide grain. */ -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 the args JSON carries only what the run uses.