Package: ccmap
A Python package and C Library for fast molecular contact map computationCurrent Version 2.1.3This package was designed as a tool to quickly compute thousands of sets of atomic or residue molecular contacts. The contacts can be evaluated inside a single body or across two bodies. The library scales well, with the support of the native python multithreading.
The module also provides docking poses evaluation by the application of triplets of Euler angles and translation vectors to initial unbound conformations.Installing and using the python moduleInstallationShould be as simple aspip intstall ccmap. Alternatively you can clone this repo and runpython setup.py installat the root folder.
Current release was successfully installed through pip on the following combinations of interpreter/platforms.python3.8/OSX.10.14.6python3.8/Ubuntu LTSUsageFrom there you can load the package and display its help.importccmaphelp(ccmap)FunctionsFour functions are available:cmap: computes the contacts of one single/two body moleculelcmap: computes the contacts of a list of single/two body moleculeszmap: computes the contacts between a receptor and a ligand molecule after applying transformations to the ligand coordinateslzmap: computes many sets of contacts between a receptor and a ligand molecule, one for each applied ligand transformationParametersAll module functions take molecular object coordinates as dictionaries, where keys are atoms descriptors and values are lists.'x' : list of float x coordinates'y' : list of float x coordinates'y' : list of float x coordinates'seqRes' : list of strings'chainID' : list of one-letter string'resName' : list of strings'name' : list of stringsAdditional argumentsContact threshold distanceIn Angstrom's unit, its default value is 4.5. It can be redefined by the name parameterd.encode : BooleanIf True, contacts are returned as integers. Each integer encoding one pair of atoms/residues positions in contact with this simple formula,defK2IJ(k,sizeBody1,sizeBody2):nCol=sizeBody2ifsizeBody2elsesizeBody1returnint(k/nCol),k%nColif False, contacts are returned as strings of JSON Objectsatomic : BooleanIf True, compute contact at the atomic level. By default, this if False and the contacts are computed at the residue level.apply : BooleanIf True, the past dictionaries of coordinates will be modified according to Euler/translation parameters.
This is useful to generate single docking conformation.
This argument is only available for thecmapfunction.offsetRec and offsetLigWhen working with protein docking data, unbound conformations are often centered to the origin of the coordinates system. Specify the translation vectors for each body with theoffsetRecandoffsetLignamed arguments. Only available for thezmapandlzmapfunctions.Working with PDB coordinates filesParsing coordinate dataWe usually work with molecules in the PDB format. We can use thepyproteinsExtpackage to handle the boilerplate.importpyproteinsExtparser=PDB.Parser()pdbREC=parser.load(file="dummy_A.pdb")pdbDictREC=pdbREC.atomDictorizepdbDictREC.keys()#dict_keys(['x', 'y', 'z', 'seqRes', 'chainID', 'resName', 'name']) ```By convention, following examples will use two molecules names REC(eptor) and LIG(and).pdbLIG=parser.load(file="dummy_B.pdb")pdbDictLIG=pdbLIG.atomDictorizepdbDictLIG.keys()#dict_keys(['x', 'y', 'z', 'seqRes', 'chainID', 'resName', 'name']) ```ExamplesComputing single body contact mapComputing one mapSetting contact distance of 6.0 and recovering residue-residue contact as an integer list.ccmap.cmap(pdbDictLIG,d=6.0,encode=True)Computing many mapsUsing default contact distance and recovering atomic contact maps as JSON object string. The first positional argument specifies a list of bodies to process independently.importjsonjson.load(ccmap.lcmap([pdbDictLIG,pdbDictREC],atomic=True))Computing two-body contact mapStraight computation of one mapThe second positional argument ofcmapis optional and defines the second body.ccmap.cmap(pdbDictLIG,pdbDictLIG,d=6.0,encode=True)Straight computation of many mapsThe second positional argument oflcmapis an optional list of second bodies. The first two arguments must be of the same size, as thei-element of the first will be processed with thei-element of the second.ccmap.lcmap([pdbDictREC_1,...,pdbDictREC_n],[pdbDictLIG_1,pdbDictLIG_n],d=6.0,encode=True)Computation of one map after conformational changeUse thezmapfunction with third and fourth positional arguments respectively specifying the :Euler angles triplettranslation vectorccmap.zmap(pdbDictREC,pdbDictLIG,(e1,e2,e3),(t1,t2,t3))Transformations are always applied to the coordinates provided as a second argument, e.g. :pdbDictLIG.Computation of many maps after conformational changesUse thelzmapfunction, arguments are similar but for the Euler angles and translation vectors which must be supplied as lists.ccmap.lzmap(pdbDictREC,pdbDictLIG,[(e1,e2,e3),],[(t1,t2,t3),])Generating docking conformationsThe conformations obtained by coordinate transformation can be back mapped to PDB files.
Here, offset vectors[u1, u2, u3]and[v1, v2, v3]respectively centerpdbDictRECandpdbDictLIGand one transformation defined by the[e1, e2, e3]Euler's angles and the[t1, t2, t3]translation vector is applied topdbDictLIG. The resulting two-body conformation is finallyappliedto the providedpdbDictRECandpdbDictLIG. These updated coordinates update the original PDB object for later writing to file.# Perform computation & alter provided dictionariesccmap.zmap(pdbDictREC,pdbDictLIG,\[e1,e2,e3],[t1,t2,t3],\offsetRec=[u1,u2,u3],\offsetLig=[v1,v2,v3],\apply=True)# Update PDB containers from previous examplespdbREC.setCoordinateFromDictorize(pdbDictREC)pdbLIG.setCoordinateFromDictorize(pdbDictLIG)# Dump to coordinate fileswithopen("new_receptor.pdb","w")asfp:fp.write(str(pdbREC))withopen("new_ligand.pdb","w")asfp:fp.write(str(pdbLIG))MultithreadingThe C implementation makes it possible for the ccmap functions to release Python Global Interpreter Lock. Hence, "actual" multithreading can be achieved and performances scale decently with the number of workers. For this benchmark, up to 50000 docking poses were generated and processed for three coordinate sets of increasing number of atoms: 1974(1GL1) 3424(1F34) 10677(2VIS).A simple example of a multithread implementation can be found in the providedscript. Thetestsfolder allows for the reproduction of the above benchmark.Installing and using the C LibraryC executable can be generated with the provided makefile. The low-level functions are the same, but the following limitations exist:One computation per executable callNo multithreading.Finding the optimal molecular path connecting two atomsUsing a thiner mesh size, it is possible to obtain the shortest path connecting two atoms.
The atoms to connect must be solvent accessible and path search will operate over the surface and solvant accessible cells. The solvent excluded volume is computed for each atom as the sum of of its Van Der Waals radius and the radius of water molecule.installgitclone-bfibonaccigit@github.com:MMSB-MOBI/ccmap.gitcdccmap/ccmapmakepathfinderUsage./bin/linky -i ../tests/structures/gil_input.pdb  -x 'LI1:B:502:CA' -y 'LI2:C:502:CA' -s 1will display:ApplyingH20proberadiusof1.4A.toatomicsolvantvolumeexclusion
Useratomselection:Startatom:" CA  LI1  502 B 14.024000 15.909000 -5.891000"Endatom:" CA  LI2  502 C 8.770000 25.230000 -5.380000"Mesh[459x408x316]created:3959cellscontainatoms
Buildingsurfacesw/meshunitof0.2A....Totalof12749100voxelsconstructed
Searchingforstart/stopcellsatstart/stopatomssurfaces...start/stopsurfacescontain391/1058voxels,pickingclosesttotheothervolumecentercell...
Startingfromcell(240,281,134)(b=0)Tryingtoreachcell(230,307,139)(b=0)---Bestwalkismadeof47moves---
Theoriticaldistancefrom1stvox_pathtostartatomvoxel[240281134]11.018,16.813,-6.889atom:CALI1502B14.02400015.909000-5.891000d=3.29382A.
Start/Stopatomsexclusionradius:3.2/3.2A.
Bestpathway--aprox.polylinelengths15.8A
Trailingspaceequals0.2A
Threadingof7atomsw/1Aspacingcompleted
Approximatelinkerlength12.6A.Where last line is fair approximation of the shortest curve linking desired atoms.Effect of parameters on searchThe path is guaranteed to be optimal but may take some time to run depending on structure topology and command line parameters.cell sizeToo large value may lead irrealistic path. Smaller values are better but increase path search space and therefore the computation time.water probeWater probe radius affect the solvant volume and therefore the pathbead spacingDoesn't affect the optimal path, but will affect the evaluation of the linker length.