Downloading and selecting model weights

Code and weights have separate versions. A code patch can keep the same default weights: the current package uses the 2.3.0 weight release. New weight releases identify changed model artifacts; they need not accompany every code release. Historical catalogue names remain available for reproducibility.

Browse what is available

mhcflurry downloads releases models_class1_presentation
mhcflurry downloads list --kind models
mhcflurry downloads info models_class1_presentation

releases lists valid catalogue identifiers. With a bundle name, it shows only the releases containing that bundle and groups entries with the same archive URLs. For example, catalogues 2.2.0 and 2.0.0 point to the same presentation archive.
list groups prediction models, legacy models, experiments, and supporting data, and shows which are installed. Use --kind data for data only, or --release 2.2.0 to inspect an older catalogue. Reading the model availability table explains its markers.
info DOWNLOAD adds descriptions, archive locations, fetch/use commands and exact embedded component paths.

All three commands support --json and read the installed package’s catalogue offline. Update the package to obtain a newer catalogue.

Bundle	Contents and use
`models_class1_presentation`	Full presentation predictor, including affinity, processing, and their combiner. The normal prediction bundle.
`models_class1_pan`	Selected pan-allele affinity ensemble, for standalone affinity prediction.
`models_class1_processing`	Standalone processing ensembles with and without N/C flanks.
`models_class1`	Legacy allele-specific affinity models. The name does not mean the current general-purpose class I bundle.
`*_unselected`	Candidate networks before ensemble selection.
`_variants`, `_refined`, `*_experiments1`	Historical experimental configurations.
`_with_mass_spec`, `_no_mass_spec`, `*_minimal`	Historical training variants or smaller subsets.
`data_*`, `allele_sequences`, `analysis_predictor_info`, `random_peptide_predictions`, `cross_validation_class1`	Supporting data and analyses.

The presentation bundle contains its own affinity and processing components, so full presentation prediction works even when the standalone bundles are absent. Loading a component predictor by itself behaves differently for each component:

Class1AffinityPredictor.load() can fall back to the default presentation bundle when standalone affinity weights are absent and no affinity-path override is set.
Class1ProcessingPredictor.load() has no such fallback. Pass an embedded component path explicitly, or use Class1PresentationPredictor.load().processing_predictor_with_flanks (or processing_predictor_without_flanks).

Explicit paths and release selection retain their existing precedence.

Compare new and historical weights

The public 2.1.5, 2.2.0, and 2.2.1 packages all used the same 2020 model archives, registered under catalogue 2.2.0. There is no separate 2.1.5 or 2.2.1 weight catalogue.

The 2.3.0 models use the 2023 curated affinity snapshot and an updated processing training recipe; this does not mean every component gained new 2023 observations. See Release training recipe.

Fetch both presentation bundles once:

mhcflurry downloads fetch models_class1_presentation --release 2.3.0
mhcflurry downloads fetch models_class1_presentation --release 2.2.0

Use a CSV with peptide, allele, n_flank, and c_flank columns. An allele cell can contain a semicolon-separated MHC allele set. Run both models on the same rows; available N/C flanks are used by default:

mhcflurry predict eval.csv --model-release 2.3.0 --out new.csv
mhcflurry predict eval.csv --model-release 2.2.0 --out old.csv

For the corresponding comparison without flanks:

mhcflurry predict eval.csv --model-release 2.3.0 --no-flanking --out new-no-flanks.csv
mhcflurry predict eval.csv --model-release 2.2.0 --no-flanking --out old-no-flanks.csv

predict-scan also accepts --model-release. The selector uses a presentation bundle, including when predict --affinity-only requests only its affinity component. It selects installed weights; it does not download them automatically. --models DIR instead selects an arbitrary local predictor and cannot be combined with --model-release.

These commands compare weights using the installed code. Reproducing a historical software version also requires that version in its own environment. See Evaluation of the 2.3.0 weights for the completed comparison across public software versions, NetMHCpan BA/EL outputs, and MixMHCpred on identical rows.

Older allele-specific models

MHCflurry still distributes the allele-specific predictors described in the 2018 paper for reproducing earlier results; for new work, use the current presentation bundle. They are a separate, affinity-only bundle selected with --models rather than --model-release:

mhcflurry downloads fetch models_class1
mhcflurry predict \
    --alleles HLA-A0201 HLA-A0301 \
    --peptides SIINFEKL SIINFEKD SIINFEKQ \
    --models "$(mhcflurry downloads path models_class1)/models" \
    --affinity-only \
    --out predictions.csv

Local storage and overrides

mhcflurry downloads info
mhcflurry downloads path models_class1_presentation --release 2.3.0
mhcflurry downloads url models_class1_presentation --release 2.3.0

info starts with model availability, followed by historical resources and resolved configuration. Use mhcflurry downloads --verbose info for configured default predictor paths, components inside the default presentation predictor, and environment variables.

On macOS the default root is ~/Library/Application Support/mhcflurry/4/; each weight release has its own subdirectory, and the presentation predictor is inside models_class1_presentation/models. The 4 is the cache-layout version, not a model version.

These environment variables are optional overrides. In info output, unset means the default is in use, not that the local path is missing.

Variable	Effect
`MHCFLURRY_DATA_DIR`	Changes the parent of the release directories.
`MHCFLURRY_DOWNLOADS_CURRENT_RELEASE`	Changes the active catalogue.
`MHCFLURRY_DOWNLOADS_DIR`	Selects an unversioned custom download directory.
`MHCFLURRY_DEFAULT_CLASS1_*`	Overrides individual predictor defaults; `info` lists each variable.

An explicit --model-release selects from the requested catalogue instead of those individual model-path overrides.

With an unversioned custom directory, --model-release requires recorded source URLs matching the requested bundle; otherwise it asks you to use a versioned cache or select the local model explicitly with --models. A release selector must not silently load another release’s weights.

“Installed” means a directory exists. “Source matches” means its DOWNLOAD_INFO.csv URLs match the catalogue; it does not verify every file’s integrity. Public model checksums are attached to the corresponding GitHub release. The --release option is supported consistently by fetch, list, info, path, and url.

Why archive tags differ

A catalogue collects many resources. Unchanged older resources keep their original URLs, so a current catalogue can include storage tags such as pre-2.0 alongside 2.3.0. Those tags describe where an archive was uploaded; they do not require prerelease code. Several catalogues can reference the same archive, and a single catalogue can include model and data archives from different dates. Inspect releases DOWNLOAD or info DOWNLOAD to see this mapping explicitly.

Percentile calibration

Released affinity and presentation predictors include percentile calibration; released processing predictors do not. For custom models, or for processing percentiles, Percentile calibration for all predictors documents compact calibration, which uses a small validated knot representation instead of dense histogram tables. Calibration changes percentile mappings, not raw model scores or weights. Use a separate model copy and an appropriate background reference; do not fit calibration to evaluation labels.

Reading the model availability table

The first table printed by mhcflurry downloads list shows the latest weights, distinct older archive versions and installed catalogue directories. The recommended presentation bundle comes first, followed by the standalone affinity and processing bundles. Historical resources appear below the main predictors.

Marker	Meaning
`RELEASE via presentation`	An affinity or processing component found inside an installed presentation bundle. Standalone bundle installs remain separate entries.
`with flanks only`, `without flanks only`	The bundle contains only one processing variant.
`?` or `!` on the presentation bundle	Unknown or different source URLs.

A component appears in the table only if it has a model directory and manifest.csv. These presence checks do not verify weight file integrity or prove that embedded and standalone ensembles are identical.

Aliases sharing the same archive are grouped in the availability columns; releases DOWNLOAD lists every valid identifier. Terminal output uses restrained color; redirected output and NO_COLOR=1 remain plain.

In JSON output, downloaded, status and path still describe the named bundle. The additive presentation_components entries describe embedded paths, directory/manifest presence and the presentation bundle’s source status.