MILAB-6848: ensure sc TCR chains are displayed in the same order as in literature: TCRAB, TCRGD

Author: mchernys

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

@@ -10,3 +10,5 @@ Fix inverted TCR chain labels. Chain letter A is the D-recombining chain, so for
 Per-chain CDR3 descriptions no longer name antibody loops (CDR-H3 / CDR-L3) on TCR input.
 
 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.

docs/spec-deviations.md

@@ -634,3 +634,62 @@ stays independent of the label.
 - Public docs: `docs/docs.platforma.bio/docs/30-sdk/100-vdj-guides/60-naming-conventions.md`.
 - Still inverted, tracked separately:
   `antibody-tcr-lead-selection/workflow/src/utils.lib.tengo:702-705`.
+
+---
+
+## SD-011: Table Order Follows Spoken Chain Naming, Not Slot Order
+
+**Status:** applied
+**Date:** 2026-08-31
+**Affected file:** `workflow/src/columns.lib.tengo` (`displaysFirst`,
+`buildCdr3Columns`, `buildFullChainColumns`)
+
+### Root cause
+
+`pl7.app/table/orderPriority` was keyed to the chain *slot* — `"A"` always took
+the higher band — and the spec fixes those numbers slot-wise from the IG
+perspective (`pcolumn-spec.md:295`: `"67000"  // 66000 for light chain`). For IG
+that is invisible, since heavy is both the first-named and the slot-`A` chain.
+For TCR the two rules diverge, because slot `A` is the D-recombining chain
+(SD-010) — beta, not alpha. The table therefore led with `CDR-β3`, leaking
+MiXCR's diversity-first slot assignment into the column order exactly as the
+labels did before SD-010.
+
+### Options considered
+
+**A. Order by the receptor's spoken naming. [chosen]** Assign the existing
+bands by a (receptor, chain) display rank instead of the slot letter. IG keeps
+heavy-then-light; no name, domain or value changes.
+**B. Leave ordering on the slot.** Matches the spec's literal numbers, but
+keeps a producer artifact in front of the scientist.
+**C. Order by slot and rename labels to match.** Rejected — re-introduces the
+SD-010 bug.
+
+### Decision
+
+**A.** Slot identity belongs to the producer; the label and the reading order
+are the user-facing surface. SD-010 established that for labels, and column
+position is the same surface reached a different way. Nothing cross-block is
+broken: `import-vdj-data` keys `orderPriority` per region, identical for both
+chains (`bare-set-specs.lib.tengo:331`), so its chain order is incidental.
+
+### Deliberately not changed: the default plot axis
+
+`ui/src/utils/scalarColumns.ts` still selects `scClonotypeChain: "A"` for the
+default scatter and histogram source, per R19/R20. Table order is a reading
+convention; the default plotted chain is an analytical one, and beta/delta carry
+the greater CDR3 diversity. The chart labels its own axes, so the divergence is
+unambiguous. The R19a/R20a fallback reads *emission* order — unchanged here — so
+it also still lands on chain `A`.
+
+### Implementation
+
+`displaysFirst(receptor, chain)` in `columns.lib.tengo`, pinned per receptor
+across both bands by `Test_buildColumns_tableOrderFollowsSpokenNaming` in
+`workflow/src/columns.test.tengo`.
+
+### References
+
+- 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.

ui/src/utils/scalarColumns.ts

@@ -59,6 +59,7 @@ export function defaultScatterAxes(
   // Antibody/TCR — IG/TCRAB/TCRGD, bulk or single-cell. Domain is identical
   // across receptors; the user-facing label (CDR-H3 / CDR-β3 / CDR-δ3) is
   // already encoded in spec annotations by the workflow (R13a).
+  // Deliberately slot A (the more diverse chain) though the table leads with α/γ.
   const domain = {
     "pl7.app/feature": "CDR3",
     "pl7.app/vdj/scClonotypeChain": "A",

workflow/src/columns.lib.tengo

@@ -48,6 +48,12 @@ labelFragments := func(receptor, chain) {
 	return { cdr3: "CDR-L3", fullChain: "VL" }
 }
 
+// Table order follows the receptor's spoken naming — heavy/light, α/β, γ/δ — not slot order.
+displaysFirst := func(receptor, chain) {
+	if receptor == "TCRAB" || receptor == "TCRGD" { return chain == "B" }
+	return chain == "A"
+}
+
 // 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-
@@ -192,12 +198,12 @@ CDR3_GRAVY_DESC := {
 
 buildCdr3Columns := func(receptor, chains) {
 	cols := []
-	cdr3OrderA := 68000
-	cdr3OrderB := 67700
+	cdr3OrderFirst := 68000
+	cdr3OrderSecond := 67700
 	for chain in chains {
 		frag := labelFragments(receptor, chain)
 		cdr3Dom := { "pl7.app/feature": "CDR3", "pl7.app/vdj/scClonotypeChain": chain }
-		chargeOrder := (chain == "A" ? cdr3OrderA : cdr3OrderB)
+		chargeOrder := (displaysFirst(receptor, chain) ? cdr3OrderFirst : cdr3OrderSecond)
 		gravyOrder := chargeOrder - 100
 
 		cols += [makeCol("charge_" + chain + "_CDR3", "pl7.app/charge", "Double",
@@ -235,12 +241,12 @@ buildCdr3Columns := func(receptor, chains) {
 
 buildFullChainColumns := func(receptor, fullChains) {
 	cols := []
-	fcOrderBaseA := 67000
-	fcOrderBaseB := 66000
+	fcOrderBaseFirst := 67000
+	fcOrderBaseSecond := 66000
 	for chain in fullChains {
 		frag := labelFragments(receptor, chain)
 		fcDom := { "pl7.app/feature": "VDJRegion", "pl7.app/vdj/scClonotypeChain": chain }
-		base := (chain == "A" ? fcOrderBaseA : fcOrderBaseB)
+		base := (displaysFirst(receptor, chain) ? fcOrderBaseFirst : fcOrderBaseSecond)
 		fcLabel := frag.fullChain
 
 		cols += [makeCol("charge_" + chain + "_VDJRegion", "pl7.app/charge", "Double",

workflow/src/columns.test.tengo

@@ -41,6 +41,34 @@ Test_buildColumns_chainAIsTheDiverseChain := func() {
 	}
 }
 
+orderOf := func(cols, tsvCol) {
+	for col in cols {
+		if col.column == tsvCol {
+			return col.spec.annotations["pl7.app/table/orderPriority"]
+		}
+	}
+	return undefined
+}
+
+Test_buildColumns_tableOrderFollowsSpokenNaming := func() {
+	pairs := [
+		{ receptor: "IG", first: "A", second: "B" },
+		{ receptor: "TCRAB", first: "B", second: "A" },
+		{ receptor: "TCRGD", first: "B", second: "A" }
+	]
+	for pair in pairs {
+		cols := pairedCols(pair.receptor)
+		test.isEqual("68000", orderOf(cols, "charge_" + pair.first + "_CDR3"),
+			pair.receptor + " CDR3 leads with chain " + pair.first)
+		test.isEqual("67700", orderOf(cols, "charge_" + pair.second + "_CDR3"),
+			pair.receptor + " CDR3 trails with chain " + pair.second)
+		test.isEqual("67000", orderOf(cols, "charge_" + pair.first + "_VDJRegion"),
+			pair.receptor + " full-chain leads with chain " + pair.first)
+		test.isEqual("66000", orderOf(cols, "charge_" + pair.second + "_VDJRegion"),
+			pair.receptor + " full-chain trails with chain " + pair.second)
+	}
+}
+
 Test_buildColumns_chainDomainIsIndependentOfTheLabel := func() {
 	for receptor in ["IG", "TCRAB", "TCRGD"] {
 		cols := pairedCols(receptor)