.. _install: 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.5., 3.6, or 3.7. Before running any installation steps, check the Python version installed on your system: .. code-block:: none python -V If you don't have Python 3.7 installed, we recommend using `Conda `_ to emulate a Python 3.7 environment. We've encountered problems with users that already have Python 2.x installed when they also try to install Python 3.7. 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.7 locally. Once you have set up your Python 3.7 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: .. code-block:: none pip install pvactools You can check that ``pvactools`` has been installed under the default environment by listing all installed packages: .. code-block:: none pip list ``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: .. code-block:: none pip install pvactools --upgrade .. _iedb_install: 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. Note that we have tested pVACtools with the versions of IEDB class I and II listed below. Using a different version may cause problems. .. 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 `_. .. note:: Using a local IEDB install with pVACtools requires conda. pVACtools is written in python 3 and IEDB is only compatible with python 2.7. Because of this version mismatch, the pVACtools modules will create a custom python 2.7 environment and execute IEDB inside of it. This requires conda. MHC Class I ___________ Download the archives for `class I `_ and unpack them. .. code-block:: none apt-get update && apt-get install -y tcsh gawk wget https://downloads.iedb.org/tools/mhci/2.19.2/IEDB_MHC_I-2.19.2.tar.gz tar -zxvf IEDB_MHC_I-2.19.2.tar.gz cd mhc_i ./configure .. note:: Running the ``configure`` script requires a Python 2 environment. If you are currently emulating a Python 3 environment with Conda you will need to run ``source deactivate`` before executing the ``configure`` script. MHC Class II ____________ Download the archives for `class II `_ and unpack them. .. code-block:: none apt-get update && apt-get install -y tcsh gawk wget https://downloads.iedb.org/tools/mhcii/2.17.6/IEDB_MHC_II-2.17.6.tar.gz tar -zxvf IEDB_MHC_II-2.17.6.tar.gz cd mhc_ii ./configure.py On older versions of the IEDB software, you might need to update some paths in the configure scripts to use relative paths. Open the ``configure.py`` file and update the lines that set the ``smm`` and ``nn`` variables to use relative paths like so: .. code-block:: none smm = re.compile(curDir + "/netMHCII-1.1") nn = re.compile(curDir + "/netMHCII-2.2") Then run the configure script. .. code-block:: none ./configure.py .. note:: Running the ``configure`` script requires a Python 2 environment. If you are currently emulating a Python 3 environment with Conda you will need to run ``source deactivate`` before executing the ``configure`` script. 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: .. code-block:: none pip install mhcflurry .. note:: The ``mhcflurry`` package needs to be installed in the same python 3 conda environment as the ``pvactools`` package. Next, you will need to download the download the MHCflurry datasets and trained models: .. code-block:: none 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: .. code-block:: none 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: .. code-block:: none 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: .. code-block:: none pip install mhcnuggets .. note:: The ``mhcnuggets`` package needs to be installed in the same python 3 conda environment as the ``pvactools`` package. You can check that the ``mhcnuggets`` package was installed successfully by running: .. code-block:: none 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: .. code-block:: none pip install tensorflow==1.5.0 PostgreSQL ---------- pVACviz and pVACapi require a Postgres database. To install Postgres follow the `installation instructions `_. .. note:: On Debian-based Linux distributions version Postgres V9.6 or lower is required. Docker and CWL -------------- A Docker container for pVACtools is available on DockerHub using the `griffithlab/pvactools `_ repo. This Docker container includes installations of the IEDB class I and class II tools at ``/opt/iedb`` (``--iedb-install-directory /opt/iedb``). An example on how to run pVACseq using Docker can be found on the :ref:`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 __________________________ .. program-output:: pvactools download_cwls -h