MILAB-6848: derive bulk chain slot from the locus instead of assuming A

Author: mchernys

.changeset/tcr-chain-label-mapping.md

@@ -12,3 +12,5 @@ Per-chain CDR3 descriptions no longer name antibody loops (CDR-H3 / CDR-L3) on T
 Adds a Tengo unit test covering the chain-letter to label mapping for all three receptors, and wires `pl-tengo test` into the workflow package so it runs.
 
 Orders paired-chain columns by the receptor's spoken naming — alpha before beta, gamma before delta — instead of by chain slot. IG keeps heavy before light. The default scatter and histogram source stays on chain A.
+
+Derives the chain slot from the locus on bulk input instead of assuming chain A. Bulk TCRAlpha, TCRGamma, IGLight, IGKappa and IGLambda datasets were labelled as their paired partner; their emitted scClonotypeChain domain now reads B rather than A.

docs/spec-deviations.md

@@ -693,3 +693,66 @@ across both bands by `Test_buildColumns_tableOrderFollowsSpokenNaming` in
 - Spec requiring correction: `pcolumn-spec.md:295` and the slot-keyed
   orderPriority values through L240-L420.
 - Predecessor: SD-010. Default-axis spec: `README.md` R19, R20, R19a, R20a.
+
+---
+
+## SD-012: Derive The Chain Slot From The Locus On Bulk Input
+
+**Status:** applied
+**Date:** 2026-09-01
+**Affected file:** `workflow/src/columns.lib.tengo` (`chainToSlot`),
+`workflow/src/main.tpl.tengo` (per-column chain resolution)
+
+### Root cause
+
+Spec R13 reads chain identity from `pl7.app/vdj/scClonotypeChain`. Bulk MiXCR
+does not emit that key at all: it names the locus on the key axis via
+`pl7.app/vdj/chain` (`"IGHeavy"`, `"TCRAlpha"`, ...), one locus per dataset.
+The code filled the gap by assuming slot `"A"` for every bulk column.
+
+While slot `A` was believed to be alpha (pre-SD-010), that assumption happened
+to label bulk alpha datasets correctly and bulk beta ones wrongly. SD-010
+corrected the slot semantics, which flipped the victims rather than removing
+them: `TCRAlpha`, `TCRGamma`, `IGLight`, `IGKappa` and `IGLambda` inputs were
+labelled as their paired partner, and the R11b coverage messages named the
+wrong chain with them.
+
+SD-008 already derives the *receptor* from the same `pl7.app/vdj/chain` key.
+The locus determines the slot just as unambiguously, so the information needed
+was present and discarded.
+
+### Options considered
+
+**A. Derive the slot from the locus. [chosen]** `chainToSlot` maps the eight
+MiXCR loci onto the slot MiXCR itself seats them in, per its diversity-first
+`receptorInfos` ordering. Unknown or absent loci keep the previous `"A"`
+default, so non-MiXCR producers are unaffected.
+**B. Emit no chain domain on bulk input.** Truer to the data, since a bulk set
+has no pairing, but changes the column shape and breaks consumers keying on it.
+**C. Keep assuming `"A"`.** Leaves half of all bulk receptors mislabelled.
+
+### Decision
+
+**A.** The derivation already existed for the receptor (SD-008); extending it
+to the slot uses the same key and the same MiXCR rule.
+
+### Emitted domain changes on affected datasets
+
+This is not label-only. On bulk `TCRAlpha`, `TCRGamma`, `IGLight`, `IGKappa`
+and `IGLambda` input the emitted `pl7.app/vdj/scClonotypeChain` domain moves
+from `"A"` to `"B"`, which changes PColumn identity for those datasets. The new
+value is the correct one, and a consumer that matched the old `"A"` was
+matching a chain that was never there. Bulk `IGHeavy`, `TCRBeta` and `TCRDelta`
+are unchanged, as is all paired single-cell input.
+
+### Implementation
+
+`chainToSlot(chain)` in `columns.lib.tengo`, applied in `main.tpl.tengo` where
+`scClonotypeChain` is absent, preferring a per-column `pl7.app/vdj/chain` and
+falling back to the key axis. Covered by
+`Test_chainToSlot_locusSeatsTheDiverseChainInA`.
+
+### References
+
+- Predecessors: SD-008 (receptor from the same key), SD-010 (slot semantics).
+- Slot ordering: `blocks/mixcr-clonotyping/workflow/src/process.tpl.tengo:39-44`.

workflow/src/columns.lib.tengo

@@ -11,6 +11,9 @@
 //                                       at pframe-build time.
 //   - `aaFractionColumn(spec, feat)` — 2-axis AA-fraction column descriptor
 //                                       (whole-sequence modes: peptide / amplicon).
+//   - `chainToSlot(chain)`           — MiXCR locus ("TCRAlpha", "IGLight", ...)
+//                                       → the A/B slot it occupies, for bulk
+//                                       input that carries no scClonotypeChain.
 //   - `cloneSpec(spec, dExtras, aExtras)` — spec-cloning helper used by the
 //                                       caller to layer blockId / isOutput /
 //                                       any other per-consumer overrides.
@@ -54,6 +57,25 @@ displaysFirst := func(receptor, chain) {
 	return chain == "A"
 }
 
+// Bulk input names its locus but has no slot; MiXCR seats the D-recombining chain in A.
+CHAIN_TO_SLOT := {
+	IGHeavy: "A",
+	IGLight: "B",
+	IGKappa: "B",
+	IGLambda: "B",
+	TCRBeta: "A",
+	TCRAlpha: "B",
+	TCRDelta: "A",
+	TCRGamma: "B"
+}
+
+chainToSlot := func(chain) {
+	if chain == undefined { return "A" }
+	s := CHAIN_TO_SLOT[chain]
+	if s == undefined { return "A" }
+	return s
+}
+
 // Build a single output column descriptor consumed by xsv.importFile.
 // `tsvCol` is the TSV column header emitted by Python (e.g. "charge_peptide", "charge_A_CDR3").
 // Clones the caller's `annotations` dict so the label stamp does not aliasing-
@@ -480,5 +502,6 @@ aaFractionColumn := func(keyAxisSpec, feature) {
 export ll.toStrict({
 	buildColumns: buildColumns,
 	aaFractionColumn: aaFractionColumn,
+	chainToSlot: chainToSlot,
 	cloneSpec: cloneSpec
 })

workflow/src/columns.test.tengo

@@ -69,6 +69,19 @@ Test_buildColumns_tableOrderFollowsSpokenNaming := func() {
 	}
 }
 
+Test_chainToSlot_locusSeatsTheDiverseChainInA := func() {
+	seats := {
+		IGHeavy: "A", IGLight: "B", IGKappa: "B", IGLambda: "B",
+		TCRBeta: "A", TCRAlpha: "B",
+		TCRDelta: "A", TCRGamma: "B"
+	}
+	for locus, slot in seats {
+		test.isEqual(slot, columns.chainToSlot(locus), locus + " slot")
+	}
+	test.isEqual("A", columns.chainToSlot(undefined), "missing locus defaults to A")
+	test.isEqual("A", columns.chainToSlot("Nonsense"), "unknown locus defaults to A")
+}
+
 Test_buildColumns_chainDomainIsIndependentOfTheLabel := func() {
 	for receptor in ["IG", "TCRAB", "TCRGD"] {
 		cols := pairedCols(receptor)

workflow/src/main.tpl.tengo

@@ -202,10 +202,12 @@ wf.body(func(args) {
 	// Spec deviation SD-008 — bulk MiXCR axes lack `pl7.app/vdj/receptor` but
 	// carry `pl7.app/vdj/chain`; derive receptor from chain when receptor is
 	// absent. See docs/spec-deviations.md.
+	axisChain := undefined
 	if keyAxisSpec.domain != undefined {
+		axisChain = keyAxisSpec.domain["pl7.app/vdj/chain"]
 		r := resolveReceptor(
 			keyAxisSpec.domain["pl7.app/vdj/receptor"],
-			keyAxisSpec.domain["pl7.app/vdj/chain"]
+			axisChain
 		)
 		if r.seen {
 			receptor = r.value
@@ -268,8 +270,9 @@ wf.body(func(args) {
 
 			chain := d["pl7.app/vdj/scClonotypeChain"]
 			if chain == undefined || chain == "" {
-				// Bulk MiXCR data without chain annotation — assume primary chain "A".
-				chain = "A"
+				// Bulk has no slot; derive it from the locus so the label names the real chain.
+				colChain := d["pl7.app/vdj/chain"]
+				chain = columnSpecs.chainToSlot(colChain != undefined ? colChain : axisChain)
 			}
 
 			// Same receptor value is expected on every input column; last seen wins.