MhcVizPipe command line interface

A command line interface for MhcVizPipe is available to facilitate e.g. automation, use in scripts, batch analysis.

How to access the command line interface

The command line interface is accessed through the cli module of MhcVizPipe. From the command line, the CLI help can be accessed thus:

$ python -m MhcVizPipe.cli --help

But if you are working with the standalone version of MhcVizPipe, it will be a little cumbersome to call the cli module like that, because the Python interpreter is located at MhcVizPipe/python/bin/python3 in Linux and Mac, and at MhcVizPipe/python/python3.exe on Windows. Further, you will always need to remember to add a --standlone argument which tells MhcVizPipe it is running in standalone mode. There is a better way.

The standalone version of MhcVizPipe has a convenient wrapper for the CLI. It is found in the MhcVizPipe directory, and is called MhcVizPipe_CLI.sh in Linux/MacOS and MhcVizPipe_CLI.exe in Windows. So to access the CLI help in the standalone version, you can use one of the following (using a terminal inside the MhcVizPipe directory):

(Linux and macOS): $ ./MhcVizPipe_CLI.sh --help

(Windows): > .\MhcVizPipe_CLI.exe --help

Both will show you the following help screen:

usage: cli.py [-h] [-f FILES [FILES ...]] [-t TEMPLATE] [-d {comma,tab}]
              [-H COLUMN_HEADER] [-a ALLELES [ALLELES ...]] -c {I,II}
              [-D DESCRIPTION] [-n NAME] [-p PUBLISH_DIRECTORY] [-e EXP_INFO]
              [--standalone]

Welcome to the MhcVizPipe command line interface (CLI). This CLI will allow
you to generate MhcVizPipe reports using standard scripting practices. If you
have not previously used the graphical interface on your computer, the first
time you run the CLI a config file will be created in one of two locations. If
you are running MVP from a standalone installation (i.e. not installed into
Python using PIP), the config file will be in the MhcVizPipe directory and
will be called mhcvizpipe.config. If you are running MhcVizPipe from Python
directly, the file will be created in your home directory:
/home/kevin/.mhcvizpipe.config. If it is the first time you have run
MhcVizPipe, be sure to check the configuration in the above file.

optional arguments:
  -h, --help            show this help message and exit
  -f FILES [FILES ...], --files FILES [FILES ...]
                        One or more files (space separated) containing peptide
                        lists to analyze.
  -t TEMPLATE, --template TEMPLATE
                        A tab-separated file containing file paths and
                        alleles. Can be used to process peptide lists with
                        different alleles at the same time. The first column
                        must be the file paths, and the respective alleles can
                        be put in the following columns, up to 6 per sample.
  -d {comma,tab}, --delimiter {comma,tab}
                        Delimiter if the file is delimited (e.g. for .csv use
                        "comma").
  -H COLUMN_HEADER, --column_header COLUMN_HEADER
                        The name of the column containing the peptide list, if
                        it is a multi-column file.
  -a ALLELES [ALLELES ...], --alleles ALLELES [ALLELES ...]
                        MHC alleles, spaces separated if more than one.
  -c {I,II}, --mhc_class {I,II}
                        MHC class
  -D DESCRIPTION, --description DESCRIPTION
                        An optional description of the experiment/analysis.
                        Enclose it in quotes, e.g. "This is a description of
                        my analysis".
  -n NAME, --name NAME  Submitter name (optional).
  -p PUBLISH_DIRECTORY, --publish_directory PUBLISH_DIRECTORY
                        The directory where you want the report published. It
                        should be an absolute path.
  -e EXP_INFO, --exp_info EXP_INFO
                        Optional details to be added to the report (e.g.
                        experimental conditions). Should be in this format
                        (including quotes): "A: Z; B: Y; C: X;" etc... where
                        ABC(etc.) are field names (e.g. cell line, # of cells,
                        MS Instrument, etc) and ZYX(etc) are details
                        describing the field (e.g. JY cell line, 10e6,
                        Orbitrap Fusion, etc.).
  --standalone          Run MVP in from a standalone installation (i.e. not
                        installed from PIP). You don't usually need to invoke
                        this as it is done automatically from the bash script
                        included in the standalone MhcVizPipe distribution.

Using the command line interface

One or more files with the same alleles for each

To analyze one or more peptide files using the same set of alleles for each, use the -f and -a arguments. This will generate a single report with all the files in the same report.

To process 2 files (peptide_file1.txt and peptide_file2.txt) with three alleles (HLA-A0201 HLA-B0702 HLA-C0702), and output the results in a specific directory, you would use the following command:

$ MhcVizPipe_CLI.sh -f /path/to/peptide_file1.txt /path/to/peptide_file2.txt -a HLA-A0201 HLA-B0702 HLA-C0702 -p /path/to/report_directory

If the peptide files have multiple columns, you will need to indicate which column contains the peptide sequences. If the column has the header Peptide, you would use this command:

$ MhcVizPipe_CLI.sh -f /path/to/peptide_file1.txt /path/to/peptide_file2.txt -H Peptide -a HLA-A0201 HLA-B0702 HLA-C0702 -p /path/to/report_directory

Note that we used an upper case H there (i.e. -H). The lower case h argument (-h) is reserved for displaying the help screen, so don't use it in this case.

Samples with different alleles

If you want to analyze samples with different alleles for each sample, you need to take a slightly different approach. You will have to create a "template" file and provide it with the argument -t. This file will contain the paths to the peptide files and the respective alleles, so in this case you do not need the -f and -a arguments.

$ MhcVizPipe_CLI.sh -t /path/to/template_file.txt -p /path/to/report_directory

The template file above must be tab separated, and needs to contain in the first column the path to each peptide file, and in subsequent columns the alleles to use for each file. For example, the following is a valid file:

/path/to/file1.txt  HLA-A0201   HLA-B0702
/path/to/file2.txt  HLA-A0201   HLA-B3501
/path/to/file3.txt  HLA-A0101   HLA-B0702 HLA-C0701

The resulting report will contain all the peptide files, and each file will have been processed using only it's respective alleles.