spec R1: apply PrimaryRef.filter clonotype subset

Spec R1 wording: "optional `PrimaryRef.filter` reduces the clonotype
set." Filter slot has been on the envelope since the chunk-1 work but
the workflow ignored it. Wire it through end-to-end:

Model: add `filterOptions` output surfacing compatible Boolean/Int
PColumns the upstream prediction block emits
(`pl7.app/structure/predictionSuccessful`, `pl7.app/structure/confident`).

UI: split `primaryRef` into two computeds. The new
`primaryRefFilter` drives a second `PlDropdownRef` in Settings;
`createPrimaryRef(col, filter)` rebuilds the envelope on either change.

Workflow: `wf.prepare` adds the filter as a `bb.addSingle(..., "filter")`
when set, sharing the PDB anchor's scClonotypeKey axis. `wf.body`
exports the resolved column via `xsv.exportFrame` and stages it as
`clonotype_filter.tsv` with a new `--clonotype-filter` CLI flag.

Python: loads the TSV into a `keep_clonotypes` set, parsing common
falsy spellings (`0`, `false`, `no`, `null`, empty, `0.0`). Skips
clonotypes outside the set before iteration. No-op when the user
didn't pick a filter (the in-block path stays the default).

Author: xnacly

model/src/index.ts

@@ -286,6 +286,18 @@ export const platforma = BlockModelV3.create(dataModel)
       },
     ]),
   )
+  // Spec R1 `PrimaryRef.filter` , surface Int/Boolean PColumns anchored on
+  // the same scClonotypeKey axis as the PDB column so the user can pick
+  // a subset filter (e.g. upstream `pl7.app/structure/predictionSuccessful`
+  // or `pl7.app/structure/confident`). The workflow stages whatever the
+  // user picks as a TSV sidecar and Python drops clonotypes whose value
+  // is falsy before iterating.
+  .output("filterOptions", (ctx) =>
+    ctx.resultPool.getOptions([
+      { name: "pl7.app/structure/predictionSuccessful" },
+      { name: "pl7.app/structure/confident" },
+    ]),
+  )
   // Spec R51 , per-clonotype scalar metrics table. PColumns come from the
   // PrimaryRef-path `scoresData` PFrame (axes: [scClonotypeKey]). Hidden
   // on the legacy single-PDB path (`scoresData` not emitted; resolve

software/liabilities-script/main.py

@@ -322,6 +322,12 @@ def main() -> None:
                          "provided, the per-clonotype value overrides the "
                          "in-block CDR3 Cα count as the R30 compactness "
                          "numerator (R5 / R29).")
+    ap.add_argument("--clonotype-filter", type=Path, default=None,
+                    dest="clonotype_filter_tsv",
+                    help="Optional TSV exported from a Boolean/Int PColumn "
+                         "(spec R1 `PrimaryRef.filter`). Clonotypes whose "
+                         "value is falsy (0, false, empty) are skipped "
+                         "before iteration.")
     args = ap.parse_args()
 
     if not args.pdb_dir.is_dir():
@@ -354,6 +360,28 @@ def main() -> None:
                     except (TypeError, ValueError):
                         continue
 
+    keep_clonotypes: set[str] | None = None
+    if args.clonotype_filter_tsv is not None and args.clonotype_filter_tsv.is_file():
+        with args.clonotype_filter_tsv.open() as fh:
+            reader = csv.DictReader(fh, delimiter="\t")
+            key_col = next((c for c in (reader.fieldnames or []) if "scClonotypeKey" in c), None)
+            val_col = next(
+                (c for c in (reader.fieldnames or []) if c != key_col),
+                None,
+            )
+            if key_col and val_col:
+                keep_clonotypes = set()
+                for r in reader:
+                    raw = (r.get(val_col) or "").strip().lower()
+                    if raw in {"", "0", "false", "no", "null"}:
+                        continue
+                    try:
+                        if float(raw) == 0.0:
+                            continue
+                    except ValueError:
+                        pass
+                    keep_clonotypes.add(r[key_col])
+
     out_buf = StringIO()
     writer = csv.writer(out_buf, delimiter="\t", lineterminator="\n")
     writer.writerow(_TSV_COLUMNS)
@@ -365,6 +393,8 @@ def main() -> None:
                 f"clonotypeKey<TAB>filename): {entry}"
             )
         clonotype_key, pdb_filename = entry
