pirl-unc / tcrsift / 25926219165

Build # 25926219165

Build Type

push

github

Committed by web-flow

Commit Message

Fix #83: surface antigen/MHC/category metadata on match output (#87)

* Fix #83: surface antigen/MHC/category metadata on match output

Three concrete extensions to the existing annotation column set. Most
columns from #83's ask were already shipped by #54 (db_epitope,
db_protein, db_protein_canonical, db_species, db_mhc, db_category,
db_database, is_viral); this PR closes the remaining gaps.

1. **``db_host_species``** — the TCR donor's species, distinct from
   ``db_species`` (which is the antigen source organism). VDJdb's
   full export carries it but the loader was deliberately dropping it
   (see ``_normalize_vdjdb_paired`` / ``_long``). Now preserved as
   ``host_species`` on the standardized DB and surfaced as
   ``db_host_species`` on matches.

2. **Cross-species match strength** — ``db_match_strength`` gains
   ``ab_cross`` / ``b_only_cross`` variants when matched rows carry a
   non-human host species (anything other than "Homo sapiens" or
   "human"). Downstream filters can distinguish a confident
   human-vs-human match from a cross-species match where the
   sequence-level hit is real but the antigen specificity may not
   carry over.

3. **Contradictory category detection** — when a clone matches
   multiple DB rows that disagree on an informative ``db_category``
   value, ``db_category`` is set to ``"contradictory"`` rather than
   silently picking the mode. New ``CATEGORY_CONTRADICTORY``
   constant. ``unknown`` is excluded from the disagreement check —
   mixing a real label with ``unknown`` picks the real one.

The category bucket set (``viral``, ``bacterial``, ``self``,
``tumor_self``, ``other``, ``unknown``, ``contradictory``) covers
all of the issue's MART-1 / viral / self / contradictory / other /
unmatched asks: tumor_self subsumes MART-1 (via the curated
TUMOR_SELF_ANTIGEN_PATTERNS list including MART1, NY-ESO-1, MAGE,
WT1, TERT, etc.); "unmatched" maps to ``db_match=False`` with
``db_category=None``.

Tests added (9 new in tes... (continued)

Coverage Stats

6264 of 8150 relevant lines covered (76.86%)

3.07 hits per line

Source File

Press 'n' to go to next uncovered line, 'b' for previous

Source Not Available