Command line¶

mhctools is one executable with subcommands. Run mhctools <command> --help for every option.

Run mhctools --version (or mhctools -V) to print the installed package version, for example mhctools 4.7.1. This needs no predictor or input. mhctools fetch --version REVISION instead selects an upstream artifact revision.

Tab completion and help¶

For Bash or zsh, enable completion in the current shell with:

eval "$(register-python-argcomplete mhctools)"

Add that line to your shell configuration to keep it enabled. Alternatively, run activate-global-python-argcomplete once and start a new shell for global activation across participating OpenVax tools. Global Bash activation requires Bash 4.2 or newer; macOS's bundled Bash 3.2 can use the per-command registration above. Argcomplete's documentation covers shell setup.

Completion includes subcommands, aliases, command options, predictor names (including comma-separated selections), local paths and fixed option choices. It does not initialize predictors, scan the Ensembl cache, or contact the network.

Help uses cyan flags and bold cyan headings in a terminal. Catalog tables use the same headings, dim unavailable fields and yellow warning statuses. Redirected help, JSON and prediction tables remain plain. Set NO_COLOR (including an empty value) or TERM=dumb to disable styling.

Commands¶

Command	Does	More
`mhctools`	Predict for peptides or FASTA sequences	below
`mhctools ls`	List model artifacts and where they live	getting models
`mhctools fetch`	Download model weights and tool snapshots	getting models
`mhctools predictors`	Report which predictors can actually run (`integrations` is an alias)	getting models
`mhctools predict-table`	Append predictor scores to a CSV	below
`mhctools cleavage`	Per-bond peptidase evidence	cleavage
`mhctools cleavenet`	Whole-substrate MMP scores for peptides or ten-residue windows	CleaveNet
`mhctools vaccine-report`	Route-aware vaccine construct report	vaccine reports
`mhctools vaccine-trajectory`	Simulate explicit SLP/mRNA kinetics and write a readable report	trajectory guide
`mhctools vaccine-windows`	Dose-normalized per-core candidate window exposure	window guide
`mhctools vaccine-compare`	Compare matched trajectory results with dose and evidence context	comparison guide
`mhctools benchmark`	Assay-aware model evaluation	benchmarks
`mhctools mixtcrpred`	Score paired TCRs against a fixed target	TCR predictors

The default command takes --mhc-predictor (one or more names, space or comma separated), --mhc-alleles or --mhc-alleles-file, and one input. The accepted names are listed by mhctools --help and in the CLI names column of the predictor matrix. TCR predictors have no name here because their input is a peptide plus a TCR.

--mhc-alleles accepts separate values or a comma- or space-separated list:

--mhc-alleles 'HLA-A*02:01' 'HLA-B*07:02'
--mhc-alleles 'HLA-A*02:01,HLA-B*07:02'
--mhc-alleles 'HLA-A*02:01 HLA-B*07:02'

Keep the quotes so the shell does not expand * to filenames or reject an unmatched pattern. --mhc-alleles-file takes one allele per line.

Predict for peptides you supply¶

mhctools --sequence SIINFEKL GILGFVFTL --mhc-predictor mhcflurry --mhc-alleles 'HLA-A*02:01'

source_sequence_name    offset  peptide allele  score   affinity    percentile_rank prediction_method_name  length
    0   SIINFEKL    HLA-A*02:01 0.192203    6249.06 7.96416 mhcflurry   8
    0   GILGFVFTL   HLA-A*02:01 0.699441    25.8414 0.130863    mhcflurry   9

--sequence may be repeated and all occurrences accumulate. Or use --input-peptides-file for one peptide per line (blank lines ignored), or --input-fasta-file for protein sequences. Pick exactly one of the three.

Extract subsequences automatically¶

mhctools --sequence AAAQQQSIINFEKL --extract-subsequences \
    --mhc-peptide-lengths 8-10 --mhc-predictor mhcflurry --mhc-alleles A0201

Annotate a table (`predict-table`)¶

Reads a CSV, runs each requested predictor once, and appends one score column per predictor, choosing the best allele per row, while preserving every input column:

mhctools predict-table \
    --input benchmark.csv.bz2 \
    --peptide-column peptide \
    --alleles-column hla \
    --predictor netmhcpan42-ba:netmhcpan4.2.ba:affinity \
    --predictor netmhcpan42-el:netmhcpan4.2.el:score \
    --out benchmark.with_scores.csv.bz2

Each --predictor spec is NAME[:OUTPUT_COLUMN[:FIELD]], where FIELD is affinity, score, or percentile_rank. Lower is better for affinity and percentile_rank, higher for score.

A row may hold several alleles per cell (whitespace-, comma-, or semicolon-separated); the best one per peptide is chosen and recorded in a <OUTPUT_COLUMN>_best_allele provenance column. Missing or blank peptide/allele cells stay unscored. They are not coerced into a literal sequence or allele string and sent to a predictor.

Pass --predictor-info info.csv to also write a sidecar describing each column's score_field, units, and higher_is_better. Empty units means the field is dimensionless or predictor-specific.

Output conventions¶

Prediction tables use the same columns and units for every predictor:

Column	Convention
`prediction_method_name`	the exact CLI predictor name you selected, including version and mode
`affinity`	IC50 in nM
`percentile_rank`	a 0–100 percentile
`score`	predictor-specific
`source_sequence_name`, `offset`	the source sequence and its zero-based offset

Plain peptide inputs get an empty source_sequence_name and offset 0. FASTA and subsequence inputs keep their source and zero-based offset, and their rows are ordered by those coordinates. CSV floats are serialized with six significant digits.

Default stdout is streamed as tab-separated values, so an empty source name survives as an empty field and large tables don't need a second formatted copy in memory. A downstream closed pipe (| head, say) exits cleanly.

Embed options in a report application¶

Applications that replay saved predictions can make predictor selection optional while keeping the shared model, allele and runtime options:

from argparse import ArgumentParser
from mhctools.cli import add_mhc_args, predictors_from_args

parser = ArgumentParser()
parser.add_argument("--rescore", action="store_true")
add_mhc_args(parser, predictor_required=False)
args = parser.parse_args()

if args.rescore:
    predictors = predictors_from_args(args)
    # Run fresh predictions with the explicitly selected predictors.

For replay, read the application's saved predictions without constructing a predictor.

Parsing does not construct predictors or read allele files. Calling predictors_from_args requires a nonempty --mhc-predictor selection and the alleles needed by the selected predictors. Unknown names remain parser errors. The default add_mhc_args(parser) and the standalone prediction CLI still require --mhc-predictor.