Lazily validate netMHCpan alleles + round-trip the tool's own spelling

[iskandr]

Problem

Determining a command-line predictor's supported alleles ran e.g. netMHCpan -listMHC and normalized every one of its ~13,000 names through mhcgnomes on every predictor construction. That was slow (~2.45s each), spammed one INFO line per unparseable name, and — more subtly — mis-spelled alleles on the way back out: mhctools re-derived the CLI name via prepare(normalize(user)), which produces a form netMHCpan rejects for ~2,456 (mostly non-human) alleles. E.g. requesting BoLA-1:00901 sent netMHCpan BoLA-109:01 → "cannot be found in hla_pseudo list", so those alleles were unrunnable.

Change: lazy validation + round-trip the predictor's own spelling

• _determine_supported_alleles returns the RAW -listMHC names verbatim (a line split — no mhcgnomes). Cheap and cached per (command, flag).
• Fast validation path: each requested allele is checked with prepare_allele_name(allele) ∈ raw_set. mhcgnomes only ever runs on the user's handful of alleles, so the common human-HLA case never parses the 13k list. First-predictor construction drops ~2.45s → ~0.09s (~27×); the earlier in-memory cache only helped the 2nd predictor onward — this helps the first too.
• Slow path (only on a fast-path miss): build the full {normalized: raw} map once (cached) and look the allele up by normalized name, then pass netMHCpan its own -listMHC spelling on the command line. This fixes the round-trip bug — BoLA-1:00901 now resolves to BoLA-1:00901 and runs end-to-end. ~2,456 previously-unrunnable non-human alleles now work.
• On collision (netMHCpan lists both BoLA-1:00901 and BoLA-100901 for one allele) prefer a colon-containing spelling — the form it actually accepts on -a.
• Logging: no more per-allele "Skipping…" spam — the raw path doesn't normalize, and the lazy map emits only a single DEBUG summary.

Human-HLA identity/output matching is unchanged (self.alleles stays normalized); only the CLI spelling and the timing of normalization change.

Why not fully skip validation

~19% of netMHCpan's own names don't round-trip through normalize→prepare, so a naive prepare(user) ∈ raw_set check with no fallback would falsely reject them. The fast-path-then-normalized-map design keeps validation robust while staying lazy for the common case.

Verified on real netMHCpan 4.2 (Darwin_arm64)

• Human HLA validates without building the normalized map (mhcgnomes runs on user alleles only).
• BoLA-1:00901 resolves to its own spelling and predicts (was impossible before).
• Unsupported alleles still raise UnsupportedAllele.
• All netMHC-family integration tests pass (netMHCpan / netMHCIIpan / netMHCcons / netMHCstabpan).

Tests

tests/test_supported_allele_cache.py (binary-free): raw+cached -listMHC; _determine_supported_alleles runs no mhcgnomes; fast path resolves without building the normalized map; slow path returns the predictor's own spelling; collision prefers the colon form; unsupported raises; no INFO spam.

Version bumped 3.17.0 → 3.18.0.

https://claude.ai/code/session_01LZahFhBSCiehXTESCYQ7wG