Use mhctools.best_direction; bump floor to 3.14.1

mhctools 3.14.1 ships ``best_direction(kind, field)`` (openvax/mhctools#212,
closes #211). Drop topiary's local ``_BEST_FIELD_DIRECTIONS`` /
``_BEST_VALUE_DIRECTIONS`` / ``_best_direction`` and import the
canonical helper instead — the direction table is mhctools-canonical
metadata and shouldn't live in two places.

- ``topiary/ranking/nodes.py``: replace the local table + helper with
  ``from mhctools import best_direction as _best_direction``.
- ``requirements.txt``: bump mhctools floor 3.13.7 → 3.14.1.
- ``tests/test_best_allele.py``: match the upstream error message
  ("best_direction undefined" instead of "best_value direction is
  undefined").
- Bump topiary 5.12.0 → 5.13.0 (additive minor — the mhctools floor
  bump tightens deps, but no public API change).

Author: iskandr

requirements.txt

@@ -1,6 +1,6 @@
 numpy>=2.0.0,<3.0.0
 pandas>=2.0.0
-mhctools>=3.13.7
+mhctools>=3.14.1
 varcode>=0.3.17
 gtfparse>=0.0.4
 mhcnames

tests/test_best_allele.py

@@ -234,7 +234,8 @@ def test_value_undefined_for_presentation_raises(self, presentation_df):
         # value direction is kind-dependent and not registered for
         # pMHC_presentation. Asking for best_value should raise loudly.
         ctx = EvalContext(presentation_df)
-        with pytest.raises(ValueError, match="best_value direction is undefined"):
+        # Error message comes from mhctools.best_direction.
+        with pytest.raises(ValueError, match="best_direction undefined"):
             Presentation["mhcflurry"].best_value.eval(ctx)
 
     def test_affinity_best_value_is_min(self):

topiary/__init__.py

@@ -53,7 +53,7 @@
 from .result import TopiaryResult, concat
 from .wide import detect_form, from_wide, to_wide
 
-__version__ = "5.12.0"
+__version__ = "5.13.0"
 
 __all__ = [
     "TopiaryPredictor",

topiary/ranking/nodes.py

@@ -723,55 +723,16 @@ def to_ast_string(self):
     # (Scoped fields cannot appear in filters — guarded in Comparison.__init__)
 
 
-# Direction conventions: which way is "best" for a given (kind, field).
-# - ``score``: higher is better, every kind (binding strength,
-#   presentation likelihood, immunogenicity, processing).
-# - ``percentile_rank``: 0 means best — min is better, every kind.
-# - ``value``: kind-dependent — pMHC_affinity uses IC50 nM (lower
-#   better); pMHC_stability would use half-life in hours (higher
-#   better). Required entry per kind.
-_BEST_FIELD_DIRECTIONS = {
-    "score": "max",
-    "percentile_rank": "min",
-}
-
-_BEST_VALUE_DIRECTIONS = {
-    "pMHC_affinity": "min",   # IC50 nM
-    "pMHC_stability": "max",  # half-life
-}
+# Canonical "best direction" per (kind, field) lives upstream in
+# mhctools (since 3.14.0) so consumers don't replicate the table —
+# see openvax/mhctools#211.
+from mhctools import best_direction as _best_direction  # noqa: E402
 
 
 def _field_short(field: str) -> str:
     return "rank" if field == "percentile_rank" else field
 
 
-def _best_direction(kind, field):
-    """Return ``"max"`` or ``"min"`` for a (kind, field) pair.
-
-    Raises ``ValueError`` for ``field='value'`` on a kind without a
-    registered direction — `value` semantics are kind-dependent and we
-    refuse to guess. New `value`-bearing kinds need an entry in
-    :data:`_BEST_VALUE_DIRECTIONS`.
-    """
-    direction = _BEST_FIELD_DIRECTIONS.get(field)
-    if direction is not None:
-        return direction
-    if field == "value":
-        kind_name = _kind_name(kind)
-        if kind_name not in _BEST_VALUE_DIRECTIONS:
-            raise ValueError(
-                f"best_value direction is undefined for kind "
-                f"{kind_name!r} — `value` semantics depend on the kind "
-                f"(IC50 vs half-life vs ...). Add an entry to "
-                f"topiary.ranking.nodes._BEST_VALUE_DIRECTIONS."
-            )
-        return _BEST_VALUE_DIRECTIONS[kind_name]
-    raise ValueError(
-        f"No best-direction defined for field {field!r}. "
-        f"Known: {sorted(_BEST_FIELD_DIRECTIONS) + ['value']}."
-    )
-
-
 class BestAlleleField(DSLNode):
     """Per-peptide aggregation of a (kind, field) value across alleles.
 
@@ -781,9 +742,9 @@ class BestAlleleField(DSLNode):
     (``return_allele=True``) to every per-(peptide, allele) entry in
     ``ctx.group_index``. Composes naturally with the rest of the DSL.
 
-    Direction is taken from :func:`_best_direction`: ``score`` is max,
-    ``percentile_rank`` is min, ``value`` is per-kind (IC50 → min,
-    half-life → max).
+    Direction is taken from :func:`mhctools.best_direction`: ``score``
+    is max, ``percentile_rank`` is min, ``value`` is per-kind (IC50 →
+    min, half-life → max).
 
     **Semantics depend on the upstream predictor's allele mode.** With
     mhctools >=3.13.7 these are reported via ``predictor.kind_support()``: