@platforma-open/milaboratories.mixcr-clonotyping-2.workflow 3.24.5 → 3.25.0

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
  WARN  Issue while reading "/home/runner/work/mixcr-clonotyping/mixcr-clonotyping/.npmrc". Failed to replace env in config: ${NPMJS_TOKEN}
 
-> @platforma-open/milaboratories.mixcr-clonotyping-2.workflow@3.24.5 build /home/runner/work/mixcr-clonotyping/mixcr-clonotyping/workflow
+> @platforma-open/milaboratories.mixcr-clonotyping-2.workflow@3.25.0 build /home/runner/work/mixcr-clonotyping/mixcr-clonotyping/workflow
 > shx rm -rf dist && pl-tengo check && pl-tengo build
 
   info: Skipping unknown file type: test/columns.test.ts

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @platforma-open/milaboratories.mixcr-clonotyping.workflow
 
+## 3.25.0
+
+### Minor Changes
+
+- 979cbf8: Add descriptions to key columns from QC table and include number of clonotypes dropped from un-paired cells
+
+## 3.24.6
+
+### Patch Changes
+
+- eea91d6: Filter non productive sequences for single cell data
+
 ## 3.24.5
 
 ### Patch Changes

package/dist/tengo/lib/qc-report-columns.lib.tengo

@@ -615,7 +615,8 @@ getQcReportColumns := func(hasUmi, isSingleCell, sampleIdAxisSpec, chains, cellT
                 "pl7.app/min": "0",
                 "pl7.app/table/orderPriority": "109000",
                 "pl7.app/table/visibility": "default",
-                "pl7.app/label": "Total Clonotypes"
+                "pl7.app/label": "Total Clonotypes",
+                "pl7.app/description": "Sum of unique clonotypes across all chains. In single-cell mode, only clonotypes from paired cells are counted."
             }
         }
     },
@@ -818,7 +819,8 @@ getQcReportColumns := func(hasUmi, isSingleCell, sampleIdAxisSpec, chains, cellT
                 "pl7.app/min": "0",
                 "pl7.app/table/orderPriority": "107900",
                 "pl7.app/table/visibility": "default",
-                "pl7.app/label": "Total number of cells (with paired chains)"
+                "pl7.app/label": "Total number of cells (with paired chains)",
+                "pl7.app/description": "Cells detected with at least two distinct chains (e.g. heavy and light)."
             }
         }
     }]
@@ -838,7 +840,8 @@ getQcReportColumns := func(hasUmi, isSingleCell, sampleIdAxisSpec, chains, cellT
                     "pl7.app/min": "0",
                     "pl7.app/table/orderPriority": string(n),
                     "pl7.app/table/visibility": "default",
-                    "pl7.app/label": "Clonotypes by Chain " + chain
+                    "pl7.app/label": "Clonotypes by Chain " + chain,
+                    "pl7.app/description": "Number of unique clonotypes for this chain (paired cells only). Includes secondary chain rearrangements."
                 }
             }
         }]
@@ -846,6 +849,25 @@ getQcReportColumns := func(hasUmi, isSingleCell, sampleIdAxisSpec, chains, cellT
     }
 
 
+    singleCellColumns += [{
+        column: "clonotypesDroppedUnpaired",
+        id: "clonotypes-dropped-unpaired",
+        allowNA: true,
+        naRegex: "NaN",
+        spec: {
+            name: "mixcr.com/reports/singleCell/clonotypesDroppedUnpaired",
+            valueType: "Long",
+            annotations: {
+                "pl7.app/min": "0",
+                "pl7.app/table/orderPriority": "108150",
+                "pl7.app/table/visibility": "optional",
+                "pl7.app/label": "Clonotypes Dropped - Unpaired",
+                "pl7.app/description": "Clonotypes discarded because their cell lacked a paired chain."
+            }
+        }
+    }]
+
+
     singleCellColumns += [
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-open/milaboratories.mixcr-clonotyping-2.workflow",
-  "version": "3.24.5",
+  "version": "3.25.0",
   "description": "Tengo-based template",
   "dependencies": {
     "@platforma-sdk/workflow-tengo": "5.11.0",

package/src/export-report.tpl.tengo

@@ -374,29 +374,29 @@ self.body(func(inputs) {
         )
         perChainJoined = perChainJoined.join(chainAgg, { how: "left", on: ["sampleId"] })
     }
-    // Single-cell: compute per-sample cell pairing stats (both chains vs one chain)
+    // Single-cell: compute per-sample cell pairing stats and paired clonotype counts
     if isSingleCell && !is_undefined(singleCellChainTsvsData) {
-        // Expect two chains for receptor; if more, we count any cell having A1 and B1 as both
-        // Build a map of per-sample cellKey presence per chain
+        // Load all single-cell chain TSVs once with (sampleId, cellKey, clonotypeKey, chain)
         scDfs := []
         maps.forEach(singleCellChainTsvsData, func(chainName, chainFiles) {
             maps.forEach(chainFiles.inputs(), func(key, f) {
                 sampleId := json.decode(key)[0]
-                df := wf.frame(f, { xsvType: "tsv", inferSchema: false, schema: [ { column: "cellKey", type: "String" } ] })
-                df2 := df.select(
+                df := wf.frame(f, { xsvType: "tsv", inferSchema: false, schema: [ { column: "cellKey", type: "String" }, { column: "clonotypeKey", type: "String" } ] })
+                scDfs = append(scDfs, df.select(
                     pt.lit(sampleId).alias("sampleId"),
-                    pt.col("cellKey").alias("cellKey"),
+                    pt.col("cellKey"),
+                    pt.col("clonotypeKey"),
                     pt.lit(chainName).alias("chain")
-                )
-                scDfs = append(scDfs, df2)
+                ))
             })
         })
         if len(scDfs) > 0 {
             scAll := len(scDfs) > 1 ? pt.concat(scDfs) : scDfs[0]
+
             // Count cells per sample across all chains (unique cellKey)
             cellsPerSample := scAll.groupBy("sampleId").agg(pt.col("cellKey").nUnique().alias("scCellsTotal"))
 
-            // Cells paired across different chains: require the same cellKey to appear in >1 distinct chains per sample
+            // Cells paired across different chains: cellKey appears in >1 distinct chain
             cellsPerSampleChainCounts := scAll.groupBy("sampleId", "cellKey").agg(pt.col("chain").nUnique().alias("_numChains"))
             bothChainCells := cellsPerSampleChainCounts.filter(pt.col("_numChains").gt(1)).groupBy("sampleId").agg(pt.col("cellKey").count().alias("scCellsBothChains"))
             pairedKeys := cellsPerSampleChainCounts.filter(pt.col("_numChains").gt(1)).select(pt.col("sampleId"), pt.col("cellKey"))
@@ -404,31 +404,20 @@ self.body(func(inputs) {
             perChainJoined = perChainJoined.join(cellsPerSample, { how: "left", on: ["sampleId"] })
             perChainJoined = perChainJoined.join(bothChainCells, { how: "left", on: ["sampleId"] })
 
-            // Recompute per-chain clonotype counts using only paired cells
+            // Filter to paired cells only
+            scPaired := scAll.join(pairedKeys, { how: "inner", on: ["sampleId", "cellKey"] })
+
+            // Per-chain clonotype counts from paired cells
             perChainPairedJoined := perChainJoined
             totalPairedParts := []
             for chain in chains {
-                chainFiles := singleCellChainTsvsData[chain]
                 chainColPaired := "clonotypesByChain." + chain + ".paired"
-                if is_undefined(chainFiles) {
-                    perChainPairedJoined = perChainPairedJoined.withColumns(pt.lit(0).alias(chainColPaired))
-                    continue
-                }
-                parts := []
-                maps.forEach(chainFiles.inputs(), func(key, f) {
-                    sampleId := json.decode(key)[0]
-                    dfc := wf.frame(f, { xsvType: "tsv", inferSchema: false, schema: [ { column: "cellKey", type: "String" }, { column: "clonotypeKey", type: "String" } ] })
-                    dfc2 := dfc.select(pt.lit(sampleId).alias("sampleId"), pt.col("cellKey"), pt.col("clonotypeKey"))
-                    // join with paired keys for this sample
-                    dfcJoined := dfc2.join(pairedKeys, { how: "inner", on: ["sampleId", "cellKey"] })
-                    parts = append(parts, dfcJoined.select(pt.col("sampleId"), pt.col("clonotypeKey")))
-                })
-                if len(parts) == 0 {
+                if is_undefined(singleCellChainTsvsData[chain]) {
                     perChainPairedJoined = perChainPairedJoined.withColumns(pt.lit(0).alias(chainColPaired))
                     continue
                 }
-                partsDf := len(parts) > 1 ? pt.concat(parts) : parts[0]
-                chainAggPaired := partsDf.groupBy("sampleId").agg(pt.col("clonotypeKey").nUnique().alias(chainColPaired))
+                chainPaired := scPaired.filter(pt.col("chain").eq(chain))
+                chainAggPaired := chainPaired.groupBy("sampleId").agg(pt.col("clonotypeKey").nUnique().alias(chainColPaired))
                 perChainPairedJoined = perChainPairedJoined.join(chainAggPaired, { how: "left", on: ["sampleId"] })
                 totalPairedParts = append(totalPairedParts, chainAggPaired.select(pt.col("sampleId"), pt.col(chainColPaired).alias("__pairedPart")))
             }
@@ -440,6 +429,7 @@ self.body(func(inputs) {
             } else {
                 perChainJoined = perChainPairedJoined.withColumns(pt.lit(0).alias("exportedClonotypesPaired"))
             }
+
         } else {
             perChainJoined = perChainJoined.withColumns(pt.lit(0).alias("scCellsTotal"), pt.lit(0).alias("scCellsBothChains"))
         }
@@ -457,7 +447,8 @@ self.body(func(inputs) {
         }
         finalDf = finalDf.withColumns(
             pt.col("exportedClonotypesPaired").fillNull(0).cast("Long").alias("totalClonotypes"),
-            pt.col("readsUsedInClonotypesNew").fillNull(0).cast("Long").alias("readsUsedInClonotypes")
+            pt.col("readsUsedInClonotypesNew").fillNull(0).cast("Long").alias("readsUsedInClonotypes"),
+            pt.col("exportedClonotypes").fillNull(0).cast("Long").minus(pt.col("exportedClonotypesPaired").fillNull(0).cast("Long")).alias("clonotypesDroppedUnpaired")
         )
     } else {
         finalDf = finalDf.withColumns(

package/src/process-single-cell.tpl.tengo

@@ -123,6 +123,13 @@ self.body(func(inputs) {
 				alias("chainRank")
 		).withoutColumns("rawChainRank")
 
+		// Filter out non-productive chains so that cells with a non-productive
+		// primary chain will have no entry and get excluded by the downstream
+		// clonotypeKeyA1/B1 isNotNull filter.
+		dfWithChainRank = dfWithChainRank.filter(
+			pt.col(mainIsProductiveColumn).eq("true")
+		)
+
 		dfWithChainRank.save("output.tsv")
 
 		// Run the workflow

package/src/qc-report-columns.lib.tengo

@@ -615,7 +615,8 @@ getQcReportColumns := func(hasUmi, isSingleCell, sampleIdAxisSpec, chains, cellT
                 "pl7.app/min": "0",
                 "pl7.app/table/orderPriority": "109000",
                 "pl7.app/table/visibility": "default",
-                "pl7.app/label": "Total Clonotypes"
+                "pl7.app/label": "Total Clonotypes",
+                "pl7.app/description": "Sum of unique clonotypes across all chains. In single-cell mode, only clonotypes from paired cells are counted."
             }
         }
     },
@@ -818,7 +819,8 @@ getQcReportColumns := func(hasUmi, isSingleCell, sampleIdAxisSpec, chains, cellT
                 "pl7.app/min": "0",
                 "pl7.app/table/orderPriority": "107900",
                 "pl7.app/table/visibility": "default",
-                "pl7.app/label": "Total number of cells (with paired chains)"
+                "pl7.app/label": "Total number of cells (with paired chains)",
+                "pl7.app/description": "Cells detected with at least two distinct chains (e.g. heavy and light)."
             }
         }
     }]
@@ -838,13 +840,33 @@ getQcReportColumns := func(hasUmi, isSingleCell, sampleIdAxisSpec, chains, cellT
                     "pl7.app/min": "0",
                     "pl7.app/table/orderPriority": string(n),
                     "pl7.app/table/visibility": "default",
-                    "pl7.app/label": "Clonotypes by Chain " + chain
+                    "pl7.app/label": "Clonotypes by Chain " + chain,
+                    "pl7.app/description": "Number of unique clonotypes for this chain (paired cells only). Includes secondary chain rearrangements."
                 }
             }
         }]
         n -= 100
     }
 
+    // Clonotypes dropped because the cell was unpaired (single-chain only)
+    singleCellColumns += [{
+        column: "clonotypesDroppedUnpaired",
+        id: "clonotypes-dropped-unpaired",
+        allowNA: true,
+        naRegex: "NaN",
+        spec: {
+            name: "mixcr.com/reports/singleCell/clonotypesDroppedUnpaired",
+            valueType: "Long",
+            annotations: {
+                "pl7.app/min": "0",
+                "pl7.app/table/orderPriority": "108150",
+                "pl7.app/table/visibility": "optional",
+                "pl7.app/label": "Clonotypes Dropped - Unpaired",
+                "pl7.app/description": "Clonotypes discarded because their cell lacked a paired chain."
+            }
+        }
+    }]
+
     // Single Cell columns
     singleCellColumns += [
     // {