Add specificity databases and immvoke annotate

.github/workflows/ci.yml

@@ -28,7 +28,11 @@ jobs:
       - name: Install package
         run: pip install .
       - name: Unit tests
-        run: python -m unittest discover -v
+        # Specificity keeps its tests beside its source (see pyproject.toml),
+        # where discovery from the top level does not reach.
+        run: |
+          python -m unittest discover -v
+          python -m unittest discover -v -s src/immvoke/Sources/Specificity/tests -t src
 
   python-versions:
     runs-on: ubuntu-latest
@@ -46,7 +50,11 @@ jobs:
           python -m pip install --upgrade pip
           pip install .
       - name: Unit tests
-        run: python -m unittest discover -v
+        # Specificity keeps its tests beside its source (see pyproject.toml),
+        # where discovery from the top level does not reach.
+        run: |
+          python -m unittest discover -v
+          python -m unittest discover -v -s src/immvoke/Sources/Specificity/tests -t src
 
   # Proves that the packaged schema snapshots and the runtime dependencies both
   # ship in the wheel. Running from /tmp guarantees the source tree cannot be

.github/workflows/release.yml

@@ -78,7 +78,11 @@ jobs:
           python -m pip install --upgrade pip build twine
           pip install .
       - name: Unit tests
-        run: python -m unittest discover -v
+        # Specificity keeps its tests beside its source (see pyproject.toml),
+        # where discovery from the top level does not reach.
+        run: |
+          python -m unittest discover -v
+          python -m unittest discover -v -s src/immvoke/Sources/Specificity/tests -t src
       - name: Build sdist and wheel
         run: python -m build
       - name: Check distribution metadata

NEWS.rst

@@ -1,6 +1,42 @@
 Release Notes
 ================================================================================
 
+Unreleased
+-------------------------------------------------------------------------------
+
+Specificity:
+
++ Added specificity databases IEDB_, CoV-AbDab_ and ASD_ under
+  ``immvoke specificity <db> search|download``, and ``immvoke specificity
+  bcr`` as a shortcut for IEDB's BCR table, downloaded as a schema-validated
+  AIRR rearrangement TSV with one record per chain, linked by ``cell_id``,
+  taking IEDB's calculated (IMGT standardized) V/D/J-gene calls over the
+  curated ones, and keeping human receptors only.
++ Each specificity download lands in its database's own folder,
+  ``<outdir>/<db>/``: the normalized ``<table>.tsv``, ``raw/`` and its own
+  ``download_metadata.yml``.
++ Added ``immvoke annotate``, to annotate a query AIRR table against a
+  reference one (e.g. IEDB's BCR table) through symscan_: the heavy chain
+  CDR3, full VDJ or pooled CDR1-3 (``--sequence-region``), within the same
+  V/J-gene (``--partition-by``), exact or at an identity threshold
+  (``--identity-threshold``) under Hamming or Levenshtein distance
+  (``--distance-metric``), or heavy+light chain of the same antibody
+  (``--paired``, one chain of each kind per cell picked by
+  ``--count-field``).
++ ``immvoke annotate --outdir`` writes ``annotation.tsv`` (the hits per
+  query), ``annotation_pairs.tsv`` (one scored row per query and reference
+  pair: the hits of an exact match, or every pair through the chosen
+  filters of a Hamming or Levenshtein run, whatever its distance, with
+  ``within_threshold`` marking the hits) and ``annotation_metadata.yml``
+  (the options, inputs, reference database and counts of the run), each
+  named after the reference's database and table, e.g.
+  ``iedb_bcr_annotation.tsv``.
+
+.. _IEDB: https://www.iedb.org/
+.. _CoV-AbDab: https://opig.stats.ox.ac.uk/webapps/covabdab/
+.. _ASD: https://naturalantibody.com/agab/
+.. _symscan: https://github.com/yutanagano/symscan
+
 Version 0.1.0: 2026.09.28
 -------------------------------------------------------------------------------
 

pyproject.toml

@@ -37,6 +37,17 @@ dependencies = [
     "pandas>=2.2.3",
     "airr>=2.0",
     "tqdm>=4.64",
+    # ASD's data unit is a Delta Lake of Parquet partitions, staged in a
+    # Google Drive folder: pyarrow reads the partitions, gdown fetches the
+    # folder, since it has no plain HTTP download. The floor is 16 for the
+    # same reason as the pandas floor above: pyarrow wheels before 16 were
+    # built against numpy 1.x and fail to import under numpy>=2.
+    "pyarrow>=16",
+    "gdown>=5.0",
+    # Symscan.py: annotate's matching engine for exact, Hamming and
+    # Levenshtein matching (a Rust symmetric-deletion index; numpy, which it
+    # returns its pairs in, comes with it and with pandas).
+    "symscan>=0.8",
 ]
 
 [project.optional-dependencies]
@@ -56,6 +67,11 @@ path = "src/immvoke/Version.py"
 # automatically as part of the package. Do not add a force-include for them: it
 # duplicates every file and the build fails.
 packages = ["src/immvoke"]
+# Specificity's own tests live alongside its source
+# (Sources/Specificity/tests/) rather than under the top level tests/
+# directory; exclude them here so a built wheel still ships no test code,
+# matching every other source under src/immvoke.
+exclude = ["src/immvoke/Sources/Specificity/tests/*"]
 
 [tool.ruff]
 line-length = 90

requirements.txt

@@ -4,3 +4,6 @@ PyYAML>=6.0
 pandas>=2.2.3
 airr>=2.0
 tqdm>=4.64
+pyarrow>=16
+gdown>=5.0
+symscan>=0.8