TUTORIAL.md

Introduction

The tutorial notebooks in this folder can be run to learn how to use DeepRank2.

• There are two tutorial notebooks for data generation, which demonstrate how to create _.hdf5-formatted input training data from raw _.pdb-formatted data using DeepRank2.
  • protein-protein interface (PPI) data (data_generation_ppi.ipynb);
  • single-residue variant (SRV) data (data_generation_srv.ipynb).
• The training tutorial will demonstrate how to train neural networks using DeepRank2.

For a smooth experience, please run these tutorials within the Jupyter notebooks provided (.ipynb files). Running the commands in a Python (interactive) shell or on command line may lead to unexpected errors.

Use cases

PPIs

The example dataset for PPIs that we provide contains 100 PDB files, each representing the structure of a Major Histocompatibility Complex (MHC) protein with a peptide in its binding pocket. This structure may or may not represent a bound state between the two molecules, forming a peptide-MHC (pMHC) complex. We are interested in predicting the binding affinity (BA) of potential pMHC complexes, which play a key role in T-cell immunity.

PDB models used in this tutorial have been generated with PANDORA, an anchor restrained modeling pipeline for generating peptide-MHC structures. While target data, (i.e., the BA values) for such pMHC complexes, have been retrieved from MHCFlurry 2.0.

On the left an example of a pMHC structure is shown, rendered using ProteinViewer. The MHC protein is displayed in green, while the peptide is in orange.

SRVs

The example SRVs dataset that we provide contains 58 PDB files, each representing protein structures containing one or multiple SRVs, which derive from alterations in the coding regions of the DNA. For each SRV, we are interested in predicting whether the phenotypic outcome is pathogenic or neutral.

PDB models and target data used in this tutorial have been retrieved from Ramakrishnan et al..

Setup

1. Follow these instructions to install the necessary package dependencies.
   • We recommend installing deeprank2 and all its dependencies into a conda environment.
2. Once the dependencies are installed, you can install the tutorials' version of the package:
   • Clone the deeprank2 repository.
   • From within the repository, run pip install ".[tutorials]"
3. To test whether the package has been succesfully installed:
   • Navigate to your deeprank2 folder.
   • Run pytest tests. All tests should pass at this point.

Running the notebooks

The tutorial notebooks can be run:

• from inside your IDE, if it has that functionality (e.g., VS Code),
• on JupyterLab by navigating to the tutorials directory in your terminal and running jupyter-lab.