Command-line reference

For each command documented here, mhcflurry <command> --help shows the same options in a terminal; set NO_COLOR=1 to disable colored help. Other mhcflurry eval and mhcflurry train subcommands, and the mhcflurry pseudosequences subcommands, appear only in the namespace listings below; run the subcommand’s --help for their options. Historical mhcflurry-* script names remain available; see Configuration and performance.

Prediction and data

See Downloading and selecting model weights for bundle descriptions, local paths, and selecting older weights with --model-release.

mhcflurry predict

Predict binding affinity, antigen processing and presentation for peptides.

Provide a CSV or use –alleles and –peptides. Use –affinity-only for binding affinity alone. Results go to stdout unless –out is given.

Examples:

mhcflurry predict INPUT.csv –out RESULT.csv mhcflurry predict –alleles HLA-A0201 –peptides SIINFEKL DENDREKLLL mhcflurry predict –alleles ‘HLA-A*02:01;HLA-A*03:01’ –peptides SIINFEKL

CSV columns: allele, peptide, n_flank and c_flank. Available N/C flanks are used by default; use –no-flanking to compare without sequence context. Flank columns may be omitted when context is unavailable. Input columns are preserved in the output. Separate –alleles arguments are independent queries, each scored against every peptide. Delimit alleles within a CSV cell or quoted argument with commas, semicolons or spaces to score one MHC allele set; its row reports the strongest binding allele.

usage: mhcflurry predict [OPTIONS] [INPUT.csv]

input.csv

Input CSV

--alleles <allele>

MHC allele or allele-set queries (exclusive with an input CSV). Separate arguments are independent queries; delimit alleles within one argument with ‘;’ or ‘,’ to score them as one MHC allele set.

--peptides <peptide>

Peptides to predict (exclusive with passing an input CSV)

--allele-column <name>

Input column name for MHC allele or delimited allele-set queries. Default: ‘allele’

--peptide-column <name>

Input column name for peptides. Default: ‘peptide’

--n-flank-column <name>

Column giving N-terminal flanking sequence. Default: ‘n_flank’

--c-flank-column <name>

Column giving C-terminal flanking sequence. Default: ‘c_flank’

--no-throw

Return NaNs for unsupported alleles or peptides instead of raising

--out <output.csv>

Output CSV

--prediction-column-prefix <name>

Prefix for output column names. Default: mhcflurry_

--output-delimiter <char>

Delimiter character for results. Default: ‘,’

--no-affinity-percentile

Do not include affinity percentile rank

--always-include-best-allele

Always include the best_allele column even when it is identical to the allele column (i.e. all queries are monoallelic).

--models <dir>

Directory containing models. Either a binding affinity predictor or a presentation predictor can be used. Default: /home/runner/work/mhcflurry/mhcflurry/.mhcflurry-data/2.3.0/models_class1_presentation/models

--model-release <release>

Use the presentation weights from a download release, overriding model path defaults. List choices: mhcflurry downloads releases models_class1_presentation.

--affinity-only

Affinity prediction only (no antigen processing or presentation)

--no-flanking

Do not use flanking sequence information even when available

--num-jobs <n>

Number of local prediction worker processes. Pass ‘auto’ (default) to size from detected CUDA capacity, host memory and work items; CPU/MPS run serially. Pass 0 for serial prediction.

--backend {auto,default,gpu,mps,cpu}

Device backend. ‘auto’ (default) selects GPU > MPS > CPU. When –gpus is set, GPU-assigned workers use CUDA.

--gpus <n>

Number of CUDA GPUs to assign across parallel prediction workers. Defaults to all visible CUDA devices with the auto or gpu backend. When CUDA_VISIBLE_DEVICES is set, this is a count within that scheduler-visible mask. Requires –num-jobs > 0.

--max-workers-per-gpu <n>

Maximum prediction workers to assign to each CUDA GPU. Pass ‘auto’ (default) to choose from detected free VRAM, or an int to pin.

--max-tasks-per-worker <n>

Restart workers after N prediction chunks.

--worker-log-dir <worker_log_dir>

Write prediction worker stdout and stderr logs to this directory.

--torch-compile {auto,0,1}

Enable torch.compile for forward kernels. ‘auto’ reads MHCFLURRY_TORCH_COMPILE (off when unset). CUDA only.

--matmul-precision {none,highest,high,medium}

torch.set_float32_matmul_precision setting. CPU/MPS: no-op.

-h, --help

Show this help message and exit

--list-supported-alleles

Prints the list of supported alleles and exits

--list-supported-peptide-lengths

Prints the list of supported peptide lengths and exits

--version

show program’s version number and exit

mhcflurry predict-scan

Scan proteins for peptide presentation using a CSV, FASTA or –sequences.

With –alleles, return peptides with affinity percentile ranks at most 2.0 by default. Use –results-all for every peptide or –threshold-* to change the filters. Without –alleles, predict processing only. Results go to stdout unless –out is given.

Examples:

mhcflurry predict-scan proteins.fasta –alleles HLA-A0201 –out hits.csv mhcflurry predict-scan proteins.csv –alleles ‘HLA-A*02:01;HLA-A*03:01’ mhcflurry predict-scan –sequences SIINFEKLGGGNLVPMVATV –alleles HLA-A0201

CSV columns: sequence_id, sequence. Each –alleles argument is one sample; delimit alleles within a quoted argument with commas or semicolons to give a sample MHC allele set.

usage: mhcflurry predict-scan [OPTIONS] [INPUT]

input

Input CSV or FASTA

--input-format {guess,csv,fasta}

Format of input file. By default, it is guessed from the file extension.

--alleles <allele>

Sample MHC allele or allele-set queries. Each argument is one sample; delimit alleles within a sample with ‘,’ or ‘;’.

--sequences <seq>

Sequences to predict (exclusive with passing an input file)

--sequence-id-column <name>

Input CSV column name for sequence IDs. Default: ‘sequence_id’

--sequence-column <name>

Input CSV column name for sequences. Default: ‘sequence’

--no-throw

Return NaNs for unsupported alleles or peptides instead of raising

--peptide-lengths <l>

Peptide lengths to consider. Pass as START-END (e.g. 8-11) or a comma-separated list (8,9,10,11). When using START-END, the range is INCLUSIVE on both ends. Default: 8-11.

--results-all

Disable the default affinity-percentile filter. Explicit thresholds still apply.

--threshold-presentation-score <threshold_presentation_score>

Keep presentation scores >= this value. No default filter on this score.

--threshold-processing-score <threshold_processing_score>

Keep processing scores >= this value. No default filter on this score.

--threshold-affinity <threshold_affinity>

Keep predicted affinities <= this value in nM. No default filter on nM affinity.

--threshold-affinity-percentile <threshold_affinity_percentile>

Keep affinity percentiles <= this value. Defaults to 2.0 when no thresholds or –results-all are supplied.

--out <output.csv>

Output CSV

--output-delimiter <char>

Delimiter character for results. Default: ‘,’

--no-affinity-percentile

Do not include affinity percentile rank

--models <dir>

Directory containing presentation models. Default: /home/runner/work/mhcflurry/mhcflurry/.mhcflurry-data/2.3.0/models_class1_presentation/models

--model-release <release>

Use the presentation weights from a download release, overriding model path defaults. List choices: mhcflurry downloads releases models_class1_presentation.

--no-flanking

Do not use flanking sequence information in predictions

--num-jobs <n>

Number of local prediction worker processes. Pass ‘auto’ (default) to size from detected CUDA capacity, host memory and work items; CPU/MPS run serially. Pass 0 for serial prediction.

--backend {auto,default,gpu,mps,cpu}

Device backend. ‘auto’ (default) selects GPU > MPS > CPU. When –gpus is set, GPU-assigned workers use CUDA.

--gpus <n>

Number of CUDA GPUs to assign across parallel prediction workers. Defaults to all visible CUDA devices with the auto or gpu backend. When CUDA_VISIBLE_DEVICES is set, this is a count within that scheduler-visible mask. Requires –num-jobs > 0.

--max-workers-per-gpu <n>

Maximum prediction workers to assign to each CUDA GPU. Pass ‘auto’ (default) to choose from detected free VRAM, or an int to pin.

--max-tasks-per-worker <n>

Restart workers after N prediction chunks.

--worker-log-dir <worker_log_dir>

Write prediction worker stdout and stderr logs to this directory.

--torch-compile {auto,0,1}

Enable torch.compile for forward kernels. ‘auto’ reads MHCFLURRY_TORCH_COMPILE (off when unset). CUDA only.

--matmul-precision {none,highest,high,medium}

torch.set_float32_matmul_precision setting. CPU/MPS: no-op.

-h, --help

Show this help message and exit

--list-supported-alleles

Print the list of supported alleles and exit

--list-supported-peptide-lengths

Print the list of supported peptide lengths and exit

--version

show program’s version number and exit

mhcflurry downloads

Browse, download and locate released weights and supporting data.

Start here:

mhcflurry downloads releases models_class1_presentation mhcflurry downloads list –kind models mhcflurry downloads info models_class1_presentation mhcflurry downloads fetch models_class1_presentation –release 2.2.0 mhcflurry predict INPUT.csv –model-release 2.2.0

Download releases are catalogue versions, separate from the installed code. Browsing uses the catalogue shipped with this package; no network is required.

usage: mhcflurry downloads [-h] [--quiet] [--verbose]
                           {fetch,info,list,releases,path,url} ...

-h, --help

show this help message and exit

--quiet

Output less

--verbose, -v

Output more

mhcflurry downloads fetch

usage: mhcflurry downloads fetch [-h] [--keep] [--release RELEASE]
                                 [--already-downloaded-dir DIR]
                                 [DOWNLOAD ...]

download

Items to download

-h, --help

show this help message and exit

--keep

Don’t delete archives after they are extracted

--release <release>

Release to download. Default: 2.3.0

--already-downloaded-dir <dir>

Don’t download files, get them from DIR

mhcflurry downloads info

usage: mhcflurry downloads info [-h] [--json] [--release RELEASE] [DOWNLOAD]

download

-h, --help

show this help message and exit

--json

Print machine-readable JSON

--release <release>

Catalogue release (default: configured release)

mhcflurry downloads list

usage: mhcflurry downloads list [-h] [--kind {all,models,data}] [--json]
                                [--release RELEASE]

-h, --help

show this help message and exit

--kind {all,models,data}

--json

Print machine-readable JSON

--release <release>

Catalogue release (default: configured release)

mhcflurry downloads path

usage: mhcflurry downloads path [-h] [--release RELEASE] [download_name]

download_name

-h, --help

show this help message and exit

--release <release>

Catalogue release (default: configured release)

mhcflurry downloads releases

usage: mhcflurry downloads releases [-h] [--json] [DOWNLOAD]

download

-h, --help

show this help message and exit

--json

Print machine-readable JSON

mhcflurry downloads url

