Add predictor MHC context metadata (#210)

Author: iskandr

README.md

@@ -152,10 +152,12 @@ df = ms.predict_dataframe(["SIINFEKL"])
 df = ms.predict_proteins_dataframe({"TP53": "MEEPQ..."})
 ```
 
-### Measurement kinds
+### Measurement kinds and MHC context
 
 Each `Prediction` has a `kind` string describing what it measures:
 
+The canonical prediction kind strings are defined in `mhctools.pred.Kind`.
+
 | Kind | Meaning |
 |---|---|
 | `pMHC_affinity` | Peptide-MHC binding affinity |
@@ -167,6 +169,49 @@ Each `Prediction` has a `kind` string describing what it measures:
 | `tap_transport` | TAP transport score (reserved, not yet used) |
 | `erap_trimming` | ERAP trimming score (reserved, not yet used) |
 
+Predictors also expose `kind_support()` so downstream code can tell what MHC
+context is meaningful for each emitted kind:
+
+```python
+support = predictor.kind_support()
+support["pMHC_affinity"]
+# {"mhc_dependence": "single_allele", "mhc_class": "I"}
+```
+
+`mhc_dependence` is one of:
+
+| Value | Meaning |
+|---|---|
+| `none` | The prediction is MHC-independent; `Prediction.allele` is empty. |
+| `single_allele` | The prediction is for one peptide/MHC allele pair; `Prediction.allele` is part of the key. |
+| `haplotype` | The prediction uses the requested MHC repertoire jointly; `Prediction.allele` may carry best-allele attribution but is not the prediction key. |
+
+`mhc_class` is one of `none`, `I`, `II`, or `both`.
+
+The allowed metadata values are defined in `mhctools.pred` as
+`MHC_DEPENDENCE_VALUES` and `MHC_CLASS_VALUES`.
+
+Examples:
+
+| Predictor | Kind | `mhc_dependence` | `mhc_class` |
+|---|---|---|---|
+| `NetMHCpan41` | `pMHC_affinity` | `single_allele` | `I` |
+| `NetMHCpan41` | `pMHC_presentation` | `single_allele` | `I` |
+| `NetMHCIIpan4_EL` | `pMHC_presentation` | `single_allele` | `II` |
+| `NetMHCstabpan` | `pMHC_stability` | `single_allele` | `I` |
+| `MHCflurry` | `pMHC_affinity` | `single_allele` | `I` |
+| `MHCflurry` haplotype mode | `pMHC_presentation` | `haplotype` | `I` |
+| `MHCflurry` per-allele panel mode | `pMHC_presentation` | `single_allele` | `I` |
+| `Pepsickle` | `proteasome_cleavage` | `none` | `none` |
+
+For MHCflurry presentation, `presentation_allele_mode="haplotype"` treats the
+requested alleles as one sample genotype and emits one `pMHC_presentation`
+record per peptide. The `allele` field carries MHCflurry's `best_allele`
+attribution when available. `presentation_allele_mode="per_allele"` treats each
+allele as a separate one-allele synthetic sample and emits one presentation
+record per peptide/allele pair. The default `"auto"` mode uses haplotype mode
+for up to six alleles and per-allele mode for larger allele panels.
+
 ### The Prediction object
 
 Every prediction is a frozen, self-contained `Prediction` dataclass:

mhctools/__init__.py

@@ -1,6 +1,15 @@
 from .binding_prediction import BindingPrediction
 from .binding_prediction_collection import BindingPredictionCollection
-from .pred import Prediction, Pred, PeptideResult, PeptidePreds, Kind, preds_from_rows
+from .pred import (
+    Kind,
+    MHC_CLASS_VALUES,
+    MHC_DEPENDENCE_VALUES,
+    PeptidePreds,
+    PeptideResult,
+    Pred,
+    Prediction,
+    preds_from_rows,
+)
 from .sample import MultiSample
 from .iedb import (
     IedbNetMHCcons,
@@ -63,14 +72,16 @@ def __getattr__(name):
     raise AttributeError(
         "module %r has no attribute %r" % (__name__, name))
 
-__version__ = "3.13.6"
+__version__ = "3.13.7"
 
 __all__ = [
     "Prediction",
     "Pred",  # backward compat alias
     "PeptideResult",
     "PeptidePreds",  # backward compat alias
     "Kind",
+    "MHC_CLASS_VALUES",
+    "MHC_DEPENDENCE_VALUES",
     "preds_from_rows",
     "MultiSample",
     "BindingPrediction",

mhctools/base_predictor.py

@@ -19,7 +19,11 @@
 
 from .unsupported_allele import UnsupportedAllele
 from .binding_prediction_collection import BindingPredictionCollection
-from .pred import Prediction, Kind, PeptideResult
+from .pred import (
+    Kind,
+    PeptideResult,
+    Prediction,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -101,6 +105,7 @@ class BasePredictor(object):
     flank_length = 15
     n_flank_length = None
     c_flank_length = None
+    mhc_class = "I"
 
     def __init__(
             self,
@@ -331,6 +336,20 @@ def _default_pred_kind(self):
         """Override in subclasses to set the Kind for compat conversion."""
         return Kind.pMHC_affinity
 
+    def kind_support(self):
+        """Predictor-specific MHC context for supported prediction kinds."""
+        return {
+            self._default_pred_kind(): {
+                "mhc_dependence": "single_allele",
+                "mhc_class": self.mhc_class,
+            }
+        }
+
+    @property
+    def supported_kinds(self):
+        """Prediction kind strings this predictor can emit."""
+        return tuple(self.kind_support())
+
     # --- deprecated API (still works) ---
 
     def predict_peptides(self, peptides):

mhctools/bigmhc.py

@@ -31,7 +31,12 @@
 import pandas as pd
 import torch
 
-from .pred import Kind, Prediction, PeptideResult, COLUMNS
+from .pred import (
+    COLUMNS,
+    Kind,
+    PeptideResult,
+    Prediction,
+)
 
 
 def _find_bigmhc_dir(bigmhc_path=None):
@@ -133,6 +138,18 @@ def _pred_kind(self):
             return Kind.immunogenicity
         return Kind.pMHC_presentation
 
+    def kind_support(self):
+        return {
+            self._pred_kind(): {
+                "mhc_dependence": "single_allele",
+                "mhc_class": "I",
+            }
+        }
+
+    @property
+    def supported_kinds(self):
+        return tuple(self.kind_support())
+
     def _predictor_name(self):
         return "bigmhc_%s" % self.mode
 

mhctools/iedb.py

@@ -325,6 +325,8 @@ def __init__(
 IEDB_MHC_CLASS_II_URL = "http://tools-cluster-interface.iedb.org/tools_api/mhcii/"
 
 class IedbNetMHCIIpan(IedbBasePredictor):
+    mhc_class = "II"
+
     def __init__(
             self,
             alleles,