+        if keep_clonotypes is not None and clonotype_key not in keep_clonotypes:
+            continue
         pdb_path = args.pdb_dir / pdb_filename
         if not pdb_path.is_file():
             raise SystemExit(

ui/src/pages/MainPage.vue

@@ -94,14 +94,25 @@ const { runSummary, showRedAlert, showGatedAlert } = useRunSummaryAlerts(scoresT
 const settingsOpen = ref(!app.model.data.primaryRef?.column);
 
 // Spec R1 , `PrimaryRef` is a frozen `{__isPrimaryRef, column, filter?}`
-// envelope. `PlDropdownRef` deals in plain `PlRef`, so we expose the
-// inner `column` to the dropdown and rebuild the envelope on every
-// change via `createPrimaryRef`. The filter slot (R47) stays
-// `undefined` until subset selection is wired.
+// envelope. `PlDropdownRef` deals in plain `PlRef`, so we split into two
+// computeds: the primary column drives the dropdown over `pdbOptions`,
+// the optional filter PlRef narrows the clonotype set at workflow time.
+// Setting the column rebuilds the envelope; setting the filter merges it
+// onto the existing envelope (or no-ops if there's no column yet).
 const primaryRefColumn = computed<PlRef | undefined>({
   get: () => app.model.data.primaryRef?.column,
   set: (value) => {
-    app.model.data.primaryRef = value ? createPrimaryRef(value) : undefined;
+    app.model.data.primaryRef = value
+      ? createPrimaryRef(value, app.model.data.primaryRef?.filter)
+      : undefined;
+  },
+});
+const primaryRefFilter = computed<PlRef | undefined>({
+  get: () => app.model.data.primaryRef?.filter,
+  set: (value) => {
+    const col = app.model.data.primaryRef?.column;
+    if (!col) return;
+    app.model.data.primaryRef = createPrimaryRef(col, value);
   },
 });
 
@@ -170,6 +181,19 @@ const modalTitle = computed(() => {
         clearable
       />
 
+      <!-- Spec R1 `PrimaryRef.filter` , subset of clonotypes to analyze.
+           Compatible columns auto-discovered from the result pool
+           (`pl7.app/structure/predictionSuccessful`, `confident`); when
+           set, the workflow exports the column to a TSV sidecar and
+           Python skips clonotypes whose value is falsy. Optional; leave
+           clear to analyze every clonotype in the dataset. -->
+      <PlDropdownRef
+        v-model="primaryRefFilter"
+        :options="app.model.outputs.filterOptions ?? []"
+        label="Clonotype filter (optional)"
+        clearable
+      />
+
       <div
         :style="{
           display: 'grid',

workflow/src/main.tpl.tengo

@@ -27,11 +27,11 @@ liabilitiesSw := assets.importSoftware("@platforma-open/milabs.3d-structure-base
 
 wf.prepare(func(args) {
 	// Anchor on the PDB column so upstream enrichments sharing the
-	// scClonotypeKey axis (R2) auto-discover. R5/R29: cdrh3Length from
-	// upstream feeds the R30 compactness numerator instead of our
-	// REMARK 99 / scheme-fallback count. Optional: when the prediction
-	// block in the chain is older and doesn't emit cdrh3Length, the
-	// bundle yields no column and Python falls back to its in-block count.
+	// scClonotypeKey axis (R2) auto-discover. R5/R29: cdrh3Length feeds
+	// the R30 compactness numerator. R1 PrimaryRef.filter: when the
+	// user picks a filter PlRef, resolve it as a Single so wf.body can
+	// export it to a TSV sidecar; Python then skips clonotypes whose
+	// filter value is falsy.
 	bb := wf.createPBundleBuilder()
 	bb.ignoreMissingDomains()
 	bb.addAnchor("pdb", args.primaryRef.column)
@@ -41,6 +41,9 @@ wf.prepare(func(args) {
 			name: "pl7.app/structure/cdrh3Length"
 		},
 		"cdrh3Length")
+	if !is_undefined(args.primaryRef.filter) {
+		bb.addSingle(args.primaryRef.filter, "filter")
+	}
 
 	return {
 		resolvedPdb: wf.resolve(args.primaryRef.column, { errIfMissing: true }),
@@ -106,6 +109,17 @@ wf.body(func(args) {
 			arg("--cdrh3-lengths").arg("cdrh3_lengths.tsv")
 	}
 
+	// R1 PrimaryRef.filter: stage the picked filter column as a TSV
+	// sidecar; Python drops clonotypes whose filter value is falsy
+	// before iterating. Empty when the user didn't pick a filter.
+	filterCol := args.columns.getColumn("filter")
+	if !is_undefined(filterCol) {
+		filterTsv := xsv.exportFrame([filterCol], "tsv", { mem: "1GiB", cpu: 1 })
+		cmd = cmd.
+			addFile("clonotype_filter.tsv", filterTsv).
+			arg("--clonotype-filter").arg("clonotype_filter.tsv")
+	}
+
 	// Optional CLI knobs (R10 fallback path + R9 chain identity overrides).
 	// Empty strings are skipped so Python falls through to its defaults.
 	if !is_undefined(args.numberingScheme) && args.numberingScheme != "" {