@platforma-open/milaboratories.top-antibodies.workflow 4.0.3 → 4.1.0

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
  WARN  Issue while reading "/home/runner/work/antibody-tcr-lead-selection/antibody-tcr-lead-selection/.npmrc". Failed to replace env in config: ${NPMJS_TOKEN}
 
-> @platforma-open/milaboratories.top-antibodies.workflow@4.0.3 build /home/runner/work/antibody-tcr-lead-selection/antibody-tcr-lead-selection/workflow
+> @platforma-open/milaboratories.top-antibodies.workflow@4.1.0 build /home/runner/work/antibody-tcr-lead-selection/antibody-tcr-lead-selection/workflow
 > shx rm -rf dist && pl-tengo check && pl-tengo build
 
 Processing "src/assembling-fasta.tpl.tengo"...
@@ -11,6 +11,7 @@ Processing "src/pf-spectratype-conv.lib.tengo"...
 Processing "src/pf-vj-usage-conv.lib.tengo"...
 Processing "src/sampled-cols-conv.lib.tengo"...
 Processing "src/sampled-export-conv.lib.tengo"...
+Processing "src/selection-stage-conv.lib.tengo"...
 Processing "src/utils.lib.tengo"...
 No syntax errors found.
   info: Compiling 'dist'...
@@ -19,6 +20,7 @@ No syntax errors found.
   info:   - writing /home/runner/work/antibody-tcr-lead-selection/antibody-tcr-lead-selection/workflow/dist/tengo/lib/pf-vj-usage-conv.lib.tengo
   info:   - writing /home/runner/work/antibody-tcr-lead-selection/antibody-tcr-lead-selection/workflow/dist/tengo/lib/sampled-cols-conv.lib.tengo
   info:   - writing /home/runner/work/antibody-tcr-lead-selection/antibody-tcr-lead-selection/workflow/dist/tengo/lib/sampled-export-conv.lib.tengo
+  info:   - writing /home/runner/work/antibody-tcr-lead-selection/antibody-tcr-lead-selection/workflow/dist/tengo/lib/selection-stage-conv.lib.tengo
   info:   - writing /home/runner/work/antibody-tcr-lead-selection/antibody-tcr-lead-selection/workflow/dist/tengo/lib/utils.lib.tengo
   info:   - writing /home/runner/work/antibody-tcr-lead-selection/antibody-tcr-lead-selection/workflow/dist/tengo/tpl/assembling-fasta.plj.gz
   info:   - writing /home/runner/work/antibody-tcr-lead-selection/antibody-tcr-lead-selection/workflow/dist/tengo/tpl/filter-and-sample.plj.gz

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @platforma-open/milaboratories.top-antibodies.workflow
 
+## 4.1.0
+
+### Minor Changes
+
+- b812c7d: Track which filter step eliminated each clonotype (or marks it as a
+  survivor) and visualize the attrition in a new Selection page. The
+  sample-clonotypes script emits a selectionStage column per clone; the
+  workflow exposes it as selectionStagePf, and the block UI renders it
+  via GraphMaker's selection chart type.
+
 ## 4.0.3
 
 ### Patch Changes

package/dist/tengo/lib/selection-stage-conv.lib.tengo

@@ -0,0 +1,33 @@
+ll := import("@platforma-sdk/workflow-tengo:ll")
+json := import("json")
+
+getColumns := func(datasetSpec, valueLabels) {
+  return {
+    axes: [
+      {
+        column: "clonotypeKey",
+        spec: datasetSpec.axesSpec[1]
+      }],
+    columns: [{
+      column: "selectionStage",
+      id: "selectionStage",
+      allowNA: false,
+      spec: {
+        name: "pl7.app/selectionStage",
+        valueType: "Int",
+        domain: {},
+        annotations: {
+          "pl7.app/label": "Selection Stage",
+          "pl7.app/valueLabels": string(json.encode(valueLabels)),
+          "pl7.app/isDiscreteFilter": "true"
+        }
+      }
+    }],
+    storageFormat: "Parquet",
+    partitionKeyLength: 0
+  }
+}
+
+export ll.toStrict({
+  getColumns: getColumns
+})

package/dist/tengo/lib/utils.lib.tengo

@@ -742,6 +742,31 @@ buildFilterTraceLabel := func(filters, columns) {
     return result
 }
 
+
+
+
+
+
+
+
+
+buildFilterStageNames := func(filters, columns) {
+    names := []
+    for filter in filters {
+
+        if !is_undefined(filter.value) && !is_undefined(columns.getColumn(filter.value.column).spec) {
+            colSpec := columns.getColumn(filter.value.column).spec
+            label := colSpec.name
+            colLabel := colSpec.annotations["pl7.app/label"]
+            if !is_undefined(colLabel) && colLabel != "" {
+                label = colLabel
+            }
+            names = names + [label]
+        }
+    }
+    return names
+}
+
 export {
     clusterAxisDomainsMatch: clusterAxisDomainsMatch,
     findMatchingLinkerIndex: findMatchingLinkerIndex,
@@ -755,5 +780,6 @@ export {
     initializeAssemSeqTable: initializeAssemSeqTable,
     formatFilterDescription: formatFilterDescription,
     buildFilterTraceLabel: buildFilterTraceLabel,
+    buildFilterStageNames: buildFilterStageNames,
     inVivoScoreSourceColumns: inVivoScoreSourceColumns
 }

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@platforma-open/milaboratories.top-antibodies.workflow",
-  "version": "4.0.3",
+  "version": "4.1.0",
   "type": "module",
   "description": "Block Workflow",
   "dependencies": {
     "@platforma-sdk/workflow-tengo": "5.21.0",
     "@platforma-open/milaboratories.software-anarci": "^0.0.3",
     "@platforma-open/milaboratories.top-antibodies.sample-clonotypes": "2.1.3",
+    "@platforma-open/milaboratories.top-antibodies.assembling-fasta": "1.3.3",
     "@platforma-open/milaboratories.top-antibodies.spectratype": "1.8.4",
     "@platforma-open/milaboratories.top-antibodies.umap": "1.2.4",
-    "@platforma-open/milaboratories.top-antibodies.anarci-kabat": "1.4.4",
-    "@platforma-open/milaboratories.top-antibodies.assembling-fasta": "1.3.3"
+    "@platforma-open/milaboratories.top-antibodies.anarci-kabat": "1.4.4"
   },
   "devDependencies": {
     "@platforma-sdk/tengo-builder": "2.5.26"

package/src/filter-and-sample.tpl.tengo

@@ -8,9 +8,10 @@ pSpec := import("@platforma-sdk/workflow-tengo:pframes.spec")
 render := import("@platforma-sdk/workflow-tengo:render")
 sampledColsConv := import(":sampled-cols-conv")
 sampledExportConv := import(":sampled-export-conv")
+selectionStageConv := import(":selection-stage-conv")
 json := import("json")
 
-self.defineOutputs("sampledRows", "finalClonotypes", "sampledColumnsExport")
+self.defineOutputs("sampledRows", "finalClonotypes", "sampledColumnsExport", "selectionStagePf")
 
 self.body(func(inputs) {
 
@@ -22,8 +23,8 @@ self.body(func(inputs) {
 
     outputs := {}
     finalClonotypes := undefined
-    
-    // Run filtering script
+
+    // Run filtering script with selection stage tracking
     filterResult := exec.builder().
         software(assets.importSoftware("@platforma-open/milaboratories.top-antibodies.sample-clonotypes:filter")).
         mem("16GiB").
@@ -32,13 +33,16 @@ self.body(func(inputs) {
         arg("--parquet").arg("clonotypes.parquet").
         arg("--out").arg("filteredClonotypes.parquet").
         arg("--filter-map").arg(string(json.encode(filterMap))).
+        arg("--emit-selection").arg("selection.parquet").
         saveFile("filteredClonotypes.parquet").
+        saveFile("selection.parquet").
         printErrStreamToStdout().
         cache(24 * 60 * 60 * 1000).
         run()
 
-    // Save filtered parquet file
+    // Save filtered parquet file and selection stage data
     filteredClonotypes := filterResult.getFile("filteredClonotypes.parquet")
+    selectionParquet := filterResult.getFile("selection.parquet")
 
     // Check if In Vivo Score is in the ranking map
     hasInVivoScore := false
@@ -60,15 +64,18 @@ self.body(func(inputs) {
 	if topClonotypes != undefined {
 
 		////////// Top Clonotypes Sampling //////////
-		// Run sampling script on filtered data
+		// Run sampling script on filtered data, with selection stage merging
 		builder := exec.builder().
 			software(assets.importSoftware("@platforma-open/milaboratories.top-antibodies.sample-clonotypes:main")).
 			mem("16GiB").
 			cpu(1).
 			addFile("filteredClonotypes.parquet", filteredClonotypes).
+			addFile("selection_in.parquet", selectionParquet).
 			arg("--parquet").arg("filteredClonotypes.parquet").
 			arg("--n").arg(string(topClonotypes)).
-			arg("--ranking-map").arg(string(json.encode(rankingMap)))
+			arg("--ranking-map").arg(string(json.encode(rankingMap))).
+			arg("--selection-in").arg("selection_in.parquet").
+			arg("--selection-out").arg("selection_out.parquet")
 
 		// Add diversification column if provided
 		if inputs.diversificationColumn != undefined && inputs.diversificationColumn != "" {
@@ -78,29 +85,57 @@ self.body(func(inputs) {
 		sampleClones := builder.
 			arg("--out").arg("sampledClonotypes_top.parquet").
 			saveFile("sampledClonotypes_top.parquet").
+			saveFile("selection_out.parquet").
 			printErrStreamToStdout().
 			cache(24 * 60 * 60 * 1000).
 			run()
 
 		// Save top clonotypes parquet file
 		finalClonotypes = sampleClones.getFile("sampledClonotypes_top.parquet")
-		
+		// Updated selection stages with "Selected" stage
+		selectionParquet = sampleClones.getFile("selection_out.parquet")
+
 		// Store outputs
         sampledColsParams := sampledColsConv.getColumns(datasetSpec, true, hasInVivoScore) // Add ranking column
 		sampledColumnsPf := xsv.importFile(finalClonotypes, "parquet", sampledColsParams,
 											{cpu: 1, mem: "16GiB"})
 		outputs["sampledRows"] = pframes.exportFrame(sampledColumnsPf)
-	} 
+	}
 
     outputs["finalClonotypes"] = finalClonotypes
 
+    // Build valueLabels for selectionStage from filter stage names
+    filterStageNames := inputs.filterStageNames
+    valueLabels := {}
+    stageIdx := 1
+    if !is_undefined(filterStageNames) {
+        for name in filterStageNames {
+            valueLabels[string(stageIdx)] = name
+            stageIdx = stageIdx + 1
+        }
+    }
+
+    if topClonotypes != undefined {
+        valueLabels[string(stageIdx)] = "Filtered"
+        valueLabels[string(stageIdx + 1)] = "Selected"
+    } else {
+        valueLabels[string(stageIdx)] = "Passed Filters"
+    }
+
+    // Import selection stage parquet as selectionStage PColumn
+    selectionStageParams := selectionStageConv.getColumns(datasetSpec, valueLabels)
+    selectionStagePf := xsv.importFile(selectionParquet, "parquet", selectionStageParams,
+                                        {cpu: 1, mem: "16GiB"})
+    // Expose as a dedicated output for the Selection Plot page's pre-bound pframe.
+    outputs["selectionStagePf"] = pframes.exportFrame(selectionStagePf)
+
     // Export only the sampling column to be used as a filter downstream
     sampledExportsParams := sampledExportConv.getColumns(datasetSpec, filterMap,
         rankingMap, inputs.diversificationColumn, topClonotypes)
     sampledColumnsOnlyPf := xsv.importFile(finalClonotypes, "parquet", sampledExportsParams,
                                         {cpu: 1, mem: "16GiB"})
 
-    // Create trace with filter descriptions and inject into exported column
+    // Create trace with filter descriptions and inject into exported columns
     traceLabel := inputs.filterTraceLabel
     if is_undefined(traceLabel) || traceLabel == "" {
         traceLabel = "Selected Leads"
@@ -117,6 +152,7 @@ self.body(func(inputs) {
         })
     exportPf := pframes.pFrameBuilder()
     exportPf.add("link", trace.inject(sampledColumnsOnlyPf["link.spec"]), sampledColumnsOnlyPf["link.data"])
+    exportPf.add("selectionStage", trace.inject(selectionStagePf["selectionStage.spec"]), selectionStagePf["selectionStage.data"])
     outputs["sampledColumnsExport"] = exportPf.build()
 
     return outputs

package/src/main.tpl.tengo

@@ -180,6 +180,8 @@ wf.body(func(args) {
 
             // Build trace label from filter descriptions
             filterTraceLabel := utils.buildFilterTraceLabel(args.filters, columns)
+            // Build per-filter stage names for Selection Plot
+            filterStageNames := utils.buildFilterStageNames(args.filters, columns)
 
             // Use ender.create to call the filter-clonotypes template
             filterSampleResult := render.create(filterAndSampleTpl, {
@@ -193,6 +195,7 @@ wf.body(func(args) {
                 topClonotypes: args.topClonotypes,
                 diversificationColumn: clusterColumnHeader,
                 filterTraceLabel: filterTraceLabel,
+                filterStageNames: filterStageNames,
                 customBlockLabel: args.customBlockLabel
             })
 
@@ -205,6 +208,9 @@ wf.body(func(args) {
             // Export only the sampling column for downstream (built inside sub-template to avoid hang)
             exports["sampledColumnsPf"] = filterSampleResult.output("sampledColumnsExport", 24 * 60 * 60 * 1000)
 
+            // Selection stage pframe for the Selection Plot page's pre-bound input
+            outputs["selectionStagePf"] = filterSampleResult.output("selectionStagePf", 24 * 60 * 60 * 1000)
+
             // CDR3 spectratype, V/J gene usage, and Kabat numbering are VDJ-only — skip for peptide inputs.
             if !isPeptide {
                 ////////// CDR3 Length Calculation //////////

package/src/selection-stage-conv.lib.tengo

@@ -0,0 +1,33 @@
+ll := import("@platforma-sdk/workflow-tengo:ll")
+json := import("json")
+
+getColumns := func(datasetSpec, valueLabels) {
+  return {
+    axes: [
+      {
+        column: "clonotypeKey",
+        spec: datasetSpec.axesSpec[1]
+      }],
+    columns: [{
+      column: "selectionStage",
+      id: "selectionStage",
+      allowNA: false,
+      spec: {
+        name: "pl7.app/selectionStage",
+        valueType: "Int",
+        domain: {},
+        annotations: {
+          "pl7.app/label": "Selection Stage",
+          "pl7.app/valueLabels": string(json.encode(valueLabels)),
+          "pl7.app/isDiscreteFilter": "true"
+        }
+      }
+    }],
+    storageFormat: "Parquet",
+    partitionKeyLength: 0
+  }
+}
+
+export ll.toStrict({
+  getColumns: getColumns
+})

package/src/utils.lib.tengo

@@ -742,6 +742,31 @@ buildFilterTraceLabel := func(filters, columns) {
     return result
 }
 
+/**
+ * Builds an ordered list of filter stage names for the Selection Plot valueLabels.
+ * Returns one label per filter, in the same order filters are applied.
+ *
+ * @param filters - Array of filter objects from block args
+ * @param columns - PBundle to look up column specs for labels
+ * @return Array of strings, one per filter stage
+ */
+buildFilterStageNames := func(filters, columns) {
+    names := []
+    for filter in filters {
+        // Same guard as initializeCloneTable: skip filters with missing upstream columns
+        if !is_undefined(filter.value) && !is_undefined(columns.getColumn(filter.value.column).spec) {
+            colSpec := columns.getColumn(filter.value.column).spec
+            label := colSpec.name
+            colLabel := colSpec.annotations["pl7.app/label"]
+            if !is_undefined(colLabel) && colLabel != "" {
+                label = colLabel
+            }
+            names = names + [label]
+        }
+    }
+    return names
+}
+
 export {
     clusterAxisDomainsMatch: clusterAxisDomainsMatch,
     findMatchingLinkerIndex: findMatchingLinkerIndex,
@@ -755,5 +780,6 @@ export {
     initializeAssemSeqTable: initializeAssemSeqTable,
     formatFilterDescription: formatFilterDescription,
     buildFilterTraceLabel: buildFilterTraceLabel,
+    buildFilterStageNames: buildFilterStageNames,
     inVivoScoreSourceColumns: inVivoScoreSourceColumns
 }