Command-line reference#

Twenty-three commands, one binary — two of them, cassette and build, have sub-verbs; cassette has seven. mhcmatch --help lists two more: vector and deslip, deprecated aliases named once at the end of the cassette table and spelled currently everywhere else.

This page groups the commands by what you are trying to do; every command also has mhcmatch <command> --help.

Important

Pass ``–peptides FILE``, never loop the shell. The expensive part of most commands is setup a per-peptide invocation re-pays every time: the presentation and affinity calibrators ~5 s, the binder calibrator ~45 s. One process over a list is the difference between seconds per peptide and thousands per second.

The calibrators survive the process — they are cached under $MHCMATCH_CALIBRATION_CACHE, so they are paid once per machine rather than once per run. Peptide origin search needs nothing staged: it builds one seqtree.TextIndex per proteome in 0.7 s, answering every length and every substitution radius from that one build (Staging reference data: the four tiers of bootstrap).

--threads N controls native searches in source, mimics, genes, neoag, mimicry and rank annotations. It defaults to one; zero opts into the available CPU allocation. Scoring stays serial. Within an outer workflow, use one native thread per task.

Machine-readable output#

Every command whose result is a table takes --out FILE and writes tab-separated values with a header row; progress and provenance go to stderr behind #.

--peptides is read two ways, and the difference is not cosmetic. complement, mimics and source take a bare list, one peptide per line. neoag and mimicry take a TSV with a header, because they carry every non-peptide column of that file through into their output — so the column naming the peptide has to be identifiable, and it may be spelled peptide or epitope. Handing them a bare list fails with no `peptide` / `epitope` column. scan, logo and expression print an aligned, human-readable form by default and switch to TSV under --out or --tsv — the aligned form of expression writes median 0.33 and IQR 0.1-0.9 inside cells, which reads well and parses badly, and the aligned form of logo keeps only the top three residues per position where the TSV carries the whole PWM.

This is the interface the figures of the mhcmatch paper are built on: each one’s underlying table is produced by a script that drives these commands, so a reader with the package installed regenerates the table rather than trusting it.

Routine tasks#

your question

command

Which peptides in this FASTA are presented?

mhcmatch predict f.fasta --cls mhc1 --alleles 'HLA-A*02:01'

Which allele presents this peptide?

mhcmatch restriction PEP --calibrated

Is it a binder at all, as one number?

mhcmatch binder PEP

What is the IC50, and how does it compare with the wild type?

mhcmatch affinity PEP --wt WTPEP --allele 'HLA-A*02:01'

Which windows of this protein are presented?

mhcmatch scan p.fasta --correction bh

Will a T cell recognise it?

mhcmatch complement --peptides p.txt

Turn a donor’s HLA typing file into an allele list

mhcmatch alleles sample.hla.tsv --cls mhc1

Rank a donor’s neoantigen candidates end to end

mhcmatch rank fasta cand.fasta --alleles donor.txt --tumor SKCM

Re-rank my candidate table, keeping every column I sent

mhcmatch rank pairs mine.tsv --passthrough --prefix mm_ --context windows.fasta

What model is doing the ranking, and how well does it hold out?

mhcmatch rank --coefficients / mhcmatch rank --holdout

Why did this candidate rank where it did?

mhcmatch explain PEP --allele 'HLA-A*02:01'

Has this, or something within 1-2 substitutions, already been tested?

mhcmatch neoag --peptides p.tsv

What self / viral / bacterial peptide does it resemble?

mhcmatch mimics --peptides p.txt --threads 0

Does that resemblance raise or lower the risk, and through which channel?

mhcmatch mimicry --peptides p.tsv

Where in the proteome does it come from?

mhcmatch source --peptides p.txt --proteome human --threads 0

Which gene does this candidate come from?

mhcmatch genes cand.tsv --out annotated.tsv

Has this peptide been seen expressed in the tumour, and is its gene on in normal tissue?

mhcmatch expression PEPTIDE --tumor SKCM / mhcmatch expression GENE --safety

Which k of this donor’s candidates should the cassette carry?

mhcmatch cassette select --candidates pool.tsv -k 20 --tol 3

What is this cassette worth, against one from another donor of another size?

mhcmatch cassette score --cassettes c.tsv --pool pool.tsv

Where does this patient sit in a cohort I already have outcomes for?

mhcmatch cassette report --cassettes c.tsv --reference cohort.tsv --out report.html

Build a vaccine cassette from ranked candidates

mhcmatch cassette build --candidates units.tsv --n0 8 --screen

…and a map of it a viewer can draw

mhcmatch cassette build ... --map cassette.tsv --map-json cassette.json

What does this allele’s motif look like?

mhcmatch logo 'HLA-A*02:01'

What is the full MHC-II ligand around this core?

mhcmatch span CORE --protein p.fasta

Two commands people expect to be one#

predict is the presentation axis — is this presented at all, the NetMHCpan %Rank_EL analogue. restriction is the specificity axis — which allele presents it. They answer different questions and a peptide can top one and not the other: NLVPMVATV is unambiguously HLA-A*02:01-restricted, yet bands mid-pack against A*02:01’s own ligands.

The full reference, in three pages

The routine cases above cover most sessions; these are the rest of the reference.