Command-line reference

This page lists every command and option. If you are new to MHCflurry or are choosing a workflow, start with the tutorial and return here to look up specific arguments.

MHCflurry 2.3.0 provides a unified mhcflurry command while retaining the historical mhcflurry-* names. Both forms use the same implementation. See Configuration and performance for the naming convention, Evaluating trained models for the evaluation workflow, and the generated argument reference below for every option.

Prediction and data

mhcflurry predict

Run MHCflurry predictor on specified peptides.

By default, the presentation predictor is used, and predictions for MHC I binding affinity, antigen processing, and the composite presentation score are returned. If you just want binding affinity predictions, pass –affinity-only.

Examples:

Write a CSV file containing the contents of INPUT.csv plus additional columns giving MHCflurry predictions:

$ mhcflurry predict INPUT.csv –out RESULT.csv

The input CSV file is expected to contain columns “allele”, “peptide”, and, optionally, “n_flank”, and “c_flank”. An allele cell may contain one allele or a comma-, semicolon-, or whitespace-separated sample genotype. For multi-allele cells, the output row reports the strongest binding allele.

If --out is not specified, results are written to stdout.

You can also run on alleles and peptides specified on the commandline, in which case predictions are written for all combinations of alleles and peptides:

$ mhcflurry predict –alleles HLA-A0201 H-2Kb –peptides SIINFEKL DENDREKLLL

Instead of individual alleles (in a CSV or on the command line), you can also give a comma- or semicolon-separated sample genotype. In this case, the tightest binding affinity across the alleles for the sample will be returned. For example:

$ mhcflurry predict –peptides SIINFEKL –alleles ‘HLA-A*02:01;HLA-A*03:01’

will report the tightest predicted affinity across the two alleles for each peptide.

usage: mhcflurry predict [-h] [--list-supported-alleles]
                         [--list-supported-peptide-lengths] [--version]
                         [--alleles ALLELE [ALLELE ...]]
                         [--peptides PEPTIDE [PEPTIDE ...]]
                         [--allele-column NAME] [--peptide-column NAME]
                         [--n-flank-column NAME] [--c-flank-column NAME]
                         [--no-throw] [--out OUTPUT.csv]
                         [--prediction-column-prefix NAME]
                         [--output-delimiter CHAR] [--no-affinity-percentile]
                         [--always-include-best-allele] [--models DIR]
                         [--affinity-only] [--no-flanking] [--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}]
                         [INPUT.csv]

input.csv: Input CSV

-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

--alleles <allele>: Allele or genotype queries (exclusive with an input CSV). Separate arguments are independent queries; delimit alleles within one argument with ‘;’ or ‘,’ to score them as one genotype.

--peptides <peptide>: Peptides to predict (exclusive with passing an input CSV)

--allele-column <name>: Input column name for allele or delimited-genotype 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.2.0/models_class1_presentation/models

--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 use --gpus * --max-workers-per-gpu when CUDA GPUs are specified, otherwise 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. 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.

--matmul-precision {none,highest,high,medium}: torch.set_float32_matmul_precision setting. CPU/MPS: no-op.

mhcflurry predict-scan

Scan protein sequences using the MHCflurry presentation predictor.

By default, sub-sequences (peptides) with affinity percentile ranks less than 2.0 are returned. You can also specify –results-all to return predictions for all peptides, or adjust the filter threshold(s) using the –threshold-* options.

Examples:

Scan a set of sequences in a FASTA file for binders to any alleles in a MHC I genotype:

$ mhcflurry predict-scan test/data/example.fasta –alleles ‘HLA-A*02:01;HLA-A*03:01’

Instead of a FASTA, you can also pass a CSV that has “sequence_id” and “sequence” columns.

You can also specify multiple MHC I genotypes to scan as space-separated arguments to the –alleles option:

$ mhcflurry predict-scan example.fasta –alleles ‘A0201;A0301’ ‘B0702;B0801’

If --out is not specified, results are written to standard out.

You can also specify sequences on the commandline:

mhcflurry predict-scan –sequences MGYINVFAFPFTIYSLLLCRMNSRNYIAQVDVVNFNLT –alleles HLA-A*02:01

usage: mhcflurry predict-scan [-h] [--list-supported-alleles]
                              [--list-supported-peptide-lengths] [--version]
                              [--input-format {guess,csv,fasta}]
                              [--alleles ALLELE [ALLELE ...]]
                              [--sequences SEQ [SEQ ...]]
                              [--sequence-id-column NAME]
                              [--sequence-column NAME] [--no-throw]
                              [--peptide-lengths L] [--results-all]
                              [--threshold-presentation-score THRESHOLD_PRESENTATION_SCORE]
                              [--threshold-processing-score THRESHOLD_PROCESSING_SCORE]
                              [--threshold-affinity THRESHOLD_AFFINITY]
                              [--threshold-affinity-percentile THRESHOLD_AFFINITY_PERCENTILE]
                              [--out OUTPUT.csv] [--output-delimiter CHAR]
                              [--no-affinity-percentile] [--models DIR]
                              [--no-flanking] [--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}]
                              [INPUT]

input: Input CSV or FASTA

-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

--input-format {guess,csv,fasta}: Format of input file. By default, it is guessed from the file extension.

--alleles <allele>: Sample allele or genotype 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: Return results for all peptides regardless of affinity, etc.

--threshold-presentation-score <threshold_presentation_score>: Threshold if filtering by presentation score. Default: > 0.7

--threshold-processing-score <threshold_processing_score>: Threshold if filtering by processing score. Default: > 0.5

--threshold-affinity <threshold_affinity>: Threshold if filtering by affinity. Default: < 500

--threshold-affinity-percentile <threshold_affinity_percentile>: Threshold if filtering by affinity percentile. Default: < 2.0

--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.2.0/models_class1_presentation/models

--no-flanking: Do not use flanking sequence information in predictions

--num-jobs <n>: Number of local prediction worker processes. Pass ‘auto’ (default) to use --gpus * --max-workers-per-gpu when CUDA GPUs are specified, otherwise 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. 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.

--matmul-precision {none,highest,high,medium}: torch.set_float32_matmul_precision setting. CPU/MPS: no-op.

mhcflurry downloads

Download MHCflurry released datasets and trained models.

Examples

Fetch the default downloads:: $ mhcflurry-downloads fetch
Fetch a specific download:: $ mhcflurry-downloads fetch models_class1_pan
Get the path to a download:: $ mhcflurry-downloads path models_class1_pan
Get the URL of a download:: $ mhcflurry-downloads url models_class1_pan
Summarize available and fetched downloads:: $ mhcflurry-downloads info

usage: mhcflurry downloads [-h] [--quiet] [--verbose]
                           {fetch,info,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.2.0

--already-downloaded-dir <dir>: Don’t download files, get them from DIR

mhcflurry downloads info

usage: mhcflurry downloads info [-h]

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

mhcflurry downloads path

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

download_name

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

mhcflurry downloads url

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

download_name

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

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_presentation}: Type of predictor to calibrate

--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>: Number of peptides per length to use to calibrate percent ranks. Default: 100000.

--num-genotypes <n>: Used when calibrating a presentation predictor. Number of genotypesto sample

--alleles-per-genotype <n>: Used when calibrating a presentation predictor. Number of alleles per genotype. 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. Same output as the default path (bit-identical on CUDA, ~1e-6 log-IC50 drift on MPS due to missing fp64 support), typically 5-30x faster on CUDA for the full pan-allele universe. Ignored when running a presentation predictor or serial/cluster mode.

--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 defaults on inside maybe_compile_loss. 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 controlling all randomness in this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Defaults to 42, so runs are reproducible out of the box; pass a different integer for a different (still reproducible) run.

Class I training and selection

`mhcflurry train`

mhcflurry train groups release-training workflows. It is a namespace command; run mhcflurry train --help or the concrete subcommand help for the complete argument list.

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

Subcommands:
  pan-allele-release  Run the retrain/evaluate/plot/release workflow.

The release workflow delegates to the maintained release script:

$ mhcflurry train pan-allele-release --help

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 controlling all randomness in this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Defaults to 42, so runs are reproducible out of the box; pass a different integer for a different (still reproducible) run.

--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 defaults on inside maybe_compile_loss. 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 defaults on inside maybe_compile_loss. 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 controlling all randomness in this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Defaults to 42, so runs are reproducible out of the box; pass a different integer for a different (still reproducible) run.

mhcflurry class1-train-pan-allele-models

usage: 
Train Class1 pan-allele models.

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

--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 controlling all randomness in this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Defaults to 42, so runs are reproducible out of the box; pass a different integer for a different (still reproducible) run.

--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.

--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 defaults on inside maybe_compile_loss. 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

--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 defaults on inside maybe_compile_loss. 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

--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 controlling all randomness in this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Defaults to 42, so runs are reproducible out of the box; pass a different integer for a different (still reproducible) run.

--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 defaults on inside maybe_compile_loss. 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

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

--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 defaults on inside maybe_compile_loss. 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 defaults on inside maybe_compile_loss. 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 controlling all randomness in this command (numpy, Python random, and torch): data shuffles, fold/held-out sampling, weight initialization, and random peptide/negative sampling. Defaults to 42, so runs are reproducible out of the box; pass a different integer for a different (still reproducible) run.

Evaluation and figures (new in 2.3.0)

`mhcflurry eval`

mhcflurry eval groups model comparison, diagnostic plotting, reusable score generation, and paper-style figure rendering. It is a namespace command; run the concrete subcommand help for the complete argument list.

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

Subcommands:
  compare-models                 Compare two model ensembles.
  plot-comparison                Render diagnostic plots from compare output.
  paper-figures render           Render paper figures from saved inputs.
  paper-figures score-predictions
                                 Derive score tables from saved predictions.
  paper-figures run              Compare, render paper figures, and write PDFs.

Evaluation and Plotting Artifacts

The commands deliberately separate reusable metrics from rendering. See Evaluating trained models for the output map, saved-prediction schema, paper-figure workflow, and external-predictor integration.

mhcflurry 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 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]
                                [--b-affinity-dir B_AFFINITY_DIR]
                                [--b-processing-dir B_PROCESSING_DIR]
                                [--b-presentation-dir B_PRESENTATION_DIR]
                                [--b-training-dir B_TRAINING_DIR] --out OUT
                                [--include INCLUDE] [--data-dir DATA_DIR]
                                [--limit-files LIMIT_FILES]
                                [--affinity-source {mixmhcpred,netmhcpan4,both}]
                                [--processing-modes PROCESSING_MODES]
                                [--presentation-modes PRESENTATION_MODES]
                                [--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.

--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.

--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.

--limit-files <limit_files>: Smoke-test: only read first N benchmark files.

--affinity-source {mixmhcpred,netmhcpan4,both}: Which monoallelic benchmark source to use for affinity eval.

--processing-modes <processing_modes>: Comma-separated subset of {with_flanks, no_flank, short_flanks} for the processing component.

--presentation-modes <presentation_modes>: Comma-separated subset of {with_flanks, without_flanks} for the presentation component.

--num-jobs <n>: Number of local prediction worker processes. Pass ‘auto’ (default) to use --gpus * --max-workers-per-gpu when CUDA GPUs are specified, otherwise 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. 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.

--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 plot-model-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 plot-model-comparison [-h] --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

--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 paper-figures

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 paper-figures [-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]
                               [--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,presentation_without_flanks_processing_score,presentation_with_flanks_processing_score.

--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.

Prefer the namespaced mhcflurry eval ... form in new automation. Compatibility shortcuts remain available for existing scripts.

Pseudosequence registry helper

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.