PANDORA

Peptide ANchored mODelling fRAmework for peptide-mhc complexes

Contents

• Overview
• Dependencies
• Installation
• Docker
• Tutorial
• Code Design
• Output
• License
• Issues
• Publication

Overview

PANDORA is anchor restrained modelling pipeline for generating peptide-MHC structures.

It contains multiple functions to pre-process data and it's able to exploit different crucial domain knowledge provided by the user to guide the modelling.

PANDORA documentation can be found at: https://csb-pandora.readthedocs.io/en/latest/

Dependencies

PANDORA requires MODELLER, python and some python libraries to be installed. The following installations are required to start PANDORA installation:

• Python = 3.11.10
• Conda
• pip3

The (conda) installation process takes care of installing the following dependencies (see Installation):

• BioPython
• muscle >= 5.1
• Modeller >= 9.3
• Blast >= 10.2
• pdb2sql (Required only for RMSD calculations for evaluation purposes)

Installation

1. Get a Modeller Key License:

Prior to PANDORA installation, you need to first activate MODELLER's license. Please request MODELLER license at: https://salilab.org/modeller/registration.html

Replace XXXX with your MODELLER License key and run the command:

export KEY_MODELLER='XXXX'

2. Install PANDORA

Option 1: GitHub / Pypi installation

1.1 Install Modeller:

Prior to PANDORA installation, you need to first activate MODELLER's license. Please request MODELLER license at: https://salilab.org/modeller/registration.html

Replace XXXX with your MODELLER License key and run the command:

export KEY_MODELLER='XXXX'

Then, install MODELLER with:

conda install -y -c salilab modeller

Note: You can also follow the instruction in the conda install output to enter your modeller key in the appropriate file afterwars, instead of setting it beforehand.

1.2 Install Other dependencies

PANDORA relies on muscle (https://anaconda.org/bioconda/muscle) and blast (https://anaconda.org/bioconda/blast) that can be both installed via bioconda.

conda install -c bioconda muscle=5.1 blast=2.10

For some HPC systems the conda blast installation might not work due to missing libraries. For those cases, you can download blast from their release page and install it (make shure you add it to your PATH, otherwise PANDORA will not be able to find it): https://ftp.ncbi.nlm.nih.gov/blast/executables/LATEST/

Note: Mac M1 processors cannot compile muscle version v5.0 and v5.1 from conda. To instll muscle, you will need to build it from source. You can find the muscle 5 code and the link to how to install from source in their GitHub repo.

1.3 Install PANDORA

Clone the repository:

git clone https://github.com/X-lab-3D/PANDORA.git

Enter the cloned directory and install the package:

cd PANDORA
pip install -e .

Option 2: Conda Installation

Install with conda:

conda install -c csb-nijmegen csb-pandora -c salilab -c bioconda

Note 1: The conda installation might, in rare cases, fail when performed under an institutional firewall with an "ERROR 404" error (example). For such cases we advise the users to opt for the pip installation above.

Note 2: Mac M1 processors cannot compile muscle version v5.0 and v5.1 from conda. To instll muscle, you will need to build it from source. You can find the muscle 5 code and the link to how to install from source in muscle GitHub repo.

Download Template Database

PANDORA needs a PDB template database to work. All the structures are retrieved from IMGT database.

The database can be quickly retrieved by zenodo by running the command-line tool:

pandora-fetch

Alternatively, the same function can be done in python:

from PANDORA import Database

Database.install_database()

(Advanced) Generate template Database

You can also generate the database from scratch, downloading and parsing the structures directly from IMGT. Please note that this does not include generation of MHC-II reversed templates yet. At the moment, those are only available in our published database.

The database can be generated with the command-line tool:

pandora-create

Or with the pythoncode below:

First, generate the necessary folders by running:

python install.py

Then, run the following script changing the path to the database you want to generate:

## import requested modules
from PANDORA import Database

## A. Create local Database
db = Database.Database()
db.construct_database(n_jobs=<n_jobs>)

Note 2: By default, the database generation will use one core only. You can sensitevly speed it up by changing the paramenter --num-cores for pandora-create or 'n_jobs' for Database.contruct_database().

Note 3: the database is saved by default into ~/PANDORA_databases/default. It is possible to modify the folder name (default) by creating a config.json file in the PANDORA installation folder using data_folder_name as a key, and the desired folder name as a value, like in the example below:

{"data_folder_name": "<folder_in_Databases>"}

(Optional) Install NetMHCpan and/or NetMHCIIpan

PANDORA lets the user to predict peptide's anchor residues instead of using conventional predefined anchor residues. In that case you need to download NetMHCpan (for peptide:MHC class I) and/or NetMHCIIpan (for peptide:MHC class II).

Once you have obtained the download link, you can install them by following the instructions in their .readme files. Note that PANDORA will assume they are installed and callable from command line (as netMHCpan and netMHCIIpan).

Docker

The Docker release is currently not uploaded on DockerHub and, due to licensing of external software (MODELLER and NetMHCpan), the only way to use at this moment is by building the docker image directly from the recipe.

We advice to use Docker only in case Conda or Git/Pypi installations are not possible in your system.

1. Get MODELLER lincense (and optional softwares, if desired)

First, you will always need to get a modeller license key and, optionally, the netMHCpan and netMHCIIpan installation packages (see Installation for details).

2. Download PANDORA

Download the GitHub repository:

git clone https://github.com/X-lab-3D/PANDORA.git
cd PANDORA

1. Add your license key

Now open the dockerfile and replace the "XXXX" at line 16 with your MODELLER license key.

4. (Optional) Install netMHCpan and/or netMHCIIpan

Download netMHCpan or netMHCIIpan directly into the PANDORA repository you cloned, then proceed with the installation as explained in their own .readme files until points 2.a and 2.b.

For points 2.a and 2.b, make sure you set NHOME to "/app/netMHCpan-<version>" and TMPDIR to "/app/netMHCpan-<version>/tmp" where <version> is the version of the software you downloaded (same for netMHCIIpan, as "/app/netMHCIIpan-<version>").

Finally, open the PANDORA dockerfile, uncomment lines 25-26, plus the lines referring to the software you want to install (29-30 for netMHCpan and 33-34 for netMHCIIpan), save and close the file.

In case, later, netMHCpan cannot be found by PANDORA, it might mean this step did not work as intended.

5. Create a database folder in your local machine

To avoid re-downloading the PANDORA database every time you run your docker container, you will need to dowload the database in a folder synced between the container and the local machine. To do so, create a folder (wherever you prefer in your machine). We will call the absolute path to this folder <path/to/local/db>

6. Compile the docker image

Make sure you are in the PANDORA repo, then run:

docker build -t pandora .

You may chance "pandora" to the name you want to give to your docker image. Also, be advised that including netMHCpan or netMHCIIpan into the image will take docker a considerable longer time.

7. Run the docker container

Run the docker container while linking the local database folder to the docker one:

docker run -v <path/to/local/db>:/root/PANDORA_databases/default/ -it pandora

8. (First time only) Download the PANDORA database Inside your docker container, run the following to download the database:

pandora-fetch

It will be downloaded into a folder we previously linked to <path/to/local/db>, thus will finally end up in your local machine.

9. Enjoy!

Done! Now you are ready to use PANDORA. Just remember to always run the docker container with:

docker run -v <path/to/local/db>:/root/PANDOR