Package: deeprank
DeepRankContentsOverviewInstallationQuick TutorialDocumentationLicenseIssues & ContributingOverviewDeepRank is a general, configurable deep learning framework for data mining protein-protein interactions (PPIs) using 3D convolutional neural networks (CNNs).DeepRank contains useful APIs for pre-processing PPIs data, computing features and targets, as well as training and testing CNN models.Features:Predefined atom-level and residue-level PPI feature typese.g. atomic density, vdw energy, residue contacts, PSSM, etc.Predefined target typese.g. binary class, CAPRI categories, DockQ, RMSD, FNAT, etc.Flexible definition of both new features and targets3D grid feature mappingEfficient data storage in HDF5 formatSupport both classification and regression (based on PyTorch)InstallationDeepRank requires a Python version 3.7 or 3.8 on Linux and MacOS.Stable ReleaseDeepRank is available in stable releases onPyPI:Install the modulepip install deeprankDevelopment VersionYou can also install the under development source code from the branchdevelopmentClone the repositorygit clone --branch development https://github.com/DeepRank/deeprank.gitGo therecd deeprankInstall the packagepip install -e ./To check if installation is successful, you can run a testGo into the test directorycd testRun the test suitepytestTutorialWe give here the tutorial like introduction to the DeepRank machinery. More informatoin can be found in the documentationhttp://deeprank.readthedocs.io/en/latest/.  We quickly illsutrate here the two main steps of Deeprank:the generation of the datarunning deep leaning experiments.A . Generate the data set (using MPI)The generation of the data require only require PDBs files of decoys and their native and the PSSM if needed. All the features/targets and mapped features onto grid points will be auomatically calculated and store in a HDF5 file.fromdeeprank.generateimport*frommpi4pyimportMPIcomm=MPI.COMM_WORLD# let's put this sample script in the test folder, so the working path will be deeprank/test/# name of the hdf5 to generateh5file='./hdf5/1ak4.hdf5'# for each hdf5 file where to find the pdbspdb_source=['./1AK4/decoys/']# where to find the native conformations# pdb_native is only used to calculate i-RMSD, dockQ and so on.# The native pdb files will not be saved in the hdf5 filepdb_native=['./1AK4/native/']# where to find the pssmpssm_source='./1AK4/pssm_new/'# initialize the databasedatabase=DataGenerator(chain1='C',chain2='D',pdb_source=pdb_source,pdb_native=pdb_native,pssm_source=pssm_source,data_augmentation=0,compute_targets=['deeprank.targets.dockQ','deeprank.targets.binary_class'],compute_features=['deeprank.features.AtomicFeature','deeprank.features.FullPSSM','deeprank.features.PSSM_IC','deeprank.features.BSA','deeprank.features.ResidueDensity'],hdf5=h5file,mpi_comm=comm)# create the database# compute features/targets for all complexesdatabase.create_database(prog_bar=True)# define the 3D gridgrid_info={'number_of_points':[30,30,30],'resolution':[1.,1.,1.],'atomic_densities':{'C':1.7,'N':1.55,'O':1.52,'S':1.8},}# Map the featuresdatabase.map_features(grid_info,try_sparse=True,time=False,prog_bar=True)This script can be exectuted using for example 4 MPI processes with the command:NP=4
    mpiexec -n $NP python generate.pyIn  the first part of the script we define the path where to find the PDBs of the decoys and natives that we want to have in the dataset. All the .pdb files present inpdb_sourcewill be used in the dataset. We need to specify where to find the native conformations to be able to compute RMSD and the dockQ score. For each pdb file detected inpdb_source, the code will try to find a native conformation inpdb_native.We then initialize theDataGeneratorobject. This object (defined indeeprank/generate/DataGenerator.py) needs a few input parameters:pdb_source: where to find the pdb to include in the datasetpdb_native: where to find the corresponding native conformationscompute_targets: list of modules used to compute the targetscompute_features: list of modules used to compute the featureshdf5: Name of the HDF5 file to store the data setWe then create the data base with the commanddatabase.create_database(). This function autmatically create an HDF5 files where each pdb has its own group. In each group we can find the pdb of the complex and its native form, the calculated features and the calculated targets. We can now mapped the features to a grid. This is done via the commanddatabase.map_features(). As you can see this method requires a dictionary as input. The dictionary contains the instruction to map the data.number_of_points: the number of points in each directionresolution: the resolution in Angsatomic_densities: {'atom_name': vvdw_radius} the atomic densities requiredThe atomic densities are mapped following theprotein-ligand paper. The other features are mapped to the grid points using a Gaussian function (other modes are possible but somehow hard coded)Visualization of the mapped featuresTo explore the HDf5 file and vizualize the features you can use the dedicated browserhttps://github.com/DeepRank/DeepXplorer. This tool saloows to dig through the hdf5 file and to directly generate the files required to vizualie the features in VMD or PyMol. An iPython comsole is also embedded to analyze the feature values, plot them etc ....B . Deep LearningThe HDF5 files generated above can be used as input for deep learning experiments. You can take a look at the filetest/test_learn.pyfor some examples. We give here a quick overview of the process.fromdeeprank.learnimport*fromdeeprank.learn.model3dimportcnn_regimporttorch.optimasoptimimportnumpyasnp# input databasedatabase='1ak4.hdf5'# output directoryout='./my_DL_test/'# declare the dataset instancedata_set=DataSet(database,chain1='C',chain2='D',grid_info={'number_of_points':(10,10,10),'resolution':(3,3,3)},select_feature={'AtomicDensities':{'C':1.7,'N':1.55,'O':1.52,'S':1.8},'Features':['coulomb','vdwaals','charge','PSSM_*']},select_target='DOCKQ',normalize_features=True,normalize_targets=True,pair_chain_feature=np.add,dict_filter={'DOCKQ':'<1'})# create the networkmodel=NeuralNet(data_set,cnn_reg,model_type='3d',task='reg',cuda=False,plot=True,outdir=out)# change the optimizer (optional)model.optimizer=optim.SGD(model.net.parameters(),lr=0.001,momentum=0.9,weight_decay=0.005)# start the trainingmodel.train(nepoch=50,divide_trainset=0.8,train_batch_size=5,num_workers=0)In the first part of the script we create a Torch database from the HDF5 file. We can specify one or several HDF5 files and even select some conformations using thedict_filterargument. Other options ofDataSetcan be used to specify the features/targets the normalization, etc ...We then create aNeuralNetinstance that takes the dataset as input argument. Several options are available to specify the task to do, the GPU use, etc ... We then have simply to train the model. Simple !Issues and ContributingIf you have questions or find a bug, please report the issue in theGithub issue channel.If you want to change or further develop DeepRank code, please check theDeveloper Guidelineto see how to conduct further development.