microproteins / mhc.py
EmmaScharfmann's picture
Pin MHCflurry to CPU so ZeroGPU does not reject it
ad07374
Raw History Blame Contribute Delete
6.93 kB
"""
MHC class I binding and presentation prediction.
Takes the microprotein sequences that TIS Transformer predicts and asks which
of their peptides could be displayed on the cell surface -- the step that turns
"this ORF is probably translated" into "this ORF could be seen by a T cell".
Uses MHCflurry 2.x (Apache-2.0), not NetMHCpan. NetMHCpan is the field
standard but its academic licence forbids redistribution, so it cannot be
hosted in a public Space. MHCflurry is open, pip-installable, and benchmarks
competitively; where a comparison to NetMHCpan matters, that is a local run the
collaborators can do themselves.
Scope: class I only. MHCflurry does not model class II, and the strongest
genetic risk in type 1 diabetes is class II (HLA-DQ8/DQ2). That is a real
limitation of this demo, not an oversight -- see README.
"""
from dataclasses import dataclass
from functools import lru_cache
import pandas as pd
# HLA class I alleles relevant to type 1 diabetes, plus common references.
# Risk associations are from the T1D genetics literature; the point of the
# grouping is to let someone run the same microprotein against a risk allele
# and a neutral one and see the difference.
T1D_ALLELES = {
"HLA-A*02:01": "Most common class I allele; restricts known preproinsulin "
"and INS-DRiP epitopes",
"HLA-A*24:02": "T1D risk; associated with earlier onset and faster "
"residual beta-cell loss",
"HLA-B*39:06": "Strongest class I T1D risk allele reported",
"HLA-B*18:01": "T1D-associated",
}
REFERENCE_ALLELES = {
"HLA-A*01:01": "Common reference allele",
"HLA-A*11:01": "Common reference allele",
"HLA-B*07:02": "Common reference allele",
"HLA-B*08:01": "Common reference allele",
}
ALL_ALLELES = {**T1D_ALLELES, **REFERENCE_ALLELES}
DEFAULT_ALLELES = ["HLA-A*02:01", "HLA-A*24:02", "HLA-B*39:06"]
# Conventional interpretation cutoffs. These are the field's rules of thumb,
# not hard truths -- they are shown in the UI so nobody reads a rank as a fact.
STRONG_BINDER_PERCENTILE = 0.5
WEAK_BINDER_PERCENTILE = 2.0
@dataclass
class MHCResult:
table: pd.DataFrame
n_peptides: int
alleles: list[str]
error: str | None = None
def _pin_to_cpu() -> None:
"""Keep MHCflurry's torch networks on the CPU.
MHCflurry 2.3 is a PyTorch model and its device defaults to "auto", so on
a GPU box it calls network.to('cuda') during prediction. Under ZeroGPU
that happens in the Gradio worker thread, outside any @spaces.GPU
function, and ZeroGPU rejects it:
RuntimeError: Low-level CUDA init (`torch._C._cuda_init`) reached.
The GPU allocation belongs to TIS Transformer. MHCflurry scores tens of
thousands of peptides in seconds on CPU, so pinning it there costs
nothing and removes the conflict.
Only `backend` is set. The sibling option `gpu_device_nums=[]` would set
CUDA_VISIBLE_DEVICES for the whole process and break the TIS stage.
"""
try:
from mhcflurry.common import configure_pytorch
configure_pytorch(backend="cpu")
except Exception:
# Older or newer MHCflurry without this knob: carry on rather than
# fail, since on a CPU-only box the default already resolves to CPU.
pass
@lru_cache(maxsize=1)
def _load_predictor():
"""Load MHCflurry once per process.
Weights are ~100s of MB and are fetched by `mhcflurry-downloads fetch`.
Deliberately lazy so importing this module never triggers a download.
"""
_pin_to_cpu()
from mhcflurry import Class1PresentationPredictor
return Class1PresentationPredictor.load()
def predictor_available() -> tuple[bool, str]:
"""Check MHCflurry is importable and its weights are present."""
try:
import mhcflurry # noqa: F401
except ImportError:
return False, "mhcflurry is not installed."
try:
_load_predictor()
except Exception as e: # weights missing, or a backend problem
return False, (
f"MHCflurry is installed but its models failed to load: {e}\n"
"Run: mhcflurry-downloads fetch models_class1_presentation"
)
return True, "ok"
def binder_class(percentile: float | None) -> str:
"""Label a presentation percentile with the conventional thresholds."""
if percentile is None:
return "-"
if percentile <= STRONG_BINDER_PERCENTILE:
return "strong"
if percentile <= WEAK_BINDER_PERCENTILE:
return "weak"
return "non-binder"
def predict_presentation(
proteins: dict[str, str],
alleles: list[str] | None = None,
peptide_lengths: tuple[int, ...] = (8, 9, 10, 11),
) -> MHCResult:
"""Score every peptide from every protein against every allele.
`proteins` maps an ORF label to its amino-acid sequence. Returns one row
per peptide with MHCflurry's best allele, affinity and presentation score.
MHCflurry's `predict_sequences` does the tiling itself, which keeps the
peptide-to-source-protein mapping correct for free.
"""
alleles = alleles or DEFAULT_ALLELES
ok, msg = predictor_available()
if not ok:
return MHCResult(pd.DataFrame(), 0, alleles, error=msg)
usable = {
k: v.replace("*", "")
for k, v in proteins.items()
if v and len(v) >= min(peptide_lengths)
}
if not usable:
return MHCResult(
pd.DataFrame(), 0, alleles,
error=f"No protein was long enough to yield a "
f"{min(peptide_lengths)}mer peptide.",
)
predictor = _load_predictor()
_pin_to_cpu() # cheap and idempotent; the predictor may be cached from
# before anything else touched the torch backend
df = predictor.predict_sequences(
sequences=usable,
alleles={"sample": alleles},
result="all",
peptide_lengths=list(peptide_lengths),
use_flanks=True,
verbose=0,
)
rename = {
"sequence_name": "orf",
"peptide": "peptide",
"best_allele": "best_allele",
"affinity": "affinity_nM",
"processing_score": "processing",
"presentation_score": "presentation",
"presentation_percentile": "percentile",
}
df = df.rename(columns={k: v for k, v in rename.items() if k in df.columns})
if "percentile" in df.columns:
df["binder"] = df["percentile"].map(binder_class)
df = df.sort_values("percentile", ascending=True)
elif "presentation" in df.columns:
df = df.sort_values("presentation", ascending=False)
keep = [
c
for c in ["orf", "peptide", "best_allele", "binder", "percentile",
"affinity_nM", "processing", "presentation"]
if c in df.columns
]
keep += [c for c in df.columns if c not in keep]
df = df[keep].reset_index(drop=True)
return MHCResult(df, len(df), alleles)