Installation

pVACtools is written for Linux but some users have been able to run it successfully on Mac OS X. If you are using Windows you will need to set up a Linux environment, for example by setting up a virtual machine.

pVACtools requires Python 3.6 or above. Before running any installation steps, check the Python version installed on your system:

python -V

If you don’t have Python 3 installed, we recommend using Conda to emulate a Python 3 environment. We’ve encountered problems with users that already have Python 2.x installed when they also try to install Python 3. The defaults will not be set correctly in that case. If you already have Python 2.x installed we strongly recommmend using Conda instead of installing Python 3 locally.

Once you have set up your Python 3 environment correctly you can use pip to install pVACtools. Make sure you have pip installed. pip is generally included in python distributions, but may need to be upgraded before use. See the instructions for installing or upgrading pip.

After you have pip installed, type the following command on your Terminal:

pip install pvactools

You can check that pvactools has been installed under the default environment like so:

pip show pvactools

pip will fetch and install pVACtools and its dependencies for you. After installing, each tool of the pVACtools suite is available in its own command line tree directly from the Terminal.

If you have an old version of pVACtools installed you might want to consider upgrading to the latest version:

pip install pvactools --upgrade

Installing IEDB binding prediction tools (strongly recommended)

Warning

Using a local IEDB installation is strongly recommended for larger datasets or when the making predictions for many alleles, epitope lengths, or prediction algorithms.

Warning

The IEDB binding prediction tools are only compatible with Linux.

You may create a local install of the IEDB binding prediction tools by first downloading the archives for class I and class II from the IEDB website. If using both the Class I and the Class II tools, they both need to be installed into the same parent directory.

pVACtools is only compatible with IEDB 3.1 and above. We have tested pVACtools with the versions of IEDB class I and II listed below. Using a different version may cause errors.

Important

By using the IEDB software, you are consenting to be bound by and become a “Licensee” for the use of IEDB tools and are consenting to the terms and conditions of the Non-Profit Open Software License (“Non-Profit OSL”) version 3.0.

Please read these two license agreements here before proceeding. If you do not agree to all of the terms of these two agreements, you must not install or use the product. Companies (for-profit entities) interested in downloading the command-line versions of the IEDB tools or running the entire analysis resource locally, should contact IEDB (license@iedb.org) for details on licensing options.

Citing the IEDB

All publications or presentations of data generated by use of the IEDB Resource Analysis tools should include citations to the relevant reference(s), found here.

MHC Class I

Download the archives for class I and unpack them.

apt-get update && apt-get install -y tcsh gawk
wget https://downloads.iedb.org/tools/mhci/3.1.5/IEDB_MHC_I-3.1.5.tar.gz
tar -zxvf IEDB_MHC_I-3.1.5.tar.gz
cd mhc_i
./configure

MHC Class II

Download the archives for class II and unpack them.

apt-get update && apt-get install -y tcsh gawk
wget https://downloads.iedb.org/tools/mhcii/3.1.11/IEDB_MHC_II-3.1.11.tar.gz
tar -zxvf IEDB_MHC_II-3.1.11.tar.gz
cd mhc_ii
./configure.py

Then run the configure script.

./configure.py

Installing MHCflurry

If you wish to run the MHCflurry prediction algorithm, you will need to install the mhcflurry python package on your system. This package is set as a dependency for the pvactools package so it should be installed automatically when you download or upgrade the pvactools package. You can install it manually by running:

pip install mhcflurry

Note

The mhcflurry package needs to be installed in the same Python 3 environment as the pvactools package.

Next, you will need to download the download the MHCflurry datasets and trained models:

mhcflurry-downloads fetch

Note

The mhcflurry-downloads fetch command will need to be run manually, even if the mhcflurry package was already installed automatically as a dependency with the pvactools package.

You can check that the mhcflurry package was installed successfully by running:

mhcflurry-predict -h

This should pull up the help page for the MHCflurry predictor.

Please note that MHCflurry depends on tensorflow, which will automatically be installed as a dependency to the mhcflurry package. Newer versions of tensorflow might not be compatible with older CPUs. In that case you will see a core dump failure. Downgrading tensorflow manually to version 1.5.0 should solve this problem:

pip install tensorflow==1.5.0

Installing MHCnuggets

If you wish to run the MHCnuggets prediction algorithm, you will need to install the mhcnuggets python package on your system. This package is set as a dependency for the pvactools package so it should be installed automatically when you download or upgrade the pvactools package. You can install it manually by running:

pip install mhcnuggets

Note

The mhcnuggets package needs to be installed in the same Python 3 environment as the pvactools package.

You can check that the mhcnuggets package was installed successfully by running:

pip show mhcnuggets

This should show information about the mhcnuggets package.

Please note that MHCnuggets depends on tensorflow, which will automatically be installed as a dependency to the mhcnuggets package. Newer versions of tensorflow might not be compatible with older CPUs. In that case you will see a core dump failure. Downgrading tensorflow manually to version 1.5.0 should solve this problem:

pip install tensorflow==1.5.0

Installing BigMHC

If you wish to run the BigMHC_EL or BigMHC_IM prediction algorithms, you will need to install BigMHC on your system. This package not a direct dependency of the the pvactools packages and needs to be installed manually by running:

pip install git+https://github.com/griffithlab/bigmhc.git#egg=bigmhc

Note

BigMHC needs to be installed in the same python 3 environment as the pvactools package.

You can check that BigMHC was installed successfully by running:

pip show bigmhc

This should show information about the BigMHC installation.

Installing DeepImmuno

If you wish to run the DeepImmuno prediction algorithm, you will need to install DeepImmuno on your system. This package not a direct dependency of the the pvactools packages and needs to be installed manually by running:

pip install git+https://github.com/griffithlab/deepimmuno.git#egg=deepimmuno

Note

DeepImmuno needs to be installed in the same python 3 environment as the pvactools package.

You can check that DeepImmuno was installed successfully by running:

pip show deepimmuno

This should show information about the DeepImmuno installation.

Installing BLAST

To run the reference proteome similarity step, standalone BLAST may be used. To install BLAST please see the official documentation. The BLAST tool needed is Protein BLAST (blastp). Please make note of the installation path of blastp (retrievable by calling which blastp), as that path is needed for the --blastp-path argument in the various pVACtools commands.

You will also need to install either the refseq_select_prot or the refseq_protein BLAST reference proteome databases. You can do so by running the update_blastdb.pl script provided with your BLAST installation (located in the bin subdirectory). You will need to set the BLASTDB to point to the installation directory of your BLAST reference proteome databases.

Downlaoding Reference Proteome FASTA file

As an alternative to BLAST, a reference proteome fasta file may be used for the reference proteome similarity step and specified as an input via the --peptide-fasta command. Any proteome fasta may be used. Ensembl provides reference proteome fastas for many species. For example, the latest reference proteome fasta for human can be downloaded from this link.

Docker and CWL

Versioned Docker containers for pVACtools are available on DockerHub using the griffithlab/pvactools repo. The Docker container contains pVACtools as well as installations of the standalone IEDB MHC Class I and Class II software. These are installed at /opt/iedb (--iedb-install-directory /opt/iedb).

An example on how to run pVACseq using Docker can be found on the Getting Started page.

Common Workflow Language (CWL) tool wrappers for pVACseq, pVACfuse, and pVACvector can be downloaded using the pvactools download_cwls command.

Download CWL tool wrappers

usage: pvactools download_cwls [-h] destination_directory

Download pVACtools CWLs for each tool's main pipeline

positional arguments:
  destination_directory
                        Directory for downloading CWLs

optional arguments:
  -h, --help            show this help message and exit