usage: mhcflurry downloads url [-h] [--release RELEASE] download_name

download_name

-h, --help

show this help message and exit

--release <release>

Catalogue release (default: configured release)

Training and model selection

See Training models for choosing between these commands. Training commands fit candidate models; selection commands choose the ensemble members to keep.

mhcflurry class1-train-allele-specific-models

usage: 
Train Class1 single allele models.

-h, --help

show this help message and exit

--data <file.csv>

Training data CSV. Expected columns: allele, peptide, measurement_value

--out-models-dir <dir>

Directory to write models and manifest

--hyperparameters <file.json>

JSON or YAML of hyperparameters

--allele <allele>

Alleles to train models for. If not specified, all alleles with enough measurements will be used.

--min-measurements-per-allele <n>

Train models for alleles with >=N measurements.

--held-out-fraction-reciprocal <n>

Hold out 1/N fraction of data (for e.g. subsequent model selection. For example, specify 5 to hold out 20 percent of the data.

--held-out-fraction-seed <n>

Seed for randomizing which measurements are held out. Only matters when –held-out-fraction-reciprocal is specified. When omitted, the held-out split is derived from –random-seed (so the whole run reproduces from one value). Pass this explicitly to control the split directly — e.g. to reproduce a pre-2.3.0 split — overriding –random-seed for the split.

--random-seed <n>

Master random seed for this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Default: 42. Exact numerical results can still vary with hardware, library versions and nondeterministic kernels.

--ignore-inequalities

Do not use affinity value inequalities even when present in data

--n-models <n>

Ensemble size, i.e. how many models to train for each architecture. If specified here it overrides any ‘n_models’ specified in the hyperparameters.

--max-epochs <n>

Max training epochs. If specified here it overrides any ‘max_epochs’ specified in the hyperparameters.

--allele-sequences <file.csv>

Allele sequences file. Used for computing allele similarity matrix.

--save-interval <n>

Write models to disk every N seconds. Only affects parallel runs; serial runs write each model to disk as it is trained.

--verbosity <verbosity>

Verbosity. Default: 0

--num-jobs <n>

Number of local processes to parallelize training over. Pass ‘auto’ (default) to derive from --gpus * --max-workers-per-gpu once the latter is resolved (so workers never overflow to CPU silently). Pass 0 for serial run, or an int to pin.

--backend {auto,default,gpu,mps,cpu}

Device backend. ‘default’ is a legacy alias for ‘auto’. ‘gpu’ means CUDA. ‘auto’ (default) selects the best available device: GPU > MPS > CPU. When –gpus is set, GPU-assigned workers use CUDA and overflow workers are forced to CPU.

--gpus <n>

Number of CUDA GPUs to assign across parallel workers. When CUDA_VISIBLE_DEVICES is set, this is a count within that scheduler-visible mask. Requires –num-jobs > 0. Each assigned worker gets one GPU; workers beyond –gpus * –max-workers-per-gpu run on CPU.

--max-workers-per-gpu <n>

Maximum number of workers to assign to a GPU. Pass ‘auto’ (default) to pick a value based on detected free VRAM, the estimated per-worker working set, and a shared safety reserve (see auto_max_workers_per_gpu). Pass an integer to pin. Workers beyond --gpus * --max-workers-per-gpu run on CPU.

--max-tasks-per-worker <n>

Restart workers after N tasks. Workaround for memory leaks.

--worker-log-dir <worker_log_dir>

Write worker stdout and stderr logs to given directory.

--dataloader-num-workers <n>

Per-fit-worker DataLoader child count for streaming pretraining. Pass ‘auto’ (default) to derive from box vCPUs / RAM / fit-worker plan via mhcflurry.parallelism.auto_dataloader_num_workers (empirical throughput cap = 4). Pass an integer to pin (0 builds pretraining batches in-process). Overrides any dataloader_num_workers set in component-model hyperparameters when applicable; non-affinity train commands accept the flag for uniformity but currently no-op.

--random-negative-pool-epochs <n>

Number of consecutive epochs that share a pre-encoded random-negative pool. Pass ‘auto’ (default) to size from system RAM / fit-worker plan via mhcflurry.parallelism.auto_random_negative_pool_epochs (empirical throughput cap = 10). Pass an integer to pin (1 means fresh random negatives every epoch). Overrides any random_negative_pool_epochs set in component-model hyperparameters.

--torch-compile {auto,0,1}

Enable torch.compile for forward kernels. ‘1’ on, ‘0’ off, ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE env (off when unset). When on, the orchestrator also auto-sizes TORCHINDUCTOR_COMPILE_THREADS — see hoist_torchinductor_compile_threads.

--torch-compile-loss {auto,0,1}

Enable torch.compile for training loss modules. ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE_LOSS env; when unset, loss compilation follows enabled CUDA network compilation. CUDA workers run a one-op autograd warmup before compiling losses to avoid the PyTorch 2.4 / Triton invalid-device-context bug.

--matmul-precision {none,highest,high,medium}

torch.set_float32_matmul_precision setting + cudnn.benchmark enable. ‘highest’ keeps full fp32 numerics with cudnn auto-tuning; ‘high’/’medium’ enable TF32 on Ampere+ (~2x matmul speedup, fp32 accumulation preserved, input-mantissa truncated). ‘none’ (default) leaves PyTorch’s default untouched. CPU/MPS: no-op.

--enable-timing

Populate per-epoch timing arrays in fit_info (epoch_fetch_time, epoch_train_time, epoch_validation_time). Persisted in the model’s config_json for post-hoc breakdown. No runtime cost beyond a few timestamp records per epoch.

mhcflurry class1-select-allele-specific-models

usage: 
Model select class1 single allele models.

-h, --help

show this help message and exit

--data <file.csv>

Model selection data CSV. Expected columns: allele, peptide, measurement_value

--exclude-data <file.csv>

Data to EXCLUDE from model selection. Useful to specify the original training data used

--models-dir <dir>

Directory to read models

--out-models-dir <dir>

Directory to write selected models

--out-unselected-predictions <file.csv>

Write predictions for validation data using unselected predictor to FILE.csv

--unselected-accuracy-scorer <scorer>

--unselected-accuracy-scorer-num-samples <unselected_accuracy_scorer_num_samples>

--unselected-accuracy-percentile-threshold <x>

--allele <allele>

Alleles to select models for. If not specified, all alleles with enough measurements will be used.

--combined-min-models <n>

Min number of models to select per allele when using combined selector

--combined-max-models <n>

Max number of models to select per allele when using combined selector

--combined-min-contribution-percent <x>

Use only model selectors that can contribute at least X % to the total score. Default: 1.0

--mass-spec-min-measurements <n>

Min number of measurements required for an allele to use mass-spec model selection

--mass-spec-min-models <n>

Min number of models to select per allele when using mass-spec selector

--mass-spec-max-models <n>

Max number of models to select per allele when using mass-spec selector

--mse-min-measurements <n>

Min number of measurements required for an allele to use MSE model selection

--mse-min-models <n>

Min number of models to select per allele when using MSE selector

--mse-max-models <n>

Max number of models to select per allele when using MSE selector

--scoring <scoring>

Scoring procedures to use in order

--consensus-min-models <n>

Min number of models to select per allele when using consensus selector

--consensus-max-models <n>

Max number of models to select per allele when using consensus selector

--consensus-num-peptides-per-length <consensus_num_peptides_per_length>

Num peptides per length to use for consensus scoring

--mass-spec-regex <regex>

Regular expression for mass-spec data. Runs on measurement_source col.Default: mass[- ]spec.

--verbosity <verbosity>

Verbosity. Default: 0

--num-jobs <n>

Number of local processes to parallelize training over. Pass ‘auto’ (default) to derive from --gpus * --max-workers-per-gpu once the latter is resolved (so workers never overflow to CPU silently). Pass 0 for serial run, or an int to pin.

--backend {auto,default,gpu,mps,cpu}

Device backend. ‘default’ is a legacy alias for ‘auto’. ‘gpu’ means CUDA. ‘auto’ (default) selects the best available device: GPU > MPS > CPU. When –gpus is set, GPU-assigned workers use CUDA and overflow workers are forced to CPU.

--gpus <n>

Number of CUDA GPUs to assign across parallel workers. When CUDA_VISIBLE_DEVICES is set, this is a count within that scheduler-visible mask. Requires –num-jobs > 0. Each assigned worker gets one GPU; workers beyond –gpus * –max-workers-per-gpu run on CPU.

--max-workers-per-gpu <n>

Maximum number of workers to assign to a GPU. Pass ‘auto’ (default) to pick a value based on detected free VRAM, the estimated per-worker working set, and a shared safety reserve (see auto_max_workers_per_gpu). Pass an integer to pin. Workers beyond --gpus * --max-workers-per-gpu run on CPU.

--max-tasks-per-worker <n>

Restart workers after N tasks. Workaround for memory leaks.

--worker-log-dir <worker_log_dir>

Write worker stdout and stderr logs to given directory.

--dataloader-num-workers <n>

Per-fit-worker DataLoader child count for streaming pretraining. Pass ‘auto’ (default) to derive from box vCPUs / RAM / fit-worker plan via mhcflurry.parallelism.auto_dataloader_num_workers (empirical throughput cap = 4). Pass an integer to pin (0 builds pretraining batches in-process). Overrides any dataloader_num_workers set in component-model hyperparameters when applicable; non-affinity train commands accept the flag for uniformity but currently no-op.

--random-negative-pool-epochs <n>

Number of consecutive epochs that share a pre-encoded random-negative pool. Pass ‘auto’ (default) to size from system RAM / fit-worker plan via mhcflurry.parallelism.auto_random_negative_pool_epochs (empirical throughput cap = 10). Pass an integer to pin (1 means fresh random negatives every epoch). Overrides any random_negative_pool_epochs set in component-model hyperparameters.

--torch-compile {auto,0,1}

Enable torch.compile for forward kernels. ‘1’ on, ‘0’ off, ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE env (off when unset). When on, the orchestrator also auto-sizes TORCHINDUCTOR_COMPILE_THREADS — see hoist_torchinductor_compile_threads.

--torch-compile-loss {auto,0,1}

Enable torch.compile for training loss modules. ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE_LOSS env; when unset, loss compilation follows enabled CUDA network compilation. CUDA workers run a one-op autograd warmup before compiling losses to avoid the PyTorch 2.4 / Triton invalid-device-context bug.

--matmul-precision {none,highest,high,medium}

torch.set_float32_matmul_precision setting + cudnn.benchmark enable. ‘highest’ keeps full fp32 numerics with cudnn auto-tuning; ‘high’/’medium’ enable TF32 on Ampere+ (~2x matmul speedup, fp32 accumulation preserved, input-mantissa truncated). ‘none’ (default) leaves PyTorch’s default untouched. CPU/MPS: no-op.

--enable-timing

Populate per-epoch timing arrays in fit_info (epoch_fetch_time, epoch_train_time, epoch_validation_time). Persisted in the model’s config_json for post-hoc breakdown. No runtime cost beyond a few timestamp records per epoch.

--random-seed <n>

Master random seed for this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Default: 42. Exact numerical results can still vary with hardware, library versions and nondeterministic kernels.

mhcflurry class1-train-pan-allele-models

usage: 
Train Class1 pan-allele models.

-h, --help

show this help message and exit

--reuse-folds

Use existing fold_0..N columns instead of generating new folds.

--data <file.csv>

Training data CSV. Expected columns: allele, peptide, measurement_value

--pretrain-data <file.csv>

Pre-training data CSV. Expected columns: allele, peptide, measurement_value

--out-models-dir <dir>

Directory to write models and manifest

--hyperparameters <file.json>

JSON or YAML of hyperparameters

--held-out-measurements-per-allele-fraction-and-max <x>

Fraction of measurements per allele to hold out, and maximum number

--ignore-inequalities

Do not use affinity value inequalities even when present in data

--num-folds <n>

Number of training folds.

--num-replicates <n>

Number of replicates per (architecture, fold) pair to train.

--random-seed <n>

Master random seed for this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Default: 42. Exact numerical results can still vary with hardware, library versions and nondeterministic kernels.

--max-epochs <n>

Max training epochs. If specified here it overrides any ‘max_epochs’ specified in the hyperparameters.

--allele-sequences <file.csv>

Allele sequences file.

--verbosity <verbosity>

Verbosity. Default: 0

--debug

Launch python debugger on error

--continue-incomplete

Continue training models from an incomplete training run. If this is specified then the only required argument is –out-models-dir

--only-initialize

Do not actually train models. The initialized run can be continued later with –continue-incomplete.

--save-all-checkpoints

Retain both terminal and minimum-validation weights for every fit. The restore_best_weights hyperparameter still selects the primary predictor weights.

--num-jobs <n>

Number of local processes to parallelize training over. Pass ‘auto’ (default) to derive from --gpus * --max-workers-per-gpu once the latter is resolved (so workers never overflow to CPU silently). Pass 0 for serial run, or an int to pin.

--backend {auto,default,gpu,mps,cpu}

Device backend. ‘default’ is a legacy alias for ‘auto’. ‘gpu’ means CUDA. ‘auto’ (default) selects the best available device: GPU > MPS > CPU. When –gpus is set, GPU-assigned workers use CUDA and overflow workers are forced to CPU.

--gpus <n>

Number of CUDA GPUs to assign across parallel workers. When CUDA_VISIBLE_DEVICES is set, this is a count within that scheduler-visible mask. Requires –num-jobs > 0. Each assigned worker gets one GPU; workers beyond –gpus * –max-workers-per-gpu run on CPU.

--max-workers-per-gpu <n>

Maximum number of workers to assign to a GPU. Pass ‘auto’ (default) to pick a value based on detected free VRAM, the estimated per-worker working set, and a shared safety reserve (see auto_max_workers_per_gpu). Pass an integer to pin. Workers beyond --gpus * --max-workers-per-gpu run on CPU.

--max-tasks-per-worker <n>

Restart workers after N tasks. Workaround for memory leaks.

--worker-log-dir <worker_log_dir>

Write worker stdout and stderr logs to given directory.

--dataloader-num-workers <n>

Per-fit-worker DataLoader child count for streaming pretraining. Pass ‘auto’ (default) to derive from box vCPUs / RAM / fit-worker plan via mhcflurry.parallelism.auto_dataloader_num_workers (empirical throughput cap = 4). Pass an integer to pin (0 builds pretraining batches in-process). Overrides any dataloader_num_workers set in component-model hyperparameters when applicable; non-affinity train commands accept the flag for uniformity but currently no-op.

--random-negative-pool-epochs <n>

Number of consecutive epochs that share a pre-encoded random-negative pool. Pass ‘auto’ (default) to size from system RAM / fit-worker plan via mhcflurry.parallelism.auto_random_negative_pool_epochs (empirical throughput cap = 10). Pass an integer to pin (1 means fresh random negatives every epoch). Overrides any random_negative_pool_epochs set in component-model hyperparameters.

--torch-compile {auto,0,1}

Enable torch.compile for forward kernels. ‘1’ on, ‘0’ off, ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE env (off when unset). When on, the orchestrator also auto-sizes TORCHINDUCTOR_COMPILE_THREADS — see hoist_torchinductor_compile_threads.

--torch-compile-loss {auto,0,1}

Enable torch.compile for training loss modules. ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE_LOSS env; when unset, loss compilation follows enabled CUDA network compilation. CUDA workers run a one-op autograd warmup before compiling losses to avoid the PyTorch 2.4 / Triton invalid-device-context bug.

--matmul-precision {none,highest,high,medium}

torch.set_float32_matmul_precision setting + cudnn.benchmark enable. ‘highest’ keeps full fp32 numerics with cudnn auto-tuning; ‘high’/’medium’ enable TF32 on Ampere+ (~2x matmul speedup, fp32 accumulation preserved, input-mantissa truncated). ‘none’ (default) leaves PyTorch’s default untouched. CPU/MPS: no-op.

--enable-timing

Populate per-epoch timing arrays in fit_info (epoch_fetch_time, epoch_train_time, epoch_validation_time). Persisted in the model’s config_json for post-hoc breakdown. No runtime cost beyond a few timestamp records per epoch.

--cluster-parallelism

--cluster-submit-command <cluster_submit_command>

Default: sh

--cluster-results-workdir <cluster_results_workdir>

Default: ./cluster-workdir

--additional-complete-file <additional_complete_file>

Additional file to monitor for job completion. Default: STDERR

--cluster-script-prefix-path <cluster_script_prefix_path>

--cluster-max-retries <cluster_max_retries>

How many times to rerun failing jobs. Default: 3

mhcflurry class1-select-pan-allele-models

usage: 
Model select class1 pan-allele models.

APPROACH: For each training fold, we select at least min and at most max models
(where min and max are set by the --{min/max}-models-per-fold argument) using a
step-up (forward) selection procedure. The final ensemble is the union of all
selected models across all folds.

-h, --help

show this help message and exit

--data <file.csv>

Model selection data CSV. Expected columns: allele, peptide, measurement_value

--models-dir <dir>

Directory to read models

--out-models-dir <dir>

Directory to write selected models

--min-models-per-fold <n>

Min number of models to select per fold. Default: 2, or the requested maximum when it is smaller.

--max-models-per-fold <n>

Max number of models to select per fold

--mass-spec-regex <regex>

Regular expression for mass-spec data. Runs on measurement_source col.Default: mass[- ]spec.

--verbosity <verbosity>

Verbosity. Default: 0

--save-validation-predictions

Save row-level out-of-fold predictions from the selected ensemble as model_selection_predictions.csv.bz2.

--num-jobs <n>

Number of local processes to parallelize training over. Pass ‘auto’ (default) to derive from --gpus * --max-workers-per-gpu once the latter is resolved (so workers never overflow to CPU silently). Pass 0 for serial run, or an int to pin.

--backend {auto,default,gpu,mps,cpu}

Device backend. ‘default’ is a legacy alias for ‘auto’. ‘gpu’ means CUDA. ‘auto’ (default) selects the best available device: GPU > MPS > CPU. When –gpus is set, GPU-assigned workers use CUDA and overflow workers are forced to CPU.

--gpus <n>

Number of CUDA GPUs to assign across parallel workers. When CUDA_VISIBLE_DEVICES is set, this is a count within that scheduler-visible mask. Requires –num-jobs > 0. Each assigned worker gets one GPU; workers beyond –gpus * –max-workers-per-gpu run on CPU.

--max-workers-per-gpu <n>

Maximum number of workers to assign to a GPU. Pass ‘auto’ (default) to pick a value based on detected free VRAM, the estimated per-worker working set, and a shared safety reserve (see auto_max_workers_per_gpu). Pass an integer to pin. Workers beyond --gpus * --max-workers-per-gpu run on CPU.

--max-tasks-per-worker <n>

Restart workers after N tasks. Workaround for memory leaks.

--worker-log-dir <worker_log_dir>

Write worker stdout and stderr logs to given directory.

--dataloader-num-workers <n>

Per-fit-worker DataLoader child count for streaming pretraining. Pass ‘auto’ (default) to derive from box vCPUs / RAM / fit-worker plan via mhcflurry.parallelism.auto_dataloader_num_workers (empirical throughput cap = 4). Pass an integer to pin (0 builds pretraining batches in-process). Overrides any dataloader_num_workers set in component-model hyperparameters when applicable; non-affinity train commands accept the flag for uniformity but currently no-op.

--random-negative-pool-epochs <n>

Number of consecutive epochs that share a pre-encoded random-negative pool. Pass ‘auto’ (default) to size from system RAM / fit-worker plan via mhcflurry.parallelism.auto_random_negative_pool_epochs (empirical throughput cap = 10). Pass an integer to pin (1 means fresh random negatives every epoch). Overrides any random_negative_pool_epochs set in component-model hyperparameters.

--torch-compile {auto,0,1}

Enable torch.compile for forward kernels. ‘1’ on, ‘0’ off, ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE env (off when unset). When on, the orchestrator also auto-sizes TORCHINDUCTOR_COMPILE_THREADS — see hoist_torchinductor_compile_threads.

--torch-compile-loss {auto,0,1}

Enable torch.compile for training loss modules. ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE_LOSS env; when unset, loss compilation follows enabled CUDA network compilation. CUDA workers run a one-op autograd warmup before compiling losses to avoid the PyTorch 2.4 / Triton invalid-device-context bug.

--matmul-precision {none,highest,high,medium}

torch.set_float32_matmul_precision setting + cudnn.benchmark enable. ‘highest’ keeps full fp32 numerics with cudnn auto-tuning; ‘high’/’medium’ enable TF32 on Ampere+ (~2x matmul speedup, fp32 accumulation preserved, input-mantissa truncated). ‘none’ (default) leaves PyTorch’s default untouched. CPU/MPS: no-op.

--enable-timing

Populate per-epoch timing arrays in fit_info (epoch_fetch_time, epoch_train_time, epoch_validation_time). Persisted in the model’s config_json for post-hoc breakdown. No runtime cost beyond a few timestamp records per epoch.

--cluster-parallelism

--cluster-submit-command <cluster_submit_command>

Default: sh

--cluster-results-workdir <cluster_results_workdir>

Default: ./cluster-workdir

--additional-complete-file <additional_complete_file>

Additional file to monitor for job completion. Default: STDERR

--cluster-script-prefix-path <cluster_script_prefix_path>

--cluster-max-retries <cluster_max_retries>

How many times to rerun failing jobs. Default: 3

mhcflurry class1-train-processing-models

usage: 
Train Class1 processing models.

-h, --help

show this help message and exit

--processing-data-policy {matched,legacy}

Require matched processing data; legacy is explicit historical replay only.

--reuse-folds

Use existing fold_0..N columns instead of generating new folds.

--data <file.csv>

Training data CSV. Expected columns: peptide, n_flank, c_flank, hit

--out-models-dir <dir>

Directory to write models and manifest

--hyperparameters <file.json>

JSON or YAML of hyperparameters

--held-out-samples <n>

Number of experiments to hold out per fold

--num-folds <n>

Number of training folds.

--num-replicates <n>

Number of replicates per (architecture, fold) pair to train.

--random-seed <n>

Master random seed for this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Default: 42. Exact numerical results can still vary with hardware, library versions and nondeterministic kernels.

--max-epochs <n>

Max training epochs. If specified here it overrides any ‘max_epochs’ specified in the hyperparameters.

--verbosity <verbosity>

Verbosity. Default: 0

--debug

Launch python debugger on error

--continue-incomplete

Continue training models from an incomplete training run. If this is specified then the only required argument is –out-models-dir

--only-initialize

Do not actually train models. The initialized run can be continued later with –continue-incomplete.

--num-jobs <n>

Number of local processes to parallelize training over. Pass ‘auto’ (default) to derive from --gpus * --max-workers-per-gpu once the latter is resolved (so workers never overflow to CPU silently). Pass 0 for serial run, or an int to pin.

--backend {auto,default,gpu,mps,cpu}

Device backend. ‘default’ is a legacy alias for ‘auto’. ‘gpu’ means CUDA. ‘auto’ (default) selects the best available device: GPU > MPS > CPU. When –gpus is set, GPU-assigned workers use CUDA and overflow workers are forced to CPU.

--gpus <n>

Number of CUDA GPUs to assign across parallel workers. When CUDA_VISIBLE_DEVICES is set, this is a count within that scheduler-visible mask. Requires –num-jobs > 0. Each assigned worker gets one GPU; workers beyond –gpus * –max-workers-per-gpu run on CPU.

--max-workers-per-gpu <n>

Maximum number of workers to assign to a GPU. Pass ‘auto’ (default) to pick a value based on detected free VRAM, the estimated per-worker working set, and a shared safety reserve (see auto_max_workers_per_gpu). Pass an integer to pin. Workers beyond --gpus * --max-workers-per-gpu run on CPU.

--max-tasks-per-worker <n>

Restart workers after N tasks. Workaround for memory leaks.

--worker-log-dir <worker_log_dir>

Write worker stdout and stderr logs to given directory.

--dataloader-num-workers <n>

Per-fit-worker DataLoader child count for streaming pretraining. Pass ‘auto’ (default) to derive from box vCPUs / RAM / fit-worker plan via mhcflurry.parallelism.auto_dataloader_num_workers (empirical throughput cap = 4). Pass an integer to pin (0 builds pretraining batches in-process). Overrides any dataloader_num_workers set in component-model hyperparameters when applicable; non-affinity train commands accept the flag for uniformity but currently no-op.

--random-negative-pool-epochs <n>

Number of consecutive epochs that share a pre-encoded random-negative pool. Pass ‘auto’ (default) to size from system RAM / fit-worker plan via mhcflurry.parallelism.auto_random_negative_pool_epochs (empirical throughput cap = 10). Pass an integer to pin (1 means fresh random negatives every epoch). Overrides any random_negative_pool_epochs set in component-model hyperparameters.

--torch-compile {auto,0,1}

Enable torch.compile for forward kernels. ‘1’ on, ‘0’ off, ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE env (off when unset). When on, the orchestrator also auto-sizes TORCHINDUCTOR_COMPILE_THREADS — see hoist_torchinductor_compile_threads.

--torch-compile-loss {auto,0,1}

Enable torch.compile for training loss modules. ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE_LOSS env; when unset, loss compilation follows enabled CUDA network compilation. CUDA workers run a one-op autograd warmup before compiling losses to avoid the PyTorch 2.4 / Triton invalid-device-context bug.

--matmul-precision {none,highest,high,medium}

torch.set_float32_matmul_precision setting + cudnn.benchmark enable. ‘highest’ keeps full fp32 numerics with cudnn auto-tuning; ‘high’/’medium’ enable TF32 on Ampere+ (~2x matmul speedup, fp32 accumulation preserved, input-mantissa truncated). ‘none’ (default) leaves PyTorch’s default untouched. CPU/MPS: no-op.

--enable-timing

Populate per-epoch timing arrays in fit_info (epoch_fetch_time, epoch_train_time, epoch_validation_time). Persisted in the model’s config_json for post-hoc breakdown. No runtime cost beyond a few timestamp records per epoch.

--cluster-parallelism

--cluster-submit-command <cluster_submit_command>

Default: sh

--cluster-results-workdir <cluster_results_workdir>

Default: ./cluster-workdir

--additional-complete-file <additional_complete_file>

Additional file to monitor for job completion. Default: STDERR

--cluster-script-prefix-path <cluster_script_prefix_path>

--cluster-max-retries <cluster_max_retries>

How many times to rerun failing jobs. Default: 3

mhcflurry class1-select-processing-models

usage: 
Model select antigen processing models.

APPROACH: For each training fold, we select at least min and at most max models
(where min and max are set by the --{min/max}-models-per-fold argument) using a
step-up (forward) selection procedure. The final ensemble is the union of all
selected models across all folds. AUC is used as the metric.

-h, --help

show this help message and exit

--processing-data-policy {matched,legacy}

--data <file.csv>

Model selection data CSV. Expected columns: peptide, hit, fold_0, …, fold_N

--models-dir <dir>

Directory to read models

--out-models-dir <dir>

Directory to write selected models

--min-models-per-fold <n>

Min number of models to select per fold. Default: 2, or the requested maximum when it is smaller.

--max-models-per-fold <n>

Max number of models to select per fold

--verbosity <verbosity>

Verbosity. Default: 0

--save-validation-predictions

Save row-level out-of-fold predictions from the selected ensemble as model_selection_predictions.csv.bz2.

--num-jobs <n>

Number of local processes to parallelize training over. Pass ‘auto’ (default) to derive from --gpus * --max-workers-per-gpu once the latter is resolved (so workers never overflow to CPU silently). Pass 0 for serial run, or an int to pin.

--backend {auto,default,gpu,mps,cpu}

Device backend. ‘default’ is a legacy alias for ‘auto’. ‘gpu’ means CUDA. ‘auto’ (default) selects the best available device: GPU > MPS > CPU. When –gpus is set, GPU-assigned workers use CUDA and overflow workers are forced to CPU.

--gpus <n>

Number of CUDA GPUs to assign across parallel workers. When CUDA_VISIBLE_DEVICES is set, this is a count within that scheduler-visible mask. Requires –num-jobs > 0. Each assigned worker gets one GPU; workers beyond –gpus * –max-workers-per-gpu run on CPU.

--max-workers-per-gpu <n>

Maximum number of workers to assign to a GPU. Pass ‘auto’ (default) to pick a value based on detected free VRAM, the estimated per-worker working set, and a shared safety reserve (see auto_max_workers_per_gpu). Pass an integer to pin. Workers beyond --gpus * --max-workers-per-gpu run on CPU.

--max-tasks-per-worker <n>

Restart workers after N tasks. Workaround for memory leaks.

--worker-log-dir <worker_log_dir>

Write worker stdout and stderr logs to given directory.

--dataloader-num-workers <n>

Per-fit-worker DataLoader child count for streaming pretraining. Pass ‘auto’ (default) to derive from box vCPUs / RAM / fit-worker plan via mhcflurry.parallelism.auto_dataloader_num_workers (empirical throughput cap = 4). Pass an integer to pin (0 builds pretraining batches in-process). Overrides any dataloader_num_workers set in component-model hyperparameters when applicable; non-affinity train commands accept the flag for uniformity but currently no-op.

--random-negative-pool-epochs <n>

Number of consecutive epochs that share a pre-encoded random-negative pool. Pass ‘auto’ (default) to size from system RAM / fit-worker plan via mhcflurry.parallelism.auto_random_negative_pool_epochs (empirical throughput cap = 10). Pass an integer to pin (1 means fresh random negatives every epoch). Overrides any random_negative_pool_epochs set in component-model hyperparameters.

--torch-compile {auto,0,1}

Enable torch.compile for forward kernels. ‘1’ on, ‘0’ off, ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE env (off when unset). When on, the orchestrator also auto-sizes TORCHINDUCTOR_COMPILE_THREADS — see hoist_torchinductor_compile_threads.

--torch-compile-loss {auto,0,1}

Enable torch.compile for training loss modules. ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE_LOSS env; when unset, loss compilation follows enabled CUDA network compilation. CUDA workers run a one-op autograd warmup before compiling losses to avoid the PyTorch 2.4 / Triton invalid-device-context bug.

--matmul-precision {none,highest,high,medium}

torch.set_float32_matmul_precision setting + cudnn.benchmark enable. ‘highest’ keeps full fp32 numerics with cudnn auto-tuning; ‘high’/’medium’ enable TF32 on Ampere+ (~2x matmul speedup, fp32 accumulation preserved, input-mantissa truncated). ‘none’ (default) leaves PyTorch’s default untouched. CPU/MPS: no-op.

--enable-timing

Populate per-epoch timing arrays in fit_info (epoch_fetch_time, epoch_train_time, epoch_validation_time). Persisted in the model’s config_json for post-hoc breakdown. No runtime cost beyond a few timestamp records per epoch.

--cluster-parallelism

--cluster-submit-command <cluster_submit_command>

Default: sh

--cluster-results-workdir <cluster_results_workdir>

Default: ./cluster-workdir

--additional-complete-file <additional_complete_file>

Additional file to monitor for job completion. Default: STDERR

--cluster-script-prefix-path <cluster_script_prefix_path>

--cluster-max-retries <cluster_max_retries>

How many times to rerun failing jobs. Default: 3

mhcflurry class1-train-presentation-models

usage: 
Train Class1 presentation models.

-h, --help

show this help message and exit

--data <file.csv>

Training data CSV. Expected columns: peptide, n_flank, c_flank, hit

--out-models-dir <dir>

Directory to write models and manifest

--affinity-predictor <dir>

Affinity predictor models dir

--processing-predictor-with-flanks <dir>

Processing predictor with flanks

--processing-predictor-without-flanks <dir>

Processing predictor without flanks

--verbosity <verbosity>

Default: 1

--debug

Launch python debugger on error

--hla-column <hla_column>

Column in data giving space-separated MHC I alleles

--target-column <target_column>

Column in data giving hit (1) vs decoy (0)

--feature-chunk-size <n>

Rows per parallel presentation feature-prediction task. Larger chunks reduce scheduling overhead but increase worker memory. Default: 250000

--num-jobs <n>

Number of local processes to parallelize training over. Pass ‘auto’ (default) to derive from --gpus * --max-workers-per-gpu once the latter is resolved (so workers never overflow to CPU silently). Pass 0 for serial run, or an int to pin.

--backend {auto,default,gpu,mps,cpu}

Device backend. ‘default’ is a legacy alias for ‘auto’. ‘gpu’ means CUDA. ‘auto’ (default) selects the best available device: GPU > MPS > CPU. When –gpus is set, GPU-assigned workers use CUDA and overflow workers are forced to CPU.

--gpus <n>

Number of CUDA GPUs to assign across parallel workers. When CUDA_VISIBLE_DEVICES is set, this is a count within that scheduler-visible mask. Requires –num-jobs > 0. Each assigned worker gets one GPU; workers beyond –gpus * –max-workers-per-gpu run on CPU.

--max-workers-per-gpu <n>

Maximum number of workers to assign to a GPU. Pass ‘auto’ (default) to pick a value based on detected free VRAM, the estimated per-worker working set, and a shared safety reserve (see auto_max_workers_per_gpu). Pass an integer to pin. Workers beyond --gpus * --max-workers-per-gpu run on CPU.

--max-tasks-per-worker <n>

Restart workers after N tasks. Workaround for memory leaks.

--worker-log-dir <worker_log_dir>

Write worker stdout and stderr logs to given directory.

--dataloader-num-workers <n>

Per-fit-worker DataLoader child count for streaming pretraining. Pass ‘auto’ (default) to derive from box vCPUs / RAM / fit-worker plan via mhcflurry.parallelism.auto_dataloader_num_workers (empirical throughput cap = 4). Pass an integer to pin (0 builds pretraining batches in-process). Overrides any dataloader_num_workers set in component-model hyperparameters when applicable; non-affinity train commands accept the flag for uniformity but currently no-op.

--random-negative-pool-epochs <n>

Number of consecutive epochs that share a pre-encoded random-negative pool. Pass ‘auto’ (default) to size from system RAM / fit-worker plan via mhcflurry.parallelism.auto_random_negative_pool_epochs (empirical throughput cap = 10). Pass an integer to pin (1 means fresh random negatives every epoch). Overrides any random_negative_pool_epochs set in component-model hyperparameters.

--torch-compile {auto,0,1}

Enable torch.compile for forward kernels. ‘1’ on, ‘0’ off, ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE env (off when unset). When on, the orchestrator also auto-sizes TORCHINDUCTOR_COMPILE_THREADS — see hoist_torchinductor_compile_threads.

--torch-compile-loss {auto,0,1}

Enable torch.compile for training loss modules. ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE_LOSS env; when unset, loss compilation follows enabled CUDA network compilation. CUDA workers run a one-op autograd warmup before compiling losses to avoid the PyTorch 2.4 / Triton invalid-device-context bug.

--matmul-precision {none,highest,high,medium}

torch.set_float32_matmul_precision setting + cudnn.benchmark enable. ‘highest’ keeps full fp32 numerics with cudnn auto-tuning; ‘high’/’medium’ enable TF32 on Ampere+ (~2x matmul speedup, fp32 accumulation preserved, input-mantissa truncated). ‘none’ (default) leaves PyTorch’s default untouched. CPU/MPS: no-op.

--enable-timing

Populate per-epoch timing arrays in fit_info (epoch_fetch_time, epoch_train_time, epoch_validation_time). Persisted in the model’s config_json for post-hoc breakdown. No runtime cost beyond a few timestamp records per epoch.

--random-seed <n>

Master random seed for this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Default: 42. Exact numerical results can still vary with hardware, library versions and nondeterministic kernels.

Percentile calibration

Released affinity and presentation predictors ship with percentile calibration; released processing predictors do not. Calibrate custom models, or a released processing predictor when you need processing percentiles. See Percentile calibration for all predictors for examples and background requirements. Calibration writes into --models-dir; use a copy to preserve an existing calibration.

mhcflurry calibrate-percentile-ranks

usage: 
Calibrate percentile ranks for models. Runs in-place.

-h, --help

show this help message and exit

--predictor-kind {class1_affinity,class1_processing,class1_presentation}

Type of predictor to calibrate

--percentile-method {compact,histogram}

Method for new calibration (default: compact). Loading alone never changes saved ranks. Histogram reproduction also requires the original reference and bin policy.

--max-percentile-knots {64,128}

Compact starts at 64; allow 128 only when background validation justifies it. This is a ceiling (default: 128), not a fixed size. Ignored for histogram calibration.

--processing-reference-data <processing_reference_data>

Required for processing: independent background CSV with peptide and, for a flanked model, n_flank and c_flank columns. No evaluation labels are used. Scores and input sequences are saved in percent_rank_reference.npz. Requires –num-jobs 0; reference-generation options do not apply.

--models-dir <dir>

Directory to read and write models

--allele <allele>, --alleles <allele>

Alleles to calibrate percentile ranks for. If not specified all alleles are used

--match-amino-acid-distribution-data <match_amino_acid_distribution_data>

Sample random peptides from the amino acid distribution of the peptides listed in the supplied CSV file, which must have a ‘peptide’ column. If not specified a uniform distribution is used.

--alleles-file <alleles_file>

Use alleles in supplied CSV file, which must have an ‘allele’ column.

--list-percent-rank-status

For class1 affinity predictors, print a CSV indicating which requested alleles already have percentile-rank calibration and exit without generating calibration peptides.

--only-missing

For class1 affinity predictors, calibrate only requested alleles that do not already have direct or sequence-equivalent percentile-rank calibration.

--num-peptides-per-length <n>

For affinity/presentation, number of generated peptides per length to use to calibrate percent ranks. Processing uses –processing-reference-data. Default: 100000.

--num-genotypes <n>

Used when calibrating a presentation predictor. Number of MHC allele setsto sample

--alleles-per-genotype <n>

Used when calibrating a presentation predictor. Number of alleles per MHC allele set. Use 1 to calibrate for single alleles. Default: 6

--motif-summary

Calculate motifs and length preferences for each allele

--summary-top-peptide-fraction <x>

The top X fraction of predictions (i.e. tightest binders) to use to generate motifs and length preferences. Default: [0.0001, 0.001, 0.01, 0.1, 1.0]

--length-range <length_range>

Min and max peptide length to calibrate, inclusive. Default: (8, 15)

--prediction-batch-size <prediction_batch_size>

Batch size for predictions. Pass an int to pin, or ‘auto’ (default) to size per GPU free memory / workers-per-GPU — see mhcflurry.pytorch_sizing.compute_prediction_batch_size.

--alleles-per-work-chunk <n>

Number of alleles per work chunk. Default: 1.

--verbosity <verbosity>

Verbosity. Default: 0

--gpu-batched

[class1 affinity predictors only] Use the GPU-hoisted calibration fast path: precompute peptide-side activations per network and batch –gpu-allele-batch-size alleles into a single forward through the merge + main dense path. Uses the same ensemble aggregation and percentile method as the ordinary path; floating-point batching can change predictions and selected knots slightly, so saved curves are not guaranteed bit-identical. Applies to affinity in serial, local-pool, and cluster modes; ignored for processing/presentation.

--gpu-allele-batch-size <gpu_allele_batch_size>

Alleles per GPU forward when –gpu-batched. Pass an int to pin; ‘auto’ (default) partitions the VRAM budget with –max-workers-per-gpu. Larger values trade off more VRAM for fewer kernel launches.

--gpu-peptide-batch-size <gpu_peptide_batch_size>

Peptide chunk size on device when –gpu-batched. Pass an int to pin; ‘auto’ (default) picks the peptide axis of the auto-sized budget. Reducing keeps peak VRAM down on smaller GPUs but adds kernel-launch overhead.

--num-jobs <n>

Number of local processes to parallelize training over. Pass ‘auto’ (default) to derive from --gpus * --max-workers-per-gpu once the latter is resolved (so workers never overflow to CPU silently). Pass 0 for serial run, or an int to pin.

--backend {auto,default,gpu,mps,cpu}

Device backend. ‘default’ is a legacy alias for ‘auto’. ‘gpu’ means CUDA. ‘auto’ (default) selects the best available device: GPU > MPS > CPU. When –gpus is set, GPU-assigned workers use CUDA and overflow workers are forced to CPU.

--gpus <n>

Number of CUDA GPUs to assign across parallel workers. When CUDA_VISIBLE_DEVICES is set, this is a count within that scheduler-visible mask. Requires –num-jobs > 0. Each assigned worker gets one GPU; workers beyond –gpus * –max-workers-per-gpu run on CPU.

--max-workers-per-gpu <n>

Maximum number of workers to assign to a GPU. Pass ‘auto’ (default) to pick a value based on detected free VRAM, the estimated per-worker working set, and a shared safety reserve (see auto_max_workers_per_gpu). Pass an integer to pin. Workers beyond --gpus * --max-workers-per-gpu run on CPU.

--max-tasks-per-worker <n>

Restart workers after N tasks. Workaround for memory leaks.

--worker-log-dir <worker_log_dir>

Write worker stdout and stderr logs to given directory.

--dataloader-num-workers <n>

Per-fit-worker DataLoader child count for streaming pretraining. Pass ‘auto’ (default) to derive from box vCPUs / RAM / fit-worker plan via mhcflurry.parallelism.auto_dataloader_num_workers (empirical throughput cap = 4). Pass an integer to pin (0 builds pretraining batches in-process). Overrides any dataloader_num_workers set in component-model hyperparameters when applicable; non-affinity train commands accept the flag for uniformity but currently no-op.

--random-negative-pool-epochs <n>

Number of consecutive epochs that share a pre-encoded random-negative pool. Pass ‘auto’ (default) to size from system RAM / fit-worker plan via mhcflurry.parallelism.auto_random_negative_pool_epochs (empirical throughput cap = 10). Pass an integer to pin (1 means fresh random negatives every epoch). Overrides any random_negative_pool_epochs set in component-model hyperparameters.

--torch-compile {auto,0,1}

Enable torch.compile for forward kernels. ‘1’ on, ‘0’ off, ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE env (off when unset). When on, the orchestrator also auto-sizes TORCHINDUCTOR_COMPILE_THREADS — see hoist_torchinductor_compile_threads.

--torch-compile-loss {auto,0,1}

Enable torch.compile for training loss modules. ‘auto’ (default) reads MHCFLURRY_TORCH_COMPILE_LOSS env; when unset, loss compilation follows enabled CUDA network compilation. CUDA workers run a one-op autograd warmup before compiling losses to avoid the PyTorch 2.4 / Triton invalid-device-context bug.

--matmul-precision {none,highest,high,medium}

torch.set_float32_matmul_precision setting + cudnn.benchmark enable. ‘highest’ keeps full fp32 numerics with cudnn auto-tuning; ‘high’/’medium’ enable TF32 on Ampere+ (~2x matmul speedup, fp32 accumulation preserved, input-mantissa truncated). ‘none’ (default) leaves PyTorch’s default untouched. CPU/MPS: no-op.

--enable-timing

Populate per-epoch timing arrays in fit_info (epoch_fetch_time, epoch_train_time, epoch_validation_time). Persisted in the model’s config_json for post-hoc breakdown. No runtime cost beyond a few timestamp records per epoch.

--cluster-parallelism

--cluster-submit-command <cluster_submit_command>

Default: sh

--cluster-results-workdir <cluster_results_workdir>

Default: ./cluster-workdir

--additional-complete-file <additional_complete_file>

Additional file to monitor for job completion. Default: STDERR

--cluster-script-prefix-path <cluster_script_prefix_path>

--cluster-max-retries <cluster_max_retries>

How many times to rerun failing jobs. Default: 3

--random-seed <n>

Master random seed for this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Default: 42. Exact numerical results can still vary with hardware, library versions and nondeterministic kernels.

Evaluation

See Evaluating trained models for the workflow and output layout.

Metrics and figures

Existing scripts can keep using the shortcuts mhcflurry compare-models, mhcflurry plot-model-comparison, and mhcflurry paper-figures.

mhcflurry eval compare-models

Compare model ensembles on the data_evaluation benchmarks.

Combines the three legacy scripts/training/compare_*.py tools into one command. --a and --b may each be a training-run directory, the literal public (resolves to the currently-installed public release), or public:<release_name> (pin a non-default release). --b defaults to public.

Runs whichever components are available on both sides:

• training_stats — per-task wall-time, epoch-count, final-loss deltas from each side’s manifest.csv. Skipped when either side is public (no manifest).

• affinity — per-allele ROC-AUC / PR-AUC / PPV@N on the monoallelic hit/decoy benchmark.

• processing — per-sample + per-length metrics on the multiallelic hit/decoy benchmark for the requested processing flank variants.

• presentation — per-sample + per-length micro/macro metrics on the multiallelic hit/decoy benchmark, with-flanks and without-flanks.

Writes detailed CSV/JSON artifacts plus release-summary CSV/Markdown tables. mhcflurry plot-model-comparison consumes the CSVs to render plots.

usage: mhcflurry eval compare-models [-h] --a A [--b B] [--a-label A_LABEL]
                                     [--b-label B_LABEL]
                                     [--a-affinity-dir A_AFFINITY_DIR]
                                     [--a-processing-dir A_PROCESSING_DIR]
                                     [--a-presentation-dir A_PRESENTATION_DIR]
                                     [--a-training-dir A_TRAINING_DIR]
                                     [--a-affinity-predictions A_AFFINITY_PREDICTIONS]
                                     [--a-affinity-prediction-column A_AFFINITY_PREDICTION_COLUMN]
                                     [--b-affinity-dir B_AFFINITY_DIR]
                                     [--b-processing-dir B_PROCESSING_DIR]
                                     [--b-presentation-dir B_PRESENTATION_DIR]
                                     [--b-training-dir B_TRAINING_DIR]
                                     [--b-affinity-predictions B_AFFINITY_PREDICTIONS]
                                     [--b-affinity-prediction-column B_AFFINITY_PREDICTION_COLUMN]
                                     --out OUT [--include INCLUDE]
                                     [--data-dir DATA_DIR]
                                     [--release-holdout-dir RELEASE_HOLDOUT_DIR]
                                     [--limit-files LIMIT_FILES]
                                     [--affinity-source {mixmhcpred,netmhcpan4,no_additional_ms,both}]
                                     [--affinity-training-overlap-policy {exclude,audit}]
                                     [--skip-affinity-predictions]
                                     [--processing-modes PROCESSING_MODES]
                                     [--processing-negative-policy {matched,random-diagnostic}]
                                     [--processing-matched-cohort PROCESSING_MATCHED_COHORT]
                                     [--presentation-modes PRESENTATION_MODES]
                                     [--presentation-score-kinds PRESENTATION_SCORE_KINDS]
                                     [--num-jobs N]
                                     [--backend {auto,default,gpu,mps,cpu}]
                                     [--gpus N] [--max-workers-per-gpu N]
                                     [--max-tasks-per-worker N]
                                     [--worker-log-dir WORKER_LOG_DIR]
                                     [--torch-compile {auto,0,1}]
                                     [--matmul-precision {none,highest,high,medium}]
                                     [--presentation-num-jobs PRESENTATION_NUM_JOBS]
                                     [--presentation-max-workers-per-gpu PRESENTATION_MAX_WORKERS_PER_GPU]
                                     [--presentation-max-tasks-per-worker PRESENTATION_MAX_TASKS_PER_WORKER]
                                     [--presentation-torch-compile {auto,0,1}]

-h, --help

show this help message and exit

--a <a>

Side A: a training-run directory, ‘public’, or ‘public:<release_name>’.

--b <b>

Side B: same forms as –a. Defaults to ‘public’ (the most recently installed mhcflurry release).

--a-label <a_label>

Display label for side A (default: derived).

--b-label <b_label>

Display label for side B (default: derived).

--a-affinity-dir <a_affinity_dir>

Override the auto-probed affinity path for side A.

--a-processing-dir <a_processing_dir>

Override the auto-probed processing path for side A.

--a-presentation-dir <a_presentation_dir>

Override the auto-probed presentation path for side A.

--a-training-dir <a_training_dir>

Override the auto-probed training path for side A.

--a-affinity-predictions <a_affinity_predictions>

Reuse a saved, row-identical affinity prediction table for side A instead of rerunning that predictor. The table’s cohort identity is verified before scores are accepted.

--a-affinity-prediction-column <a_affinity_prediction_column>

Prediction column in –a-affinity-predictions. Default: a_pred

--b-affinity-dir <b_affinity_dir>

Override the auto-probed affinity path for side B.

--b-processing-dir <b_processing_dir>

Override the auto-probed processing path for side B.

--b-presentation-dir <b_presentation_dir>

Override the auto-probed presentation path for side B.

--b-training-dir <b_training_dir>

Override the auto-probed training path for side B.

--b-affinity-predictions <b_affinity_predictions>

Reuse a saved, row-identical affinity prediction table for side B instead of rerunning that predictor. The table’s cohort identity is verified before scores are accepted.

--b-affinity-prediction-column <b_affinity_prediction_column>

Prediction column in –b-affinity-predictions. Default: b_pred

--out <out>

Output directory. Subdirs per component are created here.

--include <include>

Comma-separated subset of {training_stats, affinity, processing, presentation}; default ‘auto’ runs whichever components are available on both sides.

--data-dir <data_dir>

data_evaluation directory. Defaults to the currently-installed data_evaluation download.

--release-holdout-dir <release_holdout_dir>

Release holdout manifest directory. When specified, affinity, processing, and presentation benchmarks are restricted to their frozen evaluation sample manifests.

--limit-files <limit_files>

Smoke-test: only read first N benchmark files.

--affinity-source {mixmhcpred,netmhcpan4,no_additional_ms,both}

Which monoallelic benchmark source to use for affinity eval. The no_additional_ms source is train-excluded for the matching models_class1_pan_variants/models.no_additional_ms predictor.

--affinity-training-overlap-policy {exclude,audit}

For frozen release affinity evaluation, either exclude the union of both predictors’ recorded training pMHCs or audit/report that overlap without changing the score set.

--skip-affinity-predictions

Do not persist the row-level affinity/predictions.csv.bz2 artifact. Aggregate metrics, overlap audits, and per-allele/per-length tables are unchanged.

--processing-modes <processing_modes>

Comma-separated subset of {with_flanks, no_flank, short_flanks} for the processing component.

--processing-negative-policy {matched,random-diagnostic}

Processing headline cohort. Unmatched random decoys are diagnostic only.

--processing-matched-cohort <processing_matched_cohort>

Frozen expanded 10:1 cohort directory from eval prepare-processing-cohort.

--presentation-modes <presentation_modes>

Comma-separated subset of {with_flanks, without_flanks} for the presentation component.

--presentation-score-kinds <presentation_score_kinds>

Comma-separated subset of {presentation_score, presentation_percentile}. Default evaluates and requires both. Use presentation_score explicitly for an uncalibrated research combiner; this does not validate release percentiles.

--num-jobs <n>

Number of local prediction worker processes. Pass ‘auto’ (default) to size from detected CUDA capacity, host memory and work items; CPU/MPS run serially. Pass 0 for serial prediction.

--backend {auto,default,gpu,mps,cpu}

Device backend. ‘auto’ (default) selects GPU > MPS > CPU. When –gpus is set, GPU-assigned workers use CUDA.

--gpus <n>

Number of CUDA GPUs to assign across parallel prediction workers. Defaults to all visible CUDA devices with the auto or gpu backend. When CUDA_VISIBLE_DEVICES is set, this is a count within that scheduler-visible mask. Requires –num-jobs > 0.

--max-workers-per-gpu <n>

Maximum prediction workers to assign to each CUDA GPU. Pass ‘auto’ (default) to choose from detected free VRAM, or an int to pin.

--max-tasks-per-worker <n>

Restart workers after N prediction chunks.

--worker-log-dir <worker_log_dir>

Write prediction worker stdout and stderr logs to this directory.

--torch-compile {auto,0,1}

Enable torch.compile for forward kernels. ‘auto’ reads MHCFLURRY_TORCH_COMPILE (off when unset). CUDA only.

--matmul-precision {none,highest,high,medium}

torch.set_float32_matmul_precision setting. CPU/MPS: no-op.

--presentation-num-jobs <presentation_num_jobs>

Override –num-jobs for presentation inference. This is useful because presentation prediction has a larger per-worker GPU footprint than affinity or processing.

--presentation-max-workers-per-gpu <presentation_max_workers_per_gpu>

Override –max-workers-per-gpu for presentation inference.

--presentation-max-tasks-per-worker <presentation_max_tasks_per_worker>

Override –max-tasks-per-worker for presentation inference.

--presentation-torch-compile {auto,0,1}

Override –torch-compile for presentation inference.

mhcflurry eval plot-comparison

Plot the metric outputs from mhcflurry compare-models.

Reads the CSVs + JSON written by compare-models and renders ROC / PR / scatter / per-allele delta plots under <input>/plots/ for affinity, processing, and presentation comparisons. Kept as a separate subcommand so the metric pipeline doesn’t pay the matplotlib import cost.

usage: mhcflurry eval plot-comparison [-h] [--allow-legacy-processing-plots]
                                      --input INPUT
                                      [--max-scatter-points MAX_SCATTER_POINTS]
                                      [--components COMPONENTS]
                                      [--summary-pdf SUMMARY_PDF]
                                      [--a-label A_LABEL] [--b-label B_LABEL]
                                      [--paper-figures-scores-dir PAPER_FIGURES_SCORES_DIR]
                                      [--paper-figures-artifacts-dir PAPER_FIGURES_ARTIFACTS_DIR]
                                      [--paper-figures-out PAPER_FIGURES_OUT]
                                      [--paper-figures-formats PAPER_FIGURES_FORMATS]
                                      [--include-paper-figures-in-summary-pdf]
                                      [--paper-figures-candidate-predictor PAPER_FIGURES_CANDIDATE_PREDICTOR]
                                      [--paper-figures-external-baselines PAPER_FIGURES_EXTERNAL_BASELINES]
                                      [--paper-figures-multiallelic-predictions PAPER_FIGURES_MULTIALLELIC_PREDICTIONS]
                                      [--paper-figures-monoallelic-predictions PAPER_FIGURES_MONOALLELIC_PREDICTIONS]
                                      [--paper-figures-preferred-predictors PAPER_FIGURES_PREFERRED_PREDICTORS]
                                      [--paper-figures-presentation-panel-predictors PAPER_FIGURES_PRESENTATION_PANEL_PREDICTORS]
                                      [--paper-figures-presentation-panel-baselines PAPER_FIGURES_PRESENTATION_PANEL_BASELINES]

-h, --help

show this help message and exit

--allow-legacy-processing-plots

Explicitly render unmatched processing diagnostics, labelled as such.

--input <input>

Output directory produced by mhcflurry compare-models.

--max-scatter-points <max_scatter_points>

Subsample scatter plots above this many points (default 100k).

--components <components>

Comma-separated subset of {affinity, processing, presentation}; default ‘auto’ plots whichever components are present in –input.

--summary-pdf <summary_pdf>

Optional PDF path. When set, generated plots are collected into a single PDF, preserving vector plots where possible. Use a top-level file under <input>/plots or a path outside the plot tree; paper and diagnostic subdirectories are reserved.

--a-label <a_label>

Override side A label from side_a.json. Useful for regenerating plots from an existing comparison without recomputing metrics.

--b-label <b_label>

Override side B label from side_b.json. Useful for regenerating plots from an existing comparison without recomputing metrics.

--paper-figures-scores-dir <paper_figures_scores_dir>

Optional saved figure-input directory passed to mhcflurry paper-figures --scores-dir. This may contain saved prediction tables, derived score tables, and predictor metadata such as predictor_info.csv.

--paper-figures-artifacts-dir <paper_figures_artifacts_dir>

Compatibility alias for –paper-figures-scores-dir.

--paper-figures-out <paper_figures_out>

Output directory for paper-style figures. Default: <input>/plots/paper_figures. Must be a dedicated directory, not <input>/plots or a diagnostic component directory.

--paper-figures-formats <paper_figures_formats>

Comma-separated paper-figure formats. Default: svg,pdf,png.

--include-paper-figures-in-summary-pdf

When –summary-pdf and paper-style figures are enabled, append paper_figures/paper_figures.pdf to the summary PDF.

--paper-figures-candidate-predictor <paper_figures_candidate_predictor>

Candidate predictor passed through to mhcflurry paper-figures.

--paper-figures-external-baselines <paper_figures_external_baselines>

External baselines passed through to mhcflurry paper-figures as PREDICTOR or PREDICTOR:PERCENT_CHANGE_SUFFIX.

--paper-figures-multiallelic-predictions <paper_figures_multiallelic_predictions>

Saved multiallelic test-set prediction table passed through to mhcflurry paper-figures.

--paper-figures-monoallelic-predictions <paper_figures_monoallelic_predictions>

Saved monoallelic test-set prediction table passed through to mhcflurry paper-figures.

--paper-figures-preferred-predictors <paper_figures_preferred_predictors>

Comma-separated preferred predictors passed through to mhcflurry paper-figures.

--paper-figures-presentation-panel-predictors <paper_figures_presentation_panel_predictors>

Comma-separated presentation-panel candidate predictors passed through to mhcflurry paper-figures.

--paper-figures-presentation-panel-baselines <paper_figures_presentation_panel_baselines>

Comma-separated presentation-panel baseline predictors passed through to mhcflurry paper-figures.

Plotting layers:

• This command always reads an existing compare-models directory and writes diagnostic plots under <input>/plots.

• –summary-pdf collects those diagnostic plot PDFs into one review packet.

• The –paper-figures-* flags optionally call mhcflurry eval paper-figures render with saved score/prediction inputs for the broader paper-style figure suite.

• Custom saved-prediction score columns need predictor_info.csv metadata with predictor and higher_is_better.

mhcflurry eval paper-figures run

Run the local evaluation-to-figures workflow for a trained model. This composes compare-models, paper-figures, and plot-model-comparison; remote orchestration remains in the release wrapper.

usage: mhcflurry eval paper-figures run [-h] --a A [--b B] [--a-label A_LABEL]
                                        [--b-label B_LABEL] --out OUT
                                        [--data-dir DATA_DIR]
                                        [--release-holdout-dir RELEASE_HOLDOUT_DIR]
                                        [--include INCLUDE]
                                        [--limit-files LIMIT_FILES]
                                        [--scores-dir SCORES_DIR]
                                        [--multiallelic-predictions MULTIALLELIC_PREDICTIONS]
                                        [--monoallelic-predictions MONOALLELIC_PREDICTIONS]
                                        [--paper-figures-out PAPER_FIGURES_OUT]
                                        [--formats FORMATS]
                                        [--summary-pdf SUMMARY_PDF]
                                        [--candidate-predictor CANDIDATE_PREDICTOR]
                                        [--external-baselines EXTERNAL_BASELINES]
                                        [--preferred-predictors PREFERRED_PREDICTORS]
                                        [--presentation-panel-predictors PRESENTATION_PANEL_PREDICTORS]
                                        [--presentation-panel-baselines PRESENTATION_PANEL_BASELINES]
                                        [--skip-comparison-plots]

-h, --help

show this help message and exit

--a <a>

Candidate model run directory, ‘public’, or ‘public:<release>’.

--b <b>

Baseline model run directory or public release. Default: public.

--a-label <a_label>

Display label for side A.

--b-label <b_label>

Display label for side B.

--out <out>

Evaluation output directory. compare-models writes here.

--data-dir <data_dir>

data_evaluation directory. Defaults to installed data_evaluation.

--release-holdout-dir <release_holdout_dir>

Frozen release-evaluation sample manifests for compare-models.

--include <include>

compare-models component subset. Default: auto.

--limit-files <limit_files>

Smoke-test: only read first N benchmark files.

--scores-dir <scores_dir>

Saved figure-input directory passed to paper-figures.

--multiallelic-predictions <multiallelic_predictions>

Saved multiallelic prediction table passed to paper-figures.

--monoallelic-predictions <monoallelic_predictions>

Saved monoallelic prediction table passed to paper-figures.

--paper-figures-out <paper_figures_out>

Dedicated paper-figure output directory. Default: <out>/plots/paper_figures. Cannot be <out>/plots or a diagnostic component directory.

--formats <formats>

Paper-figure formats. Default: svg,pdf,png.

--summary-pdf <summary_pdf>

Combined diagnostic PDF. Default: <out>/plots/model_comparison_figures.pdf. Must not be inside the paper-figure or diagnostic component directories.

--candidate-predictor <candidate_predictor>

Candidate predictor name passed to paper-figures.

--external-baselines <external_baselines>

External baseline predictor list passed to paper-figures.

--preferred-predictors <preferred_predictors>

Preferred predictor list passed to paper-figures.

--presentation-panel-predictors <presentation_panel_predictors>

Presentation panel candidate predictor list passed to paper-figures.

--presentation-panel-baselines <presentation_panel_baselines>

Presentation panel baseline predictor list passed to paper-figures.

--skip-comparison-plots

Skip plot-model-comparison after paper figures are rendered.

mhcflurry eval paper-figures render

Generate paper-style figures from retraining/evaluation outputs.

This command ports the figure families from the 2023 retraining notebooks into a reproducible CLI. It reads saved evaluation tables: raw saved prediction tables such as benchmark.multiallelic.csv.bz2, derived score tables such as accuracy_scores.multiallelic.csv, and the current compare-models output directory when supplied. Missing inputs are written to missing_inputs.md and manifest.csv so a training run can distinguish “not generated because the data is absent” from “plotting silently drifted.”

usage: mhcflurry eval paper-figures render [-h] [--scores-dir SCORES_DIR]
                                           [--artifacts-dir ARTIFACTS_DIR]
                                           [--comparison-dir COMPARISON_DIR]
                                           [--multiallelic-predictions MULTIALLELIC_PREDICTIONS]
                                           [--monoallelic-predictions MONOALLELIC_PREDICTIONS]
                                           --out OUT [--formats FORMATS]
                                           [--combined-pdf COMBINED_PDF]
                                           [--sample-table SAMPLE_TABLE]
                                           [--sample-group SAMPLE_GROUP]
                                           [--candidate-predictor CANDIDATE_PREDICTOR]
                                           [--external-baselines EXTERNAL_BASELINES]
                                           [--preferred-predictors PREFERRED_PREDICTORS]
                                           [--monoallelic-panel-predictors MONOALLELIC_PANEL_PREDICTORS]
                                           [--presentation-panel-predictors PRESENTATION_PANEL_PREDICTORS]
                                           [--presentation-panel-baselines PRESENTATION_PANEL_BASELINES]
                                           [--max-scatter-points MAX_SCATTER_POINTS]
                                           [--strict]

-h, --help

show this help message and exit

--scores-dir <scores_dir>

Directory containing saved figure inputs such as accuracy_scores.multiallelic.csv, benchmark.multiallelic.csv.bz2, and predictor_info.csv. Custom predictor rows in predictor_info.csv should include higher_is_better.

--artifacts-dir <artifacts_dir>

Compatibility alias for –scores-dir. Prefer –scores-dir in new scripts.

--comparison-dir <comparison_dir>

Optional directory produced by mhcflurry compare-models. When provided, paper-figures generates current-run panels from fresh MHCflurry side-A vs side-B evaluation outputs instead of requiring pre-derived score tables.

--multiallelic-predictions <multiallelic_predictions>

Optional saved multiallelic test-set prediction table. If accuracy_scores.multiallelic.csv is absent, paper-figures derives per-sample AUC/PPV tables from this file. Default: <scores-dir>/benchmark.multiallelic.csv.bz2 when present.

--monoallelic-predictions <monoallelic_predictions>

Optional saved monoallelic test-set prediction table used to derive monoallelic AUC/PPV plots when accuracy_scores.monoallelic.csv is absent.

--out <out>

Output directory for paper figures and manifest files.

--formats <formats>

Comma-separated output formats. Default: svg,pdf,png. Use SVG/PDF for publication; PNG is for quick review.

--combined-pdf <combined_pdf>

Optional multi-page PDF path. Default: <out>/paper_figures.pdf. Pass ‘none’ to skip.

--sample-table <sample_table>

Optional sample table with sample_id and sample_group columns. When present, panels that were recent-sample-only in the 2023 notebooks use –sample-group.

--sample-group <sample_group>

Sample group for recent-only multiallelic panels.

--candidate-predictor <candidate_predictor>

Predictor to treat as the candidate MHCflurry model in notebook-style comparison panels. Default: mhcflurry_production.

--external-baselines <external_baselines>

Comma-separated external predictor comparators. Each item is PREDICTOR or PREDICTOR:PERCENT_CHANGE_SUFFIX. Default: netmhcpan4.ba:ba,netmhcpan4.el:el,mixmhcpred:mixmhcpred.

--preferred-predictors <preferred_predictors>

Comma-separated predictors for summary bar panels. Default: netmhcpan4.ba,netmhcpan4.el,mixmhcpred,mhcflurry_production,presentation_without_flanks_presentation_score,presentation_with_flanks_presentation_score.

--monoallelic-panel-predictors <monoallelic_panel_predictors>

Comma-separated candidate predictors to show as rows in the monoallelic AUROC/AUPRC/PPV comparison grids. Default: only –candidate-predictor.

--presentation-panel-predictors <presentation_panel_predictors>

Comma-separated candidate predictors for presentation-vs-baseline scatter grids. Default: presentation_without_flanks_presentation_score,presentation_with_flanks_presentation_score.

--presentation-panel-baselines <presentation_panel_baselines>

Comma-separated baseline predictors for presentation-vs-baseline scatter grids. Default: netmhcpan4.ba,netmhcpan4.el,mixmhcpred,mhcflurry_production.

--max-scatter-points <max_scatter_points>

Subsample scatter plots above this many points.

--strict

Return a non-zero exit code if any requested non-metadata figure family skips or fails.

Figure input contract:

• comparison-dir: output from mhcflurry eval compare-models.

• scores-dir: reusable paper-figure inputs. Common files are accuracy_scores.multiallelic.csv, accuracy_scores.monoallelic.csv, benchmark.multiallelic.csv(.bz2), benchmark.monoallelic.csv(.bz2), sample_table.csv, and predictor_info.csv.

• saved prediction tables: include hit, sample_id or allele/hla, optional peptide metadata, and canonical or explicitly declared score columns.

• score direction is explicit. Built-in predictor names have defaults; custom score columns require predictor_info.csv rows with predictor and higher_is_better.

Missing optional figure inputs are recorded in manifest.csv and missing_inputs.md instead of being silently fabricated.

Other evaluation workflows

mhcflurry eval also contains specialized workflows for release experiments and external-predictor comparisons.

$ mhcflurry eval --help
usage: mhcflurry eval <subcommand> [args]

Evaluation and paper-figure workflows.

Subcommands:
  compare-models          Compare two model ensembles.
  saved-candidate         Finish saved candidate evaluation without training.
  plot-comparison         Render diagnostic plots from compare output.
  affinity-candidate-figures
                          Plot finalists and public on one saved cohort.
  merge-external-predictions
                          Consolidate precomputed external predictions.
  processing-flank-ablation  Test fixed weights with perturbed external flanks.
  processing-affinity-control
                          Score affinity-controlled processing risk sets.
  prepare-processing-cohort
                          Expand and freeze a shared matched evaluation set.
  processing-ensemble     Score an ensemble from saved predictions.
  presentation-percentiles  Compare compact calibration curves and ranking metrics.
  presentation-external-predictors
                          Compare saved scores with NetMHCpan and MixMHCpred.
  processing-ensemble-subsets  Evaluate every fixed-size ensemble subset.
  paired-sample-metrics   Bootstrap matched per-sample metric differences.
  processing-recipe-analysis  Map paired processing hyperparameter effects.
  processing-fold-ensembles  Compare cached ensembles within shared held-out folds.
  collate-figures         Combine annotated experiment figures into a PDF.
  presentation-affinity-ensemble
                          Evaluate saved public/new affinity mixtures.
  release-experiment-figures
                          Render archived release experiment figures.
  paper-figures render    Render paper figures from saved inputs.
  paper-figures score-predictions
                          Derive score tables from saved predictions.
  paper-figures external-predictors
                          Add optional external predictor columns.
  paper-figures run       Compare, render paper figures, and write PDFs.

Compatibility:
  mhcflurry compare-models, mhcflurry plot-model-comparison, and
  mhcflurry paper-figures remain supported.

Options:
  -h, --help  show this help message and exit

Release and research workflows

mhcflurry train groups the release pipeline and research workflows used to produce the published models. Most need a source checkout; see Training models and Maintainer workflows.

$ mhcflurry train --help
usage: mhcflurry train {pan-allele-release,release-holdout,plot-loss-curves,snapshot-experiment,materialize-affinity-checkpoint,compose-processing-ensemble,audit-training-data,exact-public-processing,processing-data,validate-processing-data,processing-kernel-sweep,processing-hyperparameter-sweep,benchmark-processing-sampler,benchmark-processing-preparation} ...

Training workflows.

Subcommands:
  pan-allele-release  Train/evaluate/plot release weights from one entry point.
  release-holdout     Build/validate frozen evaluation exclusions.
  plot-loss-curves    Plot candidate losses and selected models.
  snapshot-experiment Archive hashes, provenance, metrics, and epoch tables.
  materialize-affinity-checkpoint
                      Select retained terminal or best affinity weights.
  compose-processing-ensemble
                      Build a provenance-recorded processing ensemble.
  audit-training-data Audit exact row identity and multiplicities.
  exact-public-processing Replay exact public processing/presentation data.
  processing-data      Generate matched processing training data.
  processing-kernel-sweep Train/evaluate the paired 48-network width sweep.
  processing-hyperparameter-sweep Run a paired width or training-recipe design.
  benchmark-processing-sampler Compare candidate sampling implementations.
  benchmark-processing-preparation Check numeric, matching and prediction parity/timings.
  validate-processing-data Verify cached matching assignments and metadata.

Examples:
  mhcflurry train pan-allele-release --run-dir runs/2.3.0 --release 2.3.0 --backend local
  mhcflurry train pan-allele-release --run-dir runs/2.3.0 --release 2.3.0 --backend brev-provision
  mhcflurry train plot-loss-curves --selected-dir models.combined --out plots
  mhcflurry train snapshot-experiment --source-dir results/run --name batch-sweep
  mhcflurry train materialize-affinity-checkpoint --models-dir models.unselected.combined --policy best --out-models-dir models.unselected.best

Deployment is opt-in. Pass --deploy-mode dry-run, draft, or publish to run the model-artifact deployment step.

Helpers

These commands support release training and data preparation rather than prediction. The grids from class1-generate-training-hyperparameters feed the maintained training scripts; see the training pipeline README for how each grid is used. Auditing training-sample overlap shows how the mass-spec reassignment command excludes evaluation peptide–MHC pairs and source samples.

mhcflurry class1-generate-training-hyperparameters

Generate release-training hyperparameter grids.

usage: mhcflurry class1-generate-training-hyperparameters [-h]
                                                          {affinity,processing-base,processing-variant}
                                                          ...

-h, --help

show this help message and exit

mhcflurry class1-generate-training-hyperparameters affinity

usage: mhcflurry class1-generate-training-hyperparameters affinity
       [-h] [--minibatch-size MINIBATCH_SIZE]
       [--optimizer-implementation {keras,pytorch}]
       [--data-dependent-initialization-target {post_activation,pre_activation}]
       [--init {glorot_uniform,glorot_normal,he_uniform,he_normal,orthogonal}]

-h, --help

show this help message and exit

--minibatch-size <minibatch_size>

Training minibatch size to write into every architecture. Default: 128

--optimizer-implementation {keras,pytorch}

Optimizer update equations to write into every architecture. Default: keras (published 2.1.x parity)

--data-dependent-initialization-target {post_activation,pre_activation}

LSUV activation boundary. Default: post_activation (2.1.x parity)

--init {glorot_uniform,glorot_normal,he_uniform,he_normal,orthogonal}

Affinity-layer initializer. Default: glorot_uniform (2.1.x parity)

mhcflurry class1-generate-training-hyperparameters processing-base

usage: mhcflurry class1-generate-training-hyperparameters processing-base
       [-h] [--minibatch-size MINIBATCH_SIZE]
       [--optimizer-implementation {keras,pytorch}]
       [--init {glorot_uniform,kaiming_uniform_fan_in}]

-h, --help

show this help message and exit

--minibatch-size <minibatch_size>

Training minibatch size to write into every architecture. Default: 512

--optimizer-implementation {keras,pytorch}

Optimizer update equations to write into every architecture. Default: keras (published 2.1.x parity)

--init {glorot_uniform,kaiming_uniform_fan_in}

Processing-layer initializer. Default: glorot_uniform (2.1.x parity)

mhcflurry class1-generate-training-hyperparameters processing-variant

usage: mhcflurry class1-generate-training-hyperparameters processing-variant
       [-h] [--optimizer-implementation {keras,pytorch}]
       [--init {glorot_uniform,kaiming_uniform_fan_in}]
       YAML {with_flanks,no_n_flank,no_c_flank,no_flank,short_flanks}

yaml

Base processing hyperparameter grid YAML.

kind

Processing flank variant to output.

-h, --help

show this help message and exit

--optimizer-implementation {keras,pytorch}

Override the optimizer equations in every architecture. If omitted, retain the value from the base YAML.

--init {glorot_uniform,kaiming_uniform_fan_in}

Override the initializer in every architecture. If omitted, retain the value from the base YAML.

mhcflurry class1-reassign-mass-spec-training-data

Reassign affinity values for mass-spec training rows.

usage: mhcflurry class1-reassign-mass-spec-training-data [-h] [--ms-only]
                                                         [--drop-negative-ms]
                                                         [--set-measurement-value SET_MEASUREMENT_VALUE]
                                                         [--out-csv OUT_CSV]
                                                         [--exclude-pmhcs EXCLUDE_PMHCS]
                                                         [--exclude-source-samples EXCLUDE_SOURCE_SAMPLES]
                                                         [--sample-aliases SAMPLE_ALIASES]
                                                         [--verbose]
                                                         CSV

csv

Training data.

-h, --help

show this help message and exit

--ms-only

Keep only mass-spec rows.

--drop-negative-ms

Drop mass-spec rows whose measurement_inequality is not ‘<’.

--set-measurement-value <set_measurement_value>

Replace measurement_value for every remaining mass-spec row.

--out-csv <out_csv>

Write the edited table here. Without it, nothing is written.

--exclude-pmhcs <exclude_pmhcs>

CSV of frozen evaluation allele,peptide pairs to exclude.

--exclude-source-samples <exclude_source_samples>

CSV of study_id,sample_id exclusions

--sample-aliases <sample_aliases>

Explicit study/specimen alias CSV; requires –exclude-source-samples.

--verbose

Print input and changed-row previews.

mhcflurry pseudosequences

Note

mhcflurry pseudosequences is a shell-helper CLI for the pseudosequence CSV registry. It has its own subcommands (filename, path, list, legacy); run mhcflurry pseudosequences --help for the full argument forms.