Command-line tutorial

This tutorial follows the common workflow: download the released models, score peptides, then scan proteins for candidate ligands. Most users can stop there; training, evaluation, configuration, and exhaustive flag descriptions are linked later.

Download models

Most users need only the presentation bundle. It includes the binding-affinity and antigen-processing components:

$ mhcflurry downloads fetch models_class1_presentation

Downloads are stored outside the Python package in a platform-specific data directory. Use info to list available bundles and path to locate one:

$ mhcflurry downloads path models_class1_presentation
/home/runner/work/mhcflurry/mhcflurry/.mhcflurry-data/2.2.0/models_class1_presentation/

Predict peptides

mhcflurry predict scores individual peptides with the downloaded models:

$ mhcflurry predict --alleles HLA-A0201 HLA-A0301 --peptides SIINFEKL SIINFEKD SIINFEKQ --out /tmp/predictions.csv
Predicting processing.
Predicting affinities.

$ cat /tmp/predictions.csv
allele,peptide,mhcflurry_affinity,mhcflurry_affinity_percentile,mhcflurry_processing_score,mhcflurry_presentation_score,mhcflurry_presentation_percentile
HLA-A0201,SIINFEKL,11927.164294664875,6.296000000000002,0.26470962166786194,0.020690202037635795,11.6303260869565
HLA-A0201,SIINFEKD,30039.7732437649,41.398,0.024963298812508583,0.00367440114530976,99.28660326086957
HLA-A0201,SIINFEKQ,28026.90603463826,30.226250000000004,0.0615493506193161,0.004470086908147677,62.74467391304348
HLA-A0301,SIINFEKL,29871.588371336024,23.19225,0.26470959186553955,0.00858619019343956,27.61739130434782
HLA-A0301,SIINFEKD,33158.80995716571,62.27625,0.024963300675153732,0.003339329916496058,99.28660326086957
HLA-A0301,SIINFEKQ,29705.410284325066,21.8915,0.0615493506193161,0.004225575360616951,62.74467391304348

Output	Interpretation
`mhcflurry_affinity`	Predicted nM affinity; lower is stronger.
`mhcflurry_affinity_percentile`	Allele-specific rank from 0–100; lower is stronger.
`mhcflurry_processing_score`	Allele-independent processing score; higher is stronger.
`mhcflurry_presentation_score`	Combined binding and processing score; higher is stronger.

Affinity thresholds of 500 nM or 2nd percentile are common screening choices. Presentation scores are useful for ranking candidates, but there is no universal presentation-score threshold.

Allele names are parsed as sequence-resolved MHC class I alleles. Invalid, ambiguous, class-II, pseudogene, null, or unsupported names produce a specific error. Add --no-throw when processing mixed-quality tables to keep those rows with NaN predictions instead.

Alleles, genotypes, and samples

MHCflurry treats each allele argument or CSV cell as one query. Delimiters inside a query (;, ,, or whitespace) combine alleles into one genotype; separate command-line arguments remain separate queries.

Input	Meaning
`--alleles A0201 A0301 --peptides P1 P2`	Four independent allele–peptide rows.
`--alleles 'A0201;A0301' --peptides P1 P2`	Two genotype–peptide rows; `best_allele` identifies the stronger allele.
CSV rows `P1,A0201` and `P1,A0301`	Two independent rows.
CSV row `P1,A0201;A0301`	One genotype row with the strongest allele reported.

mhcflurry predict-scan uses the same rule: each --alleles argument names one sample. A quoted comma-separated panel is scored as one group and reports the best allele across that group; separate arguments keep per-allele or per-genotype results. A large population panel is therefore not the same thing as one person’s genotype.

For CSV prediction, optional n_flank and c_flank columns provide source protein context for cleavage prediction. See the command reference for the complete input schema.

Scanning protein sequences for predicted MHC I ligands

Use mhcflurry predict-scan to score every supported peptide window in a protein sequence.

We’ll generate predictions across example.fasta, a FASTA file with two short sequences:

>protein1
MSSSSTPVCPNGPGNCQV
>protein2
MVENKRLLEGMEMIFGQVIPGA

This invocation keeps peptides predicted to bind at 100 nM or tighter:

$ mhcflurry predict-scan example.fasta \
    --alleles HLA-A*02:01 \
    --threshold-affinity 100

See the command reference for FASTA/CSV input, presentation-score filtering, peptide lengths, and output options.

Training models

Training is an advanced workflow; most users should use the released models. If you have custom measurements, choose the smallest workflow that matches the data:

allele-specific affinity models for one or a few well-covered alleles;
pan-allele affinity models for measurements spanning many alleles; or
mhcflurry train pan-allele-release for a complete retrain, selection, calibration, and evaluation run.

The Training models guide covers input schemas, hyperparameters, output bundles, and release-style training without interrupting this prediction tutorial.

Evaluating trained models

After fitting a model, compare it with a released predictor before using it as a default. A local comparison and diagnostic PDF take two commands:

$ mhcflurry eval compare-models \
    --a results/new_run/ \
    --b public \
    --out results/new_run/eval_comparison/

$ mhcflurry eval plot-comparison \
    --input results/new_run/eval_comparison/ \
    --summary-pdf results/new_run/eval_comparison/plots/model_comparison_figures.pdf

The Evaluating trained models guide explains the output layers, saved-prediction schema, paper-style figures, and remote release behavior.

Using older allele-specific models

MHCflurry still distributes the allele-specific predictors described in the 2018 paper. Download them and pass their model directory explicitly:

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

Use the current pan-allele presentation bundle unless you specifically need these historical models.

Configuration and command reference

See Configuration and performance for prediction batches, hardware autosizing, reproducibility, and unified command aliases. The complete generated argument reference is in Command-line reference.