[ssnn-airr]

Summary

Adds antigen specificity annotation to immvoke in two separate steps:

1. Download public specificity databases (immvoke specificity).
2. Annotate your own AIRR repertoire against one of them (immvoke annotate).

Usage is in Sources/Specificity/README.md; the matching rules and design are in idea.md. Those two files are the best place to start reviewing.

immvoke specificity: database downloads

• Databases: IEDB, CoV-AbDab and ASD, via immvoke specificity <db> search|download, immvoke specificity all download, and immvoke specificity bcr as a shortcut for IEDB's BCR table.
• IEDB BCR table: taken from IEDB's own AIRR export.
  • schema-validated, one record per chain, linked by cell_id
  • uses IEDB's calculated (IMGT standardized) gene calls
  • keeps human receptors only
• Layout: each database gets its own folder, so several can share one --outdir:

  databases/iedb/
  ├── bcr.tsv                  # the reference for annotate
  ├── bcr.tsv.validation.txt
  ├── download_metadata.yml    # source, license, citation, time, command
  └── raw/
  

immvoke annotate

Matches a query AIRR table against a reference table:

Option	Choices
--sequence-region	CDR3H (default), VDJ, CDRs (CDR1-3 pooled)
--partition-by	none, V, VJ, VJL (same gene, any allele; VJL also requires the same CDR3 length)
--identity-threshold	exact by default, or a fraction in (0, 1]
--distance-metric	hamming, levenshtein
--paired	heavy and light chain must match the same reference antibody; --count-field picks one chain of each per cell

• Matching engine: symscan finds the hits.
• Rows beyond symscan's limits: these (over 14 differences, or very long sequences at loose thresholds) are scored directly in numpy instead, so no row misses a hit.
• Gene calls: compared at gene level, any allele.
• X residues: match any residue under exact and Hamming matching.
• Blank values: never match.

Output: --outdir holds three files, each named after the reference's database and table:

annotation/F09_exact/
├── iedb_bcr_annotation.tsv            # one row per query (by its sequence_id): its hits
├── iedb_bcr_annotation_pairs.tsv      # one scored row per (query, reference) pair
└── iedb_bcr_annotation_metadata.yml   # options, inputs, reference database, counts, version, command

• Exact runs: the pairs file lists the hits.
• Hamming and Levenshtein runs: it lists every pair through the chosen filters, whatever its distance, with within_threshold marking the hits.

Dependencies

• New: symscan>=0.8 (matching), pyarrow>=16 and gdown>=5.0 (for ASD's Parquet data on Google Drive).
• Unchanged: the pandas and numpy floors.

Tests and CI

• Test location: Specificity's tests live beside its source. CI runs them as a separate step, and they are excluded from the wheel.
• Correctness: symscan's results and the direct scorer (Distances.py) are both checked against a brute-force matcher on seeded random tables covering X residues, blanks, duplicate IDs, gene and exact gates, pooled columns and fractional thresholds.
• Real data: checked on one sample (F09, about 21k heavy chains) against IEDB.
• CI: all checks pass (lint, docs, min-deps, Python 3.11–3.14, wheel).

Known limits

• Reference tables: only IEDB's bcr table is AIRR so far. CoV-AbDab and ASD download in their own columns and can't be used as a reference yet.
• Receptor types: antibodies only, no TCR. No BLOSUM scoring.
• Query cdr3_aa: the query needs cdr3_aa in the AIRR definition (without the flanking C and W/F). Change-O clone-pass tables have only junction_aa, so cdr3_aa must be added before annotating.
• Pairs file size: without --partition-by, a Hamming or Levenshtein pairs file covers every query against every reference: millions of rows per sample under Hamming, about 10⁸ under Levenshtein. --partition-by VJ keeps it manageable.

🤖 Generated with Claude Code

[ggabernet]

General comments:

The immvoke specificity iedb downlaod all --outdir . is either haning or very slow. Could you fix that or investigate why is it slow? It's stuck at the tcr.tsv download.

1. General comments for immvoke specificity download:

• allow choosing species with additional param (air_species). If not specified then download all.
• allow choosing assay outcomes with additional param. If not specified then download all.
• allow choosing antigen type with:
  "immvoke bcr
  -allow choosing antigen species with (if applicable). Follow the same vocabulary as in iedb:
  "immvoke specificity iedb download --antigen-species "Influenza A"

[ggabernet]

What are these schemas for?

[pramodsshinde]

This is consistent with what @ssnn-airr has for the base repo. I read it is more like a config file when reading the database in the download/search options.

[pramodsshinde]

@ggabernet Thanks for going over the repo and adding comments. I resolved most of the comments and concerns you raised! Please have another look when you get a chance and let me know if I missed anything or anything is still confusing.