@platforma-open/milaboratories.mixcr-amplicon-alignment.workflow 1.19.8 → 1.20.0

package/.turbo/turbo-build.log

@@ -1,6 +1,6 @@
  WARN  Issue while reading "/home/runner/work/mixcr-amplicon-alignment/mixcr-amplicon-alignment/.npmrc". Failed to replace env in config: ${NPMJS_TOKEN}
 
-> @platforma-open/milaboratories.mixcr-amplicon-alignment.workflow@1.19.8 build /home/runner/work/mixcr-amplicon-alignment/mixcr-amplicon-alignment/workflow
+> @platforma-open/milaboratories.mixcr-amplicon-alignment.workflow@1.20.0 build /home/runner/work/mixcr-amplicon-alignment/mixcr-amplicon-alignment/workflow
 > rm -rf dist && pl-tengo check && pl-tengo build
 
 Processing "src/aggregate-by-clonotype-key.tpl.tengo"...

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @platforma-open/milaboratories.mixcr-amplicon-alignment.workflow
 
+## 1.20.0
+
+### Minor Changes
+
+- e2b65c7: Support custom reference library file
+
+## 1.19.9
+
+### Patch Changes
+
+- 2149d28: Fix column naming for range assembling features (e.g. CDR1:CDR3, FR2:FR4) without imputation.
+
+  When using a range assembling feature without "Impute non-covered part", the workflow would fail with
+  "column nSeqVDJRegion does not exist in export" because VDJRegion is never exported for non-full-range features.
+
+  Changes:
+
+  - Use the assembling feature itself as clonotype key column when VDJRegion is unavailable
+  - Fix column naming to match MiXCR output format (e.g. `CDR1_TO_FR4` instead of `{CDR1Begin:FR4End}`)
+  - Add unit tests covering column naming for all assembling feature variants with/without imputation
+
 ## 1.19.8
 
 ### Patch Changes

package/dist/tengo/lib/calculate-export-specs.lib.tengo

@@ -164,8 +164,20 @@ calculateExportSpecs := func(presetSpecForBack, blockId) {
 	}
 
 	productiveFeature := formatAssemblingFeature(assemblingFeature)
-	
+
+
+
+
+
+
 	outputProductiveFeature := productiveFeature
+	if assemblingFeature != "VDJRegion" && assemblingFeature != "CDR3" {
+		parts := text.split(assemblingFeature, ":")
+		if len(parts) == 2 && parts[1] == "FR4" {
+
+			outputProductiveFeature = parts[0] + "_TO_FR4"
+		}
+	}
 	
 	coreGeneFeatures := parsedFeature.coreGeneFeatures
 
@@ -187,22 +199,67 @@ calculateExportSpecs := func(presetSpecForBack, blockId) {
 			[ "-jGene" ]
 		]
 	} else {
-		isVdjImputed := !is_undefined(imputedFeaturesMap["VDJRegion"]) && imputeGermline
-		vdjColName := "nSeq" + (isVdjImputed ? "Imputed" : "") + "VDJRegion"
-		vdjArgLabel := "-nFeature" + (isVdjImputed ? "Imputed" : "")
 
-		clonotypeKeyColumns = [vdjColName, "bestVGene", "bestJGene"]
-		clonotypeKeyArgs = [
-			[ vdjArgLabel, "VDJRegion" ],
-			[ "-vGene" ],
-			[ "-jGene" ]
-		]
+
+		vdjIsAssemblingFeature := is_undefined(imputedFeaturesMap["VDJRegion"])
+
+		if vdjIsAssemblingFeature {
+
+			clonotypeKeyColumns = ["nSeqVDJRegion", "bestVGene", "bestJGene"]
+			clonotypeKeyArgs = [
+				[ "-nFeature", "VDJRegion" ],
+				[ "-vGene" ],
+				[ "-jGene" ]
+			]
+		} else {
+
+
+
+
+
+			keyColName := "nSeq" + outputProductiveFeature
+			clonotypeKeyColumns = [keyColName, "bestVGene", "bestJGene"]
+			clonotypeKeyArgs = [
+				[ "-nFeature", productiveFeature ],
+				[ "-vGene" ],
+				[ "-jGene" ]
+			]
+		}
 	}
 
 	columnsSpecPerSample := []
 	columnsSpecPerClonotypeNoAggregates := []
 	mutationColumns := []
 
+
+
+
+	needsAssemblingFeatureExport := assemblingFeature != "CDR3" && assemblingFeature != "VDJRegion" && !is_undefined(imputedFeaturesMap["VDJRegion"])
+	if needsAssemblingFeatureExport {
+		featureIdL := text.to_lower(formatId(assemblingFeature))
+		keyColName := "nSeq" + outputProductiveFeature
+		columnsSpecPerClonotypeNoAggregates += [ {
+			column: keyColName,
+			id: "n-seq-" + featureIdL,
+			naRegex: "region_not_covered",
+			spec: {
+				name: "pl7.app/vdj/sequence",
+				valueType: "String",
+				domain: {
+					"pl7.app/vdj/feature": outputProductiveFeature,
+					"pl7.app/alphabet": "nucleotide"
+				},
+				annotations: a(80100, false, {
+					"pl7.app/vdj/isAssemblingFeature": "true",
+					"pl7.app/vdj/isMainSequence": "false",
+					"pl7.app/vdj/imputed": "false",
+					"pl7.app/table/fontFamily": "monospace",
+					"pl7.app/label": outputProductiveFeature + " nt"
+				})
+			}
+		} ]
+	}
+
 	clonotypeLabelColumn := {
 		column: "clonotypeLabel",
 		id: "clonotype-label",
@@ -220,6 +277,11 @@ calculateExportSpecs := func(presetSpecForBack, blockId) {
 	exportArgs := []
 
 
+	if needsAssemblingFeatureExport {
+		exportArgs += [ [ "-nFeature", productiveFeature ] ]
+	}
+
+
 
 	hasUmi := !is_undefined(presetSpecForBack) && !is_undefined(presetSpecForBack.umiTags) && len(presetSpecForBack.umiTags) > 0
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-open/milaboratories.mixcr-amplicon-alignment.workflow",
-  "version": "1.19.8",
+  "version": "1.20.0",
   "description": "MiXCR Amplicon Alignment Workflow",
   "type": "module",
   "dependencies": {

package/src/calculate-export-specs.lib.tengo

@@ -164,8 +164,20 @@ calculateExportSpecs := func(presetSpecForBack, blockId) {
 	}
 
 	productiveFeature := formatAssemblingFeature(assemblingFeature)
-	
+
+	// MiXCR column naming for range features:
+	// - Ranges ending at FR4 have named aliases: CDR1_TO_FR4, FR2_TO_FR4, CDR2_TO_FR4, FR3_TO_FR4
+	//   (defined in repseqio GeneFeature.java)
+	// - All other ranges use {XBegin:YEnd} format (e.g. {CDR1Begin:CDR3End})
+	// - Simple features (CDR3, VDJRegion) use their name directly
 	outputProductiveFeature := productiveFeature
+	if assemblingFeature != "VDJRegion" && assemblingFeature != "CDR3" {
+		parts := text.split(assemblingFeature, ":")
+		if len(parts) == 2 && parts[1] == "FR4" {
+			// MiXCR has a named alias for this range
+			outputProductiveFeature = parts[0] + "_TO_FR4"
+		}
+	}
 	
 	coreGeneFeatures := parsedFeature.coreGeneFeatures
 
@@ -187,22 +199,67 @@ calculateExportSpecs := func(presetSpecForBack, blockId) {
 			[ "-jGene" ]
 		]
 	} else {
-		isVdjImputed := !is_undefined(imputedFeaturesMap["VDJRegion"]) && imputeGermline
-		vdjColName := "nSeq" + (isVdjImputed ? "Imputed" : "") + "VDJRegion"
-		vdjArgLabel := "-nFeature" + (isVdjImputed ? "Imputed" : "")
-
-		clonotypeKeyColumns = [vdjColName, "bestVGene", "bestJGene"]
-		clonotypeKeyArgs = [
-			[ vdjArgLabel, "VDJRegion" ],
-			[ "-vGene" ],
-			[ "-jGene" ]
-		]
+		// VDJRegion is the assembling feature itself only when it's NOT in the imputed list
+		// (e.g. VDJRegion or FR1:FR4 as the assembling feature)
+		vdjIsAssemblingFeature := is_undefined(imputedFeaturesMap["VDJRegion"])
+
+		if vdjIsAssemblingFeature {
+			// VDJRegion IS the assembling feature, use it directly as the key
+			clonotypeKeyColumns = ["nSeqVDJRegion", "bestVGene", "bestJGene"]
+			clonotypeKeyArgs = [
+				[ "-nFeature", "VDJRegion" ],
+				[ "-vGene" ],
+				[ "-jGene" ]
+			]
+		} else {
+			// Range feature where VDJRegion is NOT the assembling feature (e.g. CDR1:CDR3, FR2:FR4)
+			// Always use the assembling feature itself as the key, even with imputation enabled.
+			// Imputed VDJRegion is NOT guaranteed unique per clone (two clones with different
+			// assembling feature sequences can produce the same imputed VDJRegion).
+			// The assembling feature sequence IS unique by definition (it defines the clone).
+			keyColName := "nSeq" + outputProductiveFeature
+			clonotypeKeyColumns = [keyColName, "bestVGene", "bestJGene"]
+			clonotypeKeyArgs = [
+				[ "-nFeature", productiveFeature ],
+				[ "-vGene" ],
+				[ "-jGene" ]
+			]
+		}
 	}
 
 	columnsSpecPerSample := []
 	columnsSpecPerClonotypeNoAggregates := []
 	mutationColumns := []
 
+	// For range features where VDJRegion is not the assembling feature, we need to export
+	// the combined assembling feature sequence column explicitly (individual features are
+	// exported in the loop below, but the combined feature like {CDR1Begin:CDR3End} is not)
+	needsAssemblingFeatureExport := assemblingFeature != "CDR3" && assemblingFeature != "VDJRegion" && !is_undefined(imputedFeaturesMap["VDJRegion"])
+	if needsAssemblingFeatureExport {
+		featureIdL := text.to_lower(formatId(assemblingFeature))
+		keyColName := "nSeq" + outputProductiveFeature
+		columnsSpecPerClonotypeNoAggregates += [ {
+			column: keyColName,
+			id: "n-seq-" + featureIdL,
+			naRegex: "region_not_covered",
+			spec: {
+				name: "pl7.app/vdj/sequence",
+				valueType: "String",
+				domain: {
+					"pl7.app/vdj/feature": outputProductiveFeature,
+					"pl7.app/alphabet": "nucleotide"
+				},
+				annotations: a(80100, false, {
+					"pl7.app/vdj/isAssemblingFeature": "true",
+					"pl7.app/vdj/isMainSequence": "false",
+					"pl7.app/vdj/imputed": "false",
+					"pl7.app/table/fontFamily": "monospace",
+					"pl7.app/label": outputProductiveFeature + " nt"
+				})
+			}
+		} ]
+	}
+
 	clonotypeLabelColumn := {
 		column: "clonotypeLabel",
 		id: "clonotype-label",
@@ -219,6 +276,11 @@ calculateExportSpecs := func(presetSpecForBack, blockId) {
 	// array of array of arg groups
 	exportArgs := []
 
+	// Add the assembling feature export arg if needed (column spec was added above)
+	if needsAssemblingFeatureExport {
+		exportArgs += [ [ "-nFeature", productiveFeature ] ]
+	}
+
 	// Abundance - reads by default; switch to UMI columns if umiTags are present
 
 	hasUmi := !is_undefined(presetSpecForBack) && !is_undefined(presetSpecForBack.umiTags) && len(presetSpecForBack.umiTags) > 0

package/src/main.tpl.tengo

@@ -41,16 +41,25 @@ wf.body(func(args) {
 		"TCRDelta": { mixcrFilter: "TRG", name: "TCR Delta", shortName: "Delta" }
 }
 
-    // Generate reference library using repseqio if both V and J genes are available
-  
-	repseqioResults := render.create(repseqioLibraryTpl, {
-		vGenes: args.vGenes,
-		jGenes: args.jGenes,
-		chains: chainInfos[chains].mixcrFilter
-	})
-	
-	referenceLibrary := repseqioResults.output("referenceLibrary")
-	debugOutput := repseqioResults.output("debugOutput")
+	// Generate reference library using repseqio, or use directly imported library file
+	isLibraryFileGzipped := false
+	referenceLibrary := false
+	debugOutput := undefined
+	libraryImportHandle := undefined
+
+	if !is_undefined(args.libraryFile) {
+		fImport := file.importFile(args.libraryFile)
+    	libraryImportHandle = fImport.handle
+    	referenceLibrary = fImport.file
+	} else {
+		repseqioResults := render.create(repseqioLibraryTpl, {
+			vGenes: args.vGenes,
+			jGenes: args.jGenes,
+			chains: chainInfos[chains].mixcrFilter
+		})
+		referenceLibrary = repseqioResults.output("referenceLibrary")
+		debugOutput = repseqioResults.output("debugOutput")
+	}
     
 
 	runMixcr := render.createEphemeral(processTpl, {
@@ -71,6 +80,7 @@ wf.body(func(args) {
 			assemblingFeature: args.assemblingFeature,
 			imputeGermline: args.imputeGermline,
 			badQualityThreshold: args.badQualityThreshold,
+			isLibraryFileGzipped: isLibraryFileGzipped,
 			stopCodonTypes: args.stopCodonTypes,
 			stopCodonReplacements: args.stopCodonReplacements
 		}, { removeUndefs: true }))
@@ -92,6 +102,23 @@ wf.body(func(args) {
 		}
 	}
 
+	if !is_undefined(args.libraryFile) {
+		exports.library = {
+			data: referenceLibrary,
+			spec: {
+				kind: "File",
+				name: "pl7.app/vdj/library",
+				domain: {
+					"pl7.app/vdj/libraryId": blockId
+				},
+				annotations: {
+					"pl7.app/vdj/isLibrary": "true",
+					"pl7.app/vdj/libraryFormat": (isLibraryFileGzipped ? "repseqio.json.gz" : "repseqio.json")
+				}
+			}
+		}
+	}
+
 	outputs := {
 		qc: pframes.exportColumnData(runMixcr.output("qc.data")),
 		reports: pframes.exportColumnData(runMixcr.output("reports.data")),
@@ -99,9 +126,15 @@ wf.body(func(args) {
 		clones: pframes.exportFrame(runMixcr.output("clones")),
 		clns: runMixcr.output("clns.data"),
 		progress: runMixcr.output("progress.data"),
-		clonotypeTables: pframes.exportFrame(runMixcr.output("clonotypeTables")),
-		debugOutput: debugOutput
+		clonotypeTables: pframes.exportFrame(runMixcr.output("clonotypeTables"))
+	}
+	outputs.referenceLibrary = file.exportFile(referenceLibrary)
+	if !is_undefined(debugOutput) {
+		outputs.debugOutput = debugOutput
 	}
+	if !is_undefined(libraryImportHandle) {
+    	outputs.libraryImportHandle = libraryImportHandle
+    }
 
 	qcReportTable := runMixcr.output("qcReportTable")
 	outputs.qcReportTable = pframes.exportFrame(qcReportTable)

package/src/mixcr-analyze.tpl.tengo

@@ -81,11 +81,16 @@ self.body(func(inputs) {
 		return "{" + parts[0] + "Begin:" + parts[1] + "End}"
 	}
 
+	libraryFileName := "library.json"
+	if !is_undefined(params.isLibraryFileGzipped) && params.isLibraryFileGzipped {
+		libraryFileName = "library.json.gz"
+	}
+
     mixcrCmdBuilder.
         arg("--assemble-clonotypes-by").arg(formatAssemblingFeature(params.assemblingFeature)).
         arg("--species").arg("custom").
-		arg("--library").arg("library.json").
-		addFile("library.json", params.referenceLibrary).
+		arg("--library").arg(libraryFileName).
+		addFile(libraryFileName, params.referenceLibrary).
         arg("--rna").
 		arg("--force-overwrite").
 		arg("--rigid-left-alignment-boundary").

package/src/mixcr-export.tpl.tengo

@@ -216,12 +216,17 @@ self.body(func(inputs) {
 
 		additionalAction(mixcrCmdBuilder)
 
+		libraryFileName := "library.json"
+		if !is_undefined(params.isLibraryFileGzipped) && params.isLibraryFileGzipped {
+			libraryFileName = "library.json.gz"
+		}
+
 		return mixcrCmdBuilder.
 			arg("clones.clns").
 			addFile("clones.clns", clnsFile).
 			arg("clones.tsv").
 			saveFile("clones.tsv").
-			addFile("library.json", params.referenceLibrary).
+			addFile(libraryFileName, params.referenceLibrary).
 			cacheHours(3).
 			run()
 	}

package/src/process.tpl.tengo

@@ -22,8 +22,6 @@ calculateExportSpecs := import(":calculate-export-specs")
 self.awaitState("InputsLocked")
 self.awaitState("params", "ResourceReady")
 self.awaitState("inputSpec", "ResourceReady")
-self.awaitState("referenceLibrary", "ResourceReady")
-self.awaitState("cdr3Sequences", "ResourceReady")
 
 self.body(func(inputs) {
 
@@ -223,7 +221,8 @@ self.body(func(inputs) {
 					tagPattern: tagPattern,
 					assemblingFeature: params.assemblingFeature,
 					imputeGermline: params.imputeGermline,
-					badQualityThreshold: params.badQualityThreshold
+					badQualityThreshold: params.badQualityThreshold,
+					isLibraryFileGzipped: params.isLibraryFileGzipped
 				}, { removeUndefs: true }),
 				limitInput: limitInput
 			},
@@ -287,7 +286,8 @@ self.body(func(inputs) {
 					cdr3SeqColumns: cdr3SeqColumns,
 					stopCodonTypes: params.stopCodonTypes,
 					stopCodonReplacements: params.stopCodonReplacements,
-					perProcessMemGB: perProcessMemGB
+					perProcessMemGB: perProcessMemGB,
+					isLibraryFileGzipped: params.isLibraryFileGzipped
 				}, { removeUndefs: true })
 			}
 		}
@@ -369,7 +369,7 @@ self.body(func(inputs) {
 		sampleIdAxisSpec: sampleIdAxisSpec,
 		chains: [chains],
 		library: referenceLibrary,
-		isLibraryFileGzipped: false,
+		isLibraryFileGzipped: params.isLibraryFileGzipped,
 		clonotypeTablesData: clonotypeTablesData,
 		hasUmi: hasUMI,
 		umiTags: umiTags,