Add predict-table command to annotate CSVs with predictor scores (#231)

.github/workflows/tests.yml

@@ -52,6 +52,7 @@ jobs:
             tests/test_netchop_parse.py \
             tests/test_process_helpers.py \
             tests/test_pred.py \
+            tests/test_annotate_table.py \
             tests/test_processing_predictor.py \
             tests/test_pepsickle.py \
             tests/test_bigmhc.py \

README.md

@@ -372,6 +372,48 @@ mhctools --sequence SIINFEKL SIINFEKLQ --mhc-predictor netmhc --mhc-alleles A020
 mhctools --sequence AAAQQQSIINFEKL --extract-subsequences --mhc-peptide-lengths 8-10 --mhc-predictor mhcflurry --mhc-alleles A0201
 ```
 
+### Annotate an existing table with predictor scores (`predict-table`)
+
+Downstream evaluation workflows often start from an annotated benchmark table
+(with columns like `sample_id`, `hit`, `peptide`, and per-row genotype/allele
+info) and just need external predictor scores appended. `mhctools
+predict-table` reads a CSV, runs each requested predictor once, and appends one
+score column per predictor — choosing the best allele per row — while
+preserving every input column:
+
+```sh
+mhctools predict-table \
+    --input benchmark.csv.bz2 \
+    --peptide-column peptide \
+    --alleles-column hla \
+    --predictor netmhcpan42-ba:netmhcpan4.2.ba:affinity \
+    --predictor netmhcpan42-el:netmhcpan4.2.el:score \
+    --out benchmark.with_scores.csv.bz2
+```
+
+Each `--predictor` spec is `NAME[:OUTPUT_COLUMN[:FIELD]]`, where `FIELD` is
+`affinity`, `score`, or `percentile_rank` (lower is better for `affinity` and
+`percentile_rank`; higher for `score`). Rows may hold several alleles per cell
+(whitespace-, comma-, or semicolon-separated); the best one per peptide is
+chosen and recorded in a `<OUTPUT_COLUMN>_best_allele` provenance column.
+Pass `--predictor-info info.csv` to also write a sidecar describing each
+column's `score_field` and `higher_is_better`.
+
+The same thing from Python (I/O-free, works on any `DataFrame`):
+
+```python
+from mhctools import annotate_table, AnnotationSpec, NetMHCpan42_BA
+
+annotated = annotate_table(
+    df,
+    [AnnotationSpec(
+        predictor=lambda alleles: NetMHCpan42_BA(alleles=alleles),
+        output_column="netmhcpan4.2.ba",
+        field="affinity")],
+    peptide_column="peptide",
+    allele_column="hla")
+```
+
 ## Legacy API
 
 The old `predict_peptides()` and `predict_subsequences()` methods still work

mhctools/__init__.py

@@ -15,6 +15,7 @@
 )
 from .sample import MultiSample
 from .tcr import TCR
+from .annotate import AnnotationSpec, annotate_table, parse_annotation_spec
 from .iedb import (
     IedbNetMHCcons,
     IedbNetMHCpan,
@@ -79,7 +80,7 @@ def __getattr__(name):
     raise AttributeError(
         "module %r has no attribute %r" % (__name__, name))
 
-__version__ = "3.20.1"
+__version__ = "3.21.0"
 
 __all__ = [
     "Prediction",
@@ -95,6 +96,9 @@ def __getattr__(name):
     "preds_from_rows",
     "MultiSample",
     "TCR",
+    "AnnotationSpec",
+    "annotate_table",
+    "parse_annotation_spec",
     "BindingPrediction",
     "BindingPredictionCollection",
     "IedbNetMHCcons",