Milab 6848 fix sc tcr chain labels

[mchernys]

Greptile Summary

The PR corrects TCR chain labels to follow MiXCR’s diversity-first slot convention, derives missing bulk chain slots from locus metadata, and orders displayed TCR columns by spoken receptor naming. It also adds focused Tengo coverage and updates documentation and release metadata.

• Important touched terms
  • Chain slot: The abstract A/B identity stored in pl7.app/vdj/scClonotypeChain. The change defines slot A as the D-recombining chain—heavy, beta, or delta—and derives the slot from bulk locus metadata when the explicit domain is absent.
  • Locus: A concrete receptor-chain identifier such as TCRAlpha, TCRBeta, IGHeavy, or IGLight. A new chainToSlot mapping translates supported bulk loci into their corresponding chain slots.
  • Receptor: The paired biological receptor family (IG, TCRAB, or TCRGD) used to interpret slots. Its label mapping now renders TCRAB A/B as beta/alpha and TCRGD A/B as delta/gamma.
  • CDR3: The third complementarity-determining region whose biochemical properties are emitted per chain. TCR labels now identify the correct biological chain, and descriptions no longer apply antibody-specific loop names to TCR data.
  • VDJRegion: A reconstructed full variable-domain chain. Its labels receive the same corrected slot-to-biological-chain mapping as CDR3 columns.
  • PColumn domain: The machine-readable identity and biological scope of an output property column. Paired-input domains remain slot-based, while affected bulk alpha, gamma, and light-chain inputs now emit slot B instead of the former blanket A default.
  • Table order priority: The annotation controlling property-column presentation order. TCR columns now display alpha before beta and gamma before delta, while IG remains heavy before light.
  • Default visualization chain: The CDR3 chain selected for initial scatter and histogram metrics. It deliberately remains slot A, selecting the more diverse beta/delta chain even though the table presents alpha/gamma first.
  • Partial-coverage message: A workflow advisory naming chains with incomplete sequence coverage. Its TCR chain names now follow the corrected slot mapping.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
workflow/src/columns.lib.tengo	Corrects receptor-specific labels, introduces bulk locus-to-slot mapping, and separates biological display order from chain-slot order.
workflow/src/main.tpl.tengo	Captures axis locus metadata, derives missing bulk slots, and updates receptor-aware coverage-message labels.
workflow/src/columns.test.tengo	Adds focused coverage for slot labels, table order, locus mapping, and preservation of machine-readable chain domains.
ui/src/utils/scalarColumns.ts	Documents that visualizations intentionally continue selecting diversity-first slot A despite the revised table order.
docs/spec-deviations.md	Records the producer-driven slot convention, display-order decision, and bulk-domain migration.
.changeset/tcr-chain-label-mapping.md	Declares minor releases for the affected workflow, UI, software, and assembled block packages.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Input VDJ metadata] --> B{Explicit scClonotypeChain?}
  B -->|Yes| C[Use A or B slot]
  B -->|No, bulk input| D[Read concrete locus]
  D --> E[Map locus to A or B]
  C --> F[Resolve receptor-specific label]
  E --> F
  F --> G[CDR3 and VDJRegion columns]
  F --> H[Coverage messages]
  G --> I[Table ordered by spoken chain naming]
  G --> J[Charts default to slot A]

Loading

_{Reviews (2): Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." | Re-trigger Greptile}

Context used (4)

• Knowledge Base — Platform application integration
• Knowledge Base — Workflow integration
• Knowledge Base — Visualization user interface
• Knowledge Base — Workspace packaging and release

[mchernys]

@greptileai