""" 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)