@platforma-open/milaboratories.top-antibodies.workflow 1.16.0 → 1.17.1

package/src/utils.lib.tengo

@@ -90,7 +90,7 @@ findMatchingLinkerIndex := func(colsSpec, linkerColumns) {
  * @param datasetMainAxisName - Name of the main dataset axis (e.g., clonotype axis)
  * @param linkerColumns - List of linker columns to match against
  * @param clusterPropertyIdx - Current cluster property index counter
- * @return Map with keys: header, clusterAxisIdx, newClusterPropertyIdx
+ * @return Map with keys: isClusterProperty, isLinkerColumn, header, clusterAxisIdx, newClusterPropertyIdx
  */
 processRankingColumn := func(colsSpec, datasetMainAxisName, linkerColumns, clusterPropertyIdx) {
     axesNames := slices.map(colsSpec.axesSpec, func (a) { return a.name})
@@ -100,6 +100,7 @@ processRankingColumn := func(colsSpec, datasetMainAxisName, linkerColumns, clust
         // This is a clonotype property
         return {
             isClusterProperty: false,
+            isLinkerColumn: false,
             header: undefined,
             clusterAxisIdx: undefined,
             newClusterPropertyIdx: clusterPropertyIdx
@@ -112,11 +113,14 @@ processRankingColumn := func(colsSpec, datasetMainAxisName, linkerColumns, clust
     header := ""
     clusterAxisIdx := undefined
     newClusterPropertyIdx := clusterPropertyIdx
+    isLinkerColumn := false
     
     if linkerIdx != undefined {
-        // This column belongs to a linker - use the linker index
+        // This column belongs to a linker - header will be generated by caller
+        // to ensure uniqueness across multiple columns from same linker
         header = "Col_linker." + string(linkerIdx)
         clusterAxisIdx = linkerIdx
+        isLinkerColumn = true
     } else {
         // This is a generic cluster property (not associated with any linker)
         header = "Col_cluster." + string(clusterPropertyIdx)
@@ -126,14 +130,430 @@ processRankingColumn := func(colsSpec, datasetMainAxisName, linkerColumns, clust
     
     return {
         isClusterProperty: true,
+        isLinkerColumn: isLinkerColumn,
         header: header,
         clusterAxisIdx: clusterAxisIdx,
         newClusterPropertyIdx: newClusterPropertyIdx
     }
 }
 
+/**
+ * Builds sorted linker list in the same order as model.
+ * 
+ * @param columns - PBundle containing all columns
+ * @param datasetSpec - Dataset specification with axes
+ * @return List of linker columns sorted by axis position
+ */
+buildSortedLinkers := func(columns, datasetSpec) {
+    allLinkersUnsorted := columns.getColumns("linkers")
+    
+    // Collect linkers by axis position (same iteration order as model)
+    sortedLinkers := []
+    // First: linkers where clonotypeKey is in SECOND axis
+    for col in allLinkersUnsorted {
+        if datasetSpec.axesSpec[1].name == col.spec.axesSpec[1].name {
+            sortedLinkers = append(sortedLinkers, col)
+        }
+    }
+    // Then: linkers where clonotypeKey is in FIRST axis
+    for col in allLinkersUnsorted {
+        if datasetSpec.axesSpec[1].name == col.spec.axesSpec[0].name {
+            sortedLinkers = append(sortedLinkers, col)
+        }
+    }
+    
+    return sortedLinkers
+}
+
+/**
+ * Resolves cluster column reference to header name by matching against sortedLinkers.
+ * 
+ * @param args - Arguments containing clusterColumn
+ * @param columns - PBundle containing all columns
+ * @param sortedLinkers - List of linker columns in proper order
+ * @return Cluster column header string or undefined
+ */
+resolveClusterColumnHeader := func(args, columns, sortedLinkers) {
+    if is_undefined(args.clusterColumn) {
+        return undefined
+    }
+    
+    // Get the spec for the selected cluster column
+    selectedLinkerSpec := columns.getSpec(args.clusterColumn)
+    if is_undefined(selectedLinkerSpec) {
+        return undefined
+    }
+    
+    // Find the clusterId axis in the selected linker
+    selectedClusterIdAxis := undefined
+    for axis in selectedLinkerSpec.axesSpec {
+        if axis.name == "pl7.app/vdj/clusterId" {
+            selectedClusterIdAxis = axis
+            break
+        }
+    }
+    
+    if is_undefined(selectedClusterIdAxis) {
+        return undefined
+    }
+    
+    // Find matching linker by comparing clusterId axis domains
+    for linkerIdx, col in sortedLinkers {
+        // Get the clusterId axis from this linker
+        for axis in col.spec.axesSpec {
+            if axis.name == "pl7.app/vdj/clusterId" {
+                // Use clusterAxisDomainsMatch for proper domain comparison
+                if clusterAxisDomainsMatch(selectedClusterIdAxis, axis) {
+                    return "clusterAxis_" + string(linkerIdx) + "_0"
+                }
+            }
+        }
+    }
+    
+    return undefined
+}
+
+/**
+ * Initializes and builds complete clone table with all columns.
+ * Handles filters, ranking columns, linkers, cluster sizes, and fallback columns.
+ * 
+ * @param pframes - PFrames import
+ * @param columns - PBundle containing all columns
+ * @param args - Arguments containing filters, rankingOrder, clusterColumn
+ * @param datasetSpec - Dataset specification with axes
+ * @return Map with keys: cloneTable, filterMap, rankingMap, sortedLinkers, clusterColumnHeader, addedCols
+ */
+initializeCloneTable := func(pframes, columns, args, datasetSpec) {
+    // Build clonotype table
+    cloneTable := pframes.parquetFileBuilder()
+    cloneTable.setAxisHeader(datasetSpec.axesSpec[1], "clonotypeKey")
+    
+    // Build linker list in SAME ORDER as model
+    sortedLinkers := buildSortedLinkers(columns, datasetSpec)
+    
+    // Add Filters to table
+    addedAxes := []
+    filterMap := {}
+    rankingMap := {}
+    addedCols := false
+    
+    if len(args.filters) > 0 {
+        for i, filter in args.filters {
+            // we check for value presence and for actual pcolumn (cases where upstream block is deleted)
+            if filter.value != undefined && columns.getColumn(filter.value.column).spec != undefined {
+                // Columns added here might also be in ranking list, so we add default IDs
+                cloneTable.add(columns.getColumn(filter.value.column), 
+                                {header: "Filter_" + string(i), id: "filter_" + string(i)})
+                addedCols = true
+                // Store reference value and filter type associated to this column
+                filterMap["Filter_" + string(i)] = filter.filter
+                filterMap["Filter_" + string(i)]["valueType"] = columns.getSpec(filter.value.column).valueType
+            
+                // If column does not have main anchor axis we have to include theirs
+                colsSpec := columns.getSpec(filter.value.column)
+                axesNames := slices.map(colsSpec.axesSpec, func (a) { return a.name})
+                if !slices.hasElement(axesNames, datasetSpec.axesSpec[1].name) {
+                    for na, ax in colsSpec.axesSpec {
+                        if ax.name != datasetSpec.axesSpec[1].name {
+                            cloneTable.setAxisHeader(ax, "cluster_" + string(i) + string(na))
+                            addedAxes = append(addedAxes, ax.name)
+                        }
+                    }
+                }	
+            }
+        }
+    }
+
+    // Add ranking columns to table
+    clusterPropertyIdx := 0
+    clonotypePropertyIdx := 0
+    linkerColumnCounters := {}  // Track column count per linker index
+    
+    if len(args.rankingOrder) > 0 {
+        for i, col in args.rankingOrder {
+            // we check for value presence and for actual pcolumn (cases where upstream block is deleted)
+            if col.value != undefined && columns.getColumn(col.value.column).spec != undefined {
+                // Process the ranking column to determine header and cluster axis
+                colsSpec := columns.getSpec(col.value.column)
+                // Use sortedLinkers for consistent ordering with model
+                result := processRankingColumn(colsSpec, datasetSpec.axesSpec[1].name, sortedLinkers, clusterPropertyIdx)
+                
+                header := ""
+                if result.isClusterProperty {
+                    // Check if this column is from a linker
+                    if result.isLinkerColumn {
+                        // Track and use counter for this specific linker
+                        linkerKey := "linker_" + string(result.clusterAxisIdx)
+                        if is_undefined(linkerColumnCounters[linkerKey]) {
+                            linkerColumnCounters[linkerKey] = 0
+                        }
+                        counter := linkerColumnCounters[linkerKey]
+                        header = "Col_linker." + string(result.clusterAxisIdx) + "." + string(counter)
+                        linkerColumnCounters[linkerKey] = counter + 1
+                    } else {
+                        header = result.header
+                        clusterPropertyIdx = result.newClusterPropertyIdx
+                    }
+                    
+                    // Add cluster axis with matching index
+                    for na, ax in colsSpec.axesSpec {
+                        if ax.name != datasetSpec.axesSpec[1].name && !slices.hasElement(addedAxes, ax.name) {
+                            axisHeader := "cluster_" + string(result.clusterAxisIdx)
+                            cloneTable.setAxisHeader(ax, axisHeader)
+                            addedAxes = append(addedAxes, ax.name)
+                        }
+                    }
+                } else {
+                    header = "Col" + string(clonotypePropertyIdx)
+                    clonotypePropertyIdx = clonotypePropertyIdx + 1
+                }
+                
+                cloneTable.add(columns.getColumn(col.value.column), {header: header})
+                addedCols = true
+                rankingMap[header] = col.rankingOrder
+            }
+        }
+    }
+
+    // Get linker columns and add them to the table
+    linkerClusterIdAxesWithIdx := []
+    
+    for linkerIdx, col in sortedLinkers {
+        clusterIdAxis := undefined
+        if datasetSpec.axesSpec[1].name == col.spec.axesSpec[1].name {
+            // clonotypeKey is in second axis
+            cloneTable.add(col, {header: "linker." + string(linkerIdx)})
+            cloneTable.setAxisHeader(col.spec.axesSpec[0], "cluster_" + string(linkerIdx))
+            clusterIdAxis = col.spec.axesSpec[0]
+            addedCols = true
+        } else if datasetSpec.axesSpec[1].name == col.spec.axesSpec[0].name {
+            // clonotypeKey is in first axis
+            cloneTable.add(col, {header: "linker." + string(linkerIdx)})
+            cloneTable.setAxisHeader(col.spec.axesSpec[1], "cluster_" + string(linkerIdx))
+            clusterIdAxis = col.spec.axesSpec[1]
+            addedCols = true
+        }
+        // Collect clusterId axes from linker columns to match cluster size columns
+        if !is_undefined(clusterIdAxis) && clusterIdAxis.name == "pl7.app/vdj/clusterId" {
+            linkerClusterIdAxesWithIdx = append(linkerClusterIdAxesWithIdx, {
+                axis: clusterIdAxis,
+                linkerIdx: linkerIdx
+            })
+        }
+    }
+
+    // Add cluster size columns if available, matching linker columns' clusterId axes
+    if len(columns.getColumns("clusterSizes")) > 0 {
+        for col in columns.getColumns("clusterSizes") {
+            // Find the clusterId axis in this cluster size column
+            clusterSizeClusterIdAxis := undefined
+            for axis in col.spec.axesSpec {
+                if axis.name == "pl7.app/vdj/clusterId" {
+                    clusterSizeClusterIdAxis = axis
+                    break
+                }
+            }
+            
+            // Find matching linker index
+            matchingLinkerIdx := -1
+            if len(linkerClusterIdAxesWithIdx) > 0 && !is_undefined(clusterSizeClusterIdAxis) {
+                for entry in linkerClusterIdAxesWithIdx {
+                    linkerAxis := entry.axis
+                    // Compare domains - they must match exactly for same clustering run
+                    if clusterSizeClusterIdAxis.name == linkerAxis.name &&
+                       clusterSizeClusterIdAxis.type == linkerAxis.type &&
+                       clusterAxisDomainsMatch(clusterSizeClusterIdAxis, linkerAxis) {
+                        matchingLinkerIdx = entry.linkerIdx
+                        break
+                    }
+                }
+            }
+            
+            // Only add cluster size columns that match a linker column's clustering run
+            if matchingLinkerIdx >= 0 {
+                cloneTable.add(col, {header: "clusterSize." + string(matchingLinkerIdx)})
+                addedCols = true
+                // Add the cluster axis header using matching linker index
+                for axisIdx, axis in col.spec.axesSpec {
+                    if axis.name != datasetSpec.axesSpec[1].name {
+                        cloneTable.setAxisHeader(axis, "clusterAxis_" + string(matchingLinkerIdx) + "_" + string(axisIdx))
+                    }
+                }
+            }
+        }
+    }
+
+    // Fallback: if no columns added, add at least one CDR3 sequence column
+    if !addedCols {
+        cdr3Sequences := columns.getColumns("cdr3Sequences")
+        if len(cdr3Sequences) > 0 {
+            cloneTable.add(cdr3Sequences[0], {header: "cdr3_fallback"})
+            addedCols = true
+        }
+    }
+
+    // Build the table if we have columns
+    builtTable := undefined
+    clusterColumnHeader := undefined
+    if addedCols {
+        cloneTable.mem("16GiB")
+        cloneTable.cpu(1)
+        builtTable = cloneTable.build()
+        
+        // Resolve clusterColumn ref to header name
+        clusterColumnHeader = resolveClusterColumnHeader(args, columns, sortedLinkers)
+    }
+    
+    return {
+        cloneTable: builtTable,
+        filterMap: filterMap,
+        rankingMap: rankingMap,
+        sortedLinkers: sortedLinkers,
+        clusterColumnHeader: clusterColumnHeader,
+        addedCols: addedCols
+    }
+}
+
+/**
+ * Creates a header name with chain information for CDR3/gene columns.
+ * 
+ * @param col - Column specification
+ * @param baseHeaderName - Base name for the header (e.g., "cdr3Sequence", "vGene", "jGene")
+ * @param isSingleCell - Whether the data is single cell
+ * @return Header name with chain information
+ */
+makeHeaderName := func(col, baseHeaderName, isSingleCell) {
+    chainMapping := {
+        "IG": { "A": "Heavy", "B": "Light" },
+        "TCRAB": { "A": "TRA", "B": "TRB" },
+        "TCRGD": { "A": "TRG", "B": "TRD" }
+    }
+    
+    if isSingleCell {
+        chain := col.spec.domain["pl7.app/vdj/scClonotypeChain"]  // e.g., "A", "B"
+        receptor := col.spec.axesSpec[0].domain["pl7.app/vdj/receptor"]  // e.g., "IG", "TCRAB", "TCRGD"
+        chainLabel := chainMapping[receptor][chain]
+        return baseHeaderName + "." + chainLabel // e.g., "cdr3Sequence.Heavy"
+    } else {
+        // For bulk, if chain info is available (e.g. IGH, IGK, IGL)
+        chainFromDomain := col.spec.axesSpec[0].domain["pl7.app/vdj/chain"] // e.g. "IGH", "IGK"
+        if chainFromDomain != undefined {
+            return baseHeaderName + "." + chainFromDomain // e.g., "cdr3Sequence.IGH"
+        }
+    }
+    return baseHeaderName
+}
+
+/**
+ * Initializes and builds CDR3 sequence table with CDR3 sequences, V genes, and J genes.
+ * 
+ * @param pframes - PFrames import
+ * @param columns - PBundle containing all columns
+ * @param datasetSpec - Dataset specification with axes
+ * @param isSingleCell - Whether the data is single cell
+ * @return Built CDR3 sequence table
+ */
+initializeCdr3SeqTable := func(pframes, columns, datasetSpec, isSingleCell) {
+    cdr3SeqTable := pframes.parquetFileBuilder()
+    cdr3SeqTable.setAxisHeader(datasetSpec.axesSpec[1].name, "clonotypeKey")
+
+    // Process CDR3 sequences
+    cdr3Sequences := columns.getColumns("cdr3Sequences")
+    for col in cdr3Sequences {
+        headerName := makeHeaderName(col, "cdr3Sequence", isSingleCell)
+        if isSingleCell {
+            if col.spec.domain["pl7.app/vdj/scClonotypeChain/index"] == "primary" {
+                cdr3SeqTable.add(col, {header: headerName})
+            }
+        } else {
+            cdr3SeqTable.add(col, {header: headerName})
+        }
+    }
+
+    // Process V genes
+    vGenes := columns.getColumns("VGenes")
+    for col in vGenes {
+        headerName := makeHeaderName(col, "vGene", isSingleCell)
+        cdr3SeqTable.add(col, {header: headerName})
+    }
+
+    // Process J genes
+    jGenes := columns.getColumns("JGenes")
+    for col in jGenes {
+        headerName := makeHeaderName(col, "jGene", isSingleCell)
+        cdr3SeqTable.add(col, {header: headerName})
+    }
+
+    cdr3SeqTable.mem("16GiB")
+    cdr3SeqTable.cpu(1)
+    return cdr3SeqTable.build()
+}
+
+/**
+ * Detects bulk chain from sequence columns.
+ * 
+ * @param seqCols - List of sequence columns
+ * @return Chain string ("H" for Heavy, "KL" for Light)
+ */
+detectBulkChain := func(seqCols) {
+    chainDetected := "KL"
+    for col in seqCols {
+        ch := col.spec.axesSpec[0].domain["pl7.app/vdj/chain"] // e.g., IGHeavy, IGLight
+        if ch == "IGHeavy" { 
+            chainDetected = "H"
+            break 
+        }
+        if ch == "IGLight" { 
+            chainDetected = "KL" 
+        }
+    }
+    return chainDetected
+}
+
+/**
+ * Initializes and builds assembling sequence table with assembling AA sequences.
+ * 
+ * @param pframes - PFrames import
+ * @param columns - PBundle containing all columns
+ * @param datasetSpec - Dataset specification with axes
+ * @param isSingleCell - Whether the data is single cell
+ * @return Map with keys: assemSeqTable (built table), bulkChain, seqCols
+ */
+initializeAssemSeqTable := func(pframes, columns, datasetSpec, isSingleCell) {
+    assemSeqTable := pframes.parquetFileBuilder()
+    assemSeqTable.setAxisHeader(datasetSpec.axesSpec[1].name, "clonotypeKey")
+
+    seqCols := columns.getColumns("assemblingAaSeqs")
+    for col in seqCols {
+        headerName := makeHeaderName(col, "assemblingFeature", isSingleCell)
+        assemSeqTable.add(col, {header: headerName})
+    }
+
+    assemSeqTable.mem("16GiB")
+    assemSeqTable.cpu(1)
+    
+    // Detect bulk chain if needed
+    bulkChain := undefined
+    if !isSingleCell {
+        bulkChain = detectBulkChain(seqCols)
+    }
+    
+    return {
+        assemSeqTable: assemSeqTable.build(),
+        bulkChain: bulkChain,
+        seqCols: seqCols
+    }
+}
+
 export {
     clusterAxisDomainsMatch: clusterAxisDomainsMatch,
     findMatchingLinkerIndex: findMatchingLinkerIndex,
-    processRankingColumn: processRankingColumn
+    processRankingColumn: processRankingColumn,
+    buildSortedLinkers: buildSortedLinkers,
+    resolveClusterColumnHeader: resolveClusterColumnHeader,
+    initializeCloneTable: initializeCloneTable,
+    makeHeaderName: makeHeaderName,
+    initializeCdr3SeqTable: initializeCdr3SeqTable,
+    detectBulkChain: detectBulkChain,
+    initializeAssemSeqTable: initializeAssemSeqTable
 }

package/index.d.ts

@@ -1,4 +0,0 @@
-declare type TemplateFromFile = { readonly type: "from-file"; readonly path: string; };
-declare type TplName = "main";
-declare const Templates: Record<TplName, TemplateFromFile>;
-export { Templates };

package/index.js

@@ -1,3 +0,0 @@
-module.exports = { Templates: {
-  'main': { type: 'from-file', path: require.resolve('./dist/tengo/tpl/main.plj.gz') }
-}}

package/tsconfig.json

@@ -1,16 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "es2022",
-    "module": "commonjs",
-    "moduleResolution": "node",
-    "esModuleInterop": true,
-    "strict": true,
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "sourceMap": true,
-    "declaration": true
-  },
-  "types": [],
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}

package/vitest.config.mts

@@ -1,9 +0,0 @@
-import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    watch: false,
-    maxConcurrency: 3,
-    testTimeout: 5000
-  }
-});