pirl-unc / tcrsift / 26644524356

Build # 26644524356

Build Type

push

github

Committed by web-flow

Commit Message

2.2.0: fix #56 — structured db_match_score with audit columns (#114)

Adds a composite confidence score and the four sub-signals that feed
it so downstream code can filter by quality (``score >= 0.6``)
instead of treating every β-only fallback the same as a high-quality
αβ exact match.

## New output columns

  - ``db_match_score`` ∈ [0, 1] — composite from the signals below.
  - ``db_v_gene_agreement`` ∈ [0, 1] or None — fraction of matching
    DB rows whose ``v_beta`` matches the clone's ``beta_v_gene``
    (allele suffix stripped, case normalised).
  - ``db_n_studies`` — distinct ``reference`` ids across matching
    rows. Single-study hits get a confidence discount.
  - ``db_category_votes`` — ``"viral:0.67;tumor_self:0.33"`` style
    string summarising the per-category vote shares (paired with the
    pre-existing #83 ``db_category`` / ``db_category_dominant`` /
    ``db_category_detail`` / ``db_category_counts`` audit set).

## Score formula

Documented in ``_compute_match_score``. Base score per strength
label (1.0 αβ exact, 0.7 β-only), multiplicative penalties:
  - 0.7× for ``_near`` (Lev-1 fuzzy β, #57)
  - 0.5× for ``_cross`` (non-human host, #83 / #54)
  - 1 − 0.3 × (1 − v_gene_agreement) for V-gene disagreement
    (1.0 when unknown — neutral)
  - 1 − 0.3 / max(n_studies, 1) — 1 study → 0.7, 2 → 0.85, 3+ → ≥0.9

Score clamped to [0, 1], rounded to 3 decimals for CSV stability.

## DB loader plumbing

VDJdb's paired (``vdjdb_full.txt``) and long (``vdjdb.txt``) formats
now expose V-gene calls as ``v_beta`` / ``v_alpha`` standardised
columns. Long format uses ``v.segm`` for V-gene (per-chain row); the
paired format uses ``v.beta`` / ``v.alpha``. IEDB / CEDAR formats
don't currently carry V-gene info — when ``v_beta`` is absent or
NaN across the match set, ``db_v_gene_agreement`` stays None and
the score uses the neutral V-factor.

## Out of scope

MHC compatibility (``db_mhc_agreement`` in the original issue
proposal) requires plumbing do... (continued)

Coverage Stats

6772 of 8629 relevant lines covered (78.48%)

3.14 hits per line

Source File

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

Source Not Available