Correlation-Based Docking Tutorial
This tutorial teaches new users the application of the exhaustive 6D seach and FFT-accelerated docking program colores for rigid-body docking. Colores provides options for contour-based enhancement of the fitting contrast by means of a Laplacian filter that can also be turned off if desired. The results of this tutorial can be compared to solutions distributed with the tutorial software. More documentation is available in the user guide , on the Methodology page, and in the published articles .
Content:
Download and Installation

Follow first the simple registration and download steps.

In addition to the executables, the Situs_2.3_colores_tutorial/bin directory also contains three data files:

  • 2recmon.pdb: Atomic coordinates of one of the monomers of RecA.
  • 2rec15.situs: Simulated EM map (Situs format) at 15Å resolution of RecA.
  • 2REC.pdb: For validating purposes, the atomic coordinates of the hexameric RecA.

In the following, we will use the first two files for docking. The user can compare all generated files to the files in the "solutions" directory. Here is an overfiew of the fitting scenario:
Data Flow and Design
The series of steps and the programs that are required to use colores for the docking of an atomic-resolution structure to low-resolution data are shown schematically in the following figure. Detailed program explanations are given in the Situs user guide . 

Schematic diagram of colores related routines. Major Situs components (blue) are classified by their functionality. The main data flow is indicated by brown arrows. The visualization (orange) for the rendering of the bead models requires a molecular graphics viewer (we recommend the free VMD graphics program, version 1.8.4 or higher; Chimera and Sculptor also support Situs format). 


Standard EM formats are supported and are converted to cubic lattices in Situs format. This is done with the map2map utility. Subsequently, the data is inspected and, if necessary, prepared for the fitting using a variety of visualization and analysis tools. All Situs tools require one volume and one PDB structure for the fitting. Atomic coordinates in PDB format can be transformed to low-resolution maps, if necessary, and vice versa, to allow docking of maps to maps or structures to structures. The resulting docked complex can be inspected in the graphics program. Also, if a subset of Euler angles is chosen these can be inspected after conversion into PDB format with the map2map tool.

Running colores

For this particular docking case it will be sufficient to perform a reduced angular search (sampled at 20°-> option -deg 20) to restore the original atomic structure that we used to generate the 15Å simulated EM map (target resolution 15Å -> option -res 15). After the exhaustive search is done, the best 6 on-lattice maxima (option -explor 6)  will be refined (off-lattice) using Powell optimization. Here is the command that runs this search: 

./colores 2rec15.situs 2recmon.pdb -res 15.0 -deg 20 -explor 6

When you start the program (by default as a single processor run), it will first display the user assigned and default assigned options.  Here you can check if all the input options that you requested were understood, and if you agree with the default assignment of the orther options (the user assigned options are marked in blue). For example, the program uses by default the Laplacian filter that enhances the fitting contrast, and assigns a density threshold of 0.0, i.e. only positive values will be considered:

colores> Options read:
colores> Target resolution 15.000  <== -res 15
colores> Resolution anisotropy 1.000
colores> Low-resolution map cutoff 0.000
colores> Grid size expansion factor 0.200
colores> Laplacian correlation
colores> Euler angles generation using Proportional method
colores> Angular sampling accuracy 20.000 <== -deg 20
colores> Euler angle range: [0.000:360.000] [0.000:180.000] [0.000:360.000]
colores> Number of best fits explored  6 <== -explor 6
colores> New peak search via filtering
colores> Powell maximization ON
colores> Powell tolerance 1.00E-06  Max iterations 25
colores> Powell trans & rot initial step sizes set to default values
colores> Powell correlation algorithm determined automatically
colores> Peak sharpness estimation ON
colores> Number of SMP processors requested: 1


Then the input files will be read. You can check if the map parameters, as well as the size of the atomic structure, are as expected: 

colores> Processing low-resolution map.
lib_vio> File 2rec15.situs - Header information:
lib_vio> Columns, rows, and sections: x=1-37, y=1-35, z=1-23
lib_vio> 3D coordinates of first voxel (1,1,1): (-72.000000,-68.000000,-56.000000)
lib_vio> Voxel size in Angstrom: 4.000000
lib_vio> Reading density data...
lib_vio> Volumetric data read from file 2rec15.situs
lib_vwk> Setting density values below 0.000000 to zero.
lib_vwk> Remaining occupied volume: 29785 voxels.
lib_vwk> Map size reduced from 37 x 35 x 23 to 37 x 35 x 23.
lib_vwk> New map origin (coord of (1,1,1) voxel): (-72.000,-68.000,-56.000)
lib_vwk> Map density info: max 6.104903, min 0.000000, ave 1.413333, sig 1.704802.
_____________________________________________________________________________

colores> Processing atomic structure.
lib_pio> 303 atoms read.
colores> COM: -12.369 -36.951 -9.252, radius: 40.526 Angstrom

Next, the Gaussian filter that is used for lowering the resolution of the atomic structure, and the Laplacian filter that is used to add the contour information to the fitting criterion, are generated:  
 
lib_vwk> Generating Gaussian kernel with 7^3 = 343 voxels.
lib_vwk> Generating Gaussian kernel with 11^3 = 1331 voxels.
lib_vwk> Generating Laplacian kernel with 3^3 = 27 voxels.
lib_vwk> Generating kernel with 9^3 = 729 voxels.
lib_vwk> Map size expanded from 37 x 35 x 23 to 63 x 61 x 43 by zero-padding.
lib_vwk> New map origin (coord of (1,1,1) voxel): (-124.000,-120.000,-96.000)
colores> Identifying inside or buried voxels and creating flipped mask...
colores> Found 11957 inside or buried voxels (out of a total of 165249).
colores> Identifying inside or buried voxels...
colores> Found 11957 inside or buried voxels (out of a total of 165249).
colores> Memory allocation for FFT.
colores> FFT planning...

As a test, the correlation is calculated with the probe structure centered in target density map.  In this case, since the low resolution map has a "hole" in the center, the Laplacian correlation yields negative values:

colores> Testing the maps and correlations.
colores> Projecting probe structure to lattice...
colores> Low-pass-filtering probe map...
colores> Target and probe maps:
lib_vwk> Map density info: max 6.104903, min 0.000000, ave 1.413333, sig 1.704802.
lib_vwk> Map density info: max 5.614532, min 0.000000, ave 0.890466, sig 1.404673.
colores> Projecting probe structure to lattice...
colores> Applying filters to target and probe maps...
lib_vwk> Relaxing 5 voxel thick shell about thresholded density...
colores> Normalizing target and probe maps...
colores> Target and probe maps:
lib_vwk> Map density info: max 9.376034, min -14.080725, ave 0.635900, sig 1.215082.
lib_vwk> Map density info: max 18.084443, min -33.297337, ave 1.558890, sig 2.247276.
colores> Computing correlation in direct space...
colores> Correlation with structure centered in density map:  -4.2808216E-02
colores> Computing correlation in Fourier space...
colores> FFT correlation with structure centered in density map: -4.2808216E-02

Now the uniform distribution of the Euler angles that covers the rotational search space is computed. The triplets of Euler angles are saved in the file col_eulers.dat. This file can be edited or can be used again at other times when you perform a search with idenical sampling:

colores> Getting Euler angles.
lib_eul> Proportional Euler angles distribution, total number 1908 (delta = 20.0 deg.)
colores> Total number of orientations sampled: 1908
colores> Euler angles saved in file col_eulers.dat.

Here follows the system-dependent time estimate for the 6D on-lattice search (this test was run on an AMD Athlon 1900+ Linux PC):

colores> Time of one FFT calculation: 50.663000 ms
colores> Average time spent on each rotation: 106.439800 ms
colores> Estimated time for full 6D (on-lattice) search: 0 h 3 m 23 s
colores> Off-lattice Powell optimization will take significant extra time.

Then the 6D on-lattice search is performed. During this search a progressive information about the best translational fit for each orientation is written to the file col_rotate.log. A progress bar keeps you informed:

colores> Starting 6D on-lattice search with 3D FFT scan of Euler angles.
colores> Searching using 1 processors
colores> |##################################################|   1908/1908 | 100% done
colores> Actual time spent on 6D on-lattice search: 0 h 3 m 30 s

Subsequently follows a peak search of the maximal correlation values, after which the program enters the Powell off-lattice optimization of the selected (-explor) 6 highest scoring maxima:

colores> Translation function peak detection.
colores> Peak filter contrast: maximum 0.822128, sigma 0.065242
colores> Contrast threshold: 0.130484, candidate peaks: 186
colores> Found 94 non-redundant peaks.
_____________________________________________________________________________
 
colores> Off-lattice search (Powell's optimization method).
colores> Determining fastest correlation function...
colores>    Original algorithm: Correlation = 0.01860422  Time = 19.848500 ms
colores>    Masked algorithm:   Correlation = 0.01874687  Time = 17.383500 ms
colores>    One-step algorithm: Correlation = 0.01860422  Time = 7.237000 ms
colores> Using one-step correlation function.
colores> Shown are: offset (in A) from reference center (2.000,2.000,-10.000),
colores> Euler angles (in degrees), and correlation value.
colores>
colores> Performing optimizations...
colores>
colores> Powell optimization for score maximum no.  1.
colores>   X       Y       Z       Psi     Theta   Phi      Correlation
colores>  24.000 -32.000   4.000   0.000   0.000 300.000    3.5700032E-01 Initial
colores>  23.945 -31.409   1.938  -0.439   0.000 300.000    3.9183223E-01 1
colores>  23.838 -31.155   1.928  -0.876   0.178 300.009    3.9251983E-01 2
colores>  23.877 -31.154   1.947  -0.874   0.182 300.009    3.9253416E-01 3
colores>  23.877 -31.154   1.947  -0.874   0.182 300.009    3.9253427E-01 4
colores>  23.877 -31.154   1.947 359.126   0.182 300.009    3.9253427E-01 Final
colores>
colores> Powell optimization for score maximum no.  2.
colores>   X       Y       Z       Psi     Theta   Phi      Correlation
colores> -28.000  28.000   4.000   0.000   0.000 120.000    3.5699806E-01 Initial
colores> -27.945  27.409   1.938  -0.439  -0.000 120.000    3.9182962E-01 1
colores> -27.838  27.155   1.928  -0.876  -0.178 120.009    3.9251717E-01 2
colores> -27.877  27.154   1.947  -0.874  -0.182 120.009    3.9253144E-01 3
colores> -27.877  27.154   1.947  -0.874  -0.182 120.009    3.9253155E-01 4
colores> -27.877  27.154   1.947 179.126   0.182 300.009    3.9253155E-01 Final
colores>
colores> Powell optimization for score maximum no.  3.
colores>   X       Y       Z       Psi     Theta   Phi      Correlation
colores> -16.000 -40.000   4.000   0.000   0.000   0.000    3.3733660E-01 Initial
colores> -14.241 -39.268   1.938  -0.273  -0.630  -0.054    3.9537002E-01 1
colores> -14.248 -39.132   1.869  -0.563  -0.630  -0.054    3.9578155E-01 2
colores> -14.284 -39.103   1.869  -0.681  -0.615  -0.053    3.9581916E-01 3
colores> -14.283 -39.101   1.892  -0.681  -0.612  -0.053    3.9581995E-01 4
colores> -14.284 -39.101   1.892  -0.682  -0.610  -0.053    3.9582047E-01 5
colores> -14.284 -39.098   1.893  -0.683  -0.605  -0.053    3.9582157E-01 6
colores> -14.284 -39.098   1.893 179.317   0.605 179.947    3.9582157E-01 Final
colores>
colores> Powell optimization for score maximum no.  4.
colores>   X       Y       Z       Psi     Theta   Phi      Correlation
colores>  12.000  36.000   4.000   0.000   0.000 180.000    3.3733281E-01 Initial
colores>  10.241  35.268   1.938  -0.273   0.630 179.946    3.9536920E-01 1
colores>  10.248  35.132   1.869  -0.563   0.630 179.946    3.9578099E-01 2
colores>  10.284  35.103   1.869  -0.681   0.616 179.947    3.9581863E-01 3
colores>  10.283  35.101   1.892  -0.681   0.612 179.947    3.9581946E-01 4
colores>  10.284  35.100   1.892  -0.682   0.610 179.947    3.9582005E-01 5
colores>  10.284  35.099   1.892  -0.682   0.606 179.947    3.9582097E-01 6
colores>  10.284  35.099   1.892 359.318   0.606 179.947    3.9582097E-01 Final
colores>
colores> Powell optimization for score maximum no.  5.
colores>   X       Y       Z       Psi     Theta   Phi      Correlation
colores> -40.000  -8.000   0.000   0.000   0.000  60.000    3.3684373E-01 Initial
colores> -40.091  -9.744   1.918  -0.159  -0.076  60.000    3.8226497E-01 1
colores> -40.364  -9.789   1.935  -0.159  -0.072  60.000    3.8320113E-01 2
colores> -40.366  -9.789   1.936  -0.159  -0.070  60.000    3.8320130E-01 3
colores> -40.366  -9.789   1.936 179.841   0.070 240.000    3.8320130E-01 Final
colores>
colores> Powell optimization for score maximum no.  6.
colores>   X       Y       Z       Psi     Theta   Phi      Correlation
colores>  36.000   4.000   0.000   0.000   0.000 240.000    3.3684215E-01 Initial
colores>  36.091   5.744   1.918  -0.159   0.076 240.000    3.8226413E-01 1
colores>  36.364   5.789   1.935  -0.159   0.072 240.000    3.8320035E-01 2
colores>  36.366   5.789   1.936  -0.159   0.070 240.000    3.8320050E-01 3
colores>  36.366   5.789   1.936 359.841   0.070 240.000    3.8320050E-01 Final
colores>
colores> Powell optimization time (6 runs): 41.177516 s

As we will see later, the six saved fits correspond to the symmetry-related placement of the monomer into the hexameric density. The peak sharpness is estimated for every solution (can be turned off) and the found highest scoring results are written to PDB files:
colores> Renormalizing correlation values by highest score.
colores> Writing translation function lattice to Situs file.
lib_vio> Writing density data...
lib_vio> Volumetric data written to file col_trans.sit
lib_vio> File col_trans.sit - Header information:
lib_vio> Columns, rows, and sections: x=1-63, y=1-61, z=1-43
lib_vio> 3D coordinates of first voxel (1,1,1): (-124.000000,-120.000000,-96.000000)
lib_vio> Voxel size in Angstrom: 4.000000
colores> Writing translation function lattice information to log file.
_____________________________________________________________________________
 
colores> Saving the best results.
colores> Estimating peak sharpness and writing best fit no.   1 to file col_best_001.pdb.
colores> Estimating peak sharpness and writing best fit no.   2 to file col_best_002.pdb.
colores> Estimating peak sharpness and writing best fit no.   3 to file col_best_003.pdb.
colores> Estimating peak sharpness and writing best fit no.   4 to file col_best_004.pdb.
colores> Estimating peak sharpness and writing best fit no.   5 to file col_best_005.pdb.
colores> Estimating peak sharpness and writing best fit no.   6 to file col_best_006.pdb.

Finally, in addion of the output file coordinates a number of output log files (described in the next section) are saved:

colores> Output files:
   col_best*.pdb   => best docking results in PDB format with info in header
   col_eulers.dat  => colores-readable list of Euler angles
   col_rotate.log  => Rotation function (unnormalized) log file
   col_trans.log   => Translation function (norm. by best fit) log file
   col_trans.sit   => Translation function (norm. by best fit) in Situs format
   col_powell.log  => Powell optimization log file
Inspecting the Results

In this section, we inspect how well the docked structures fit into the map. For the visualization we will use the program VMD (version 1.8.4 or higher) because it supports Situs format, but you can use other graphics programs as well.

For convenience, the following VMD commands can be pasted directly into the VMD command shell:

vmd shell commands:

mol load situs 2rec15.situs
mol load pdb col_best_001.pdb
mol load pdb col_best_002.pdb
mol load pdb col_best_003.pdb
mol load pdb col_best_004.pdb
mol load pdb col_best_005.pdb
mol load pdb col_best_006.pdb
mol top 0
rotate stop
display resetview
display projection orthographic
mol modstyle 0 0 Isosurface 1 0 0 1 2 1
mol modstyle 0 1 Trace 0.3 32
mol modstyle 0 2 Trace 0.3 32
mol modstyle 0 3 Trace 0.3 32
mol modstyle 0 4 Trace 0.3 32
mol modstyle 0 5 Trace 0.3 32
mol modstyle 0 6 Trace 0.3 32
mol modcolor 0 0 ColorID 0
mol modcolor 0 1 ColorID 3
mol modcolor 0 2 ColorID 3
mol modcolor 0 3 ColorID 3
mol modcolor 0 4 ColorID 3
mol modcolor 0 5 ColorID 3
mol modcolor 0 6 ColorID 3

Now we compare the six docked monomers with the original hexameric structure (2REC.pdb) that we used for generating the 15Å resolution map (note that we toggle off the isocontour wireframe for a better display.):
 

vmd shell commands:

mol off 0
mol load pdb 2REC.pdb
mol modstyle 0 7 Trace 0.30 32.0


In this picture you can see how the best docking results (in orange) are practically identical to the original structure (in cyan). In fact the average distance between the docked monomers and their corresponding subunits in the original structure is <<1Å rmsd. 

You can also inspect the maximal translational correlation values found in the on-lattice search (the so-called translation function) by using the map col_trans.sit. This Situs format file contains the 3D correlation values (normalized to the maximum value) as a function of translation only (the rotations have been projected out by using the optimum orientation for each voxel). 

As we did before, paste the following commands in the VMD command shell:

vmd shell commands:

mol off 1
mol off 2
mol off 3
mol off 4
mol off 5
mol off 6
mol off 7
mol on 0
mol load situs col_trans.sit
mol modstyle 0 8 Isosurface 0.4 0 0 0 1 1
mol modcolor 0 8 ColorID 4
mol top 0
rotate stop
display projection orthographic
display resetview

On the right you can see the VMD display. The higher correlational values are represented in yellow. These regions correspond roughly to the centers of mass of the six subunits that underlie the simulated map (wireframe in blue).

Alternatively, you can inspect the translation function with voledit: To make a 2D representation of a slice with an external plotting program (e.g. Sigmaplot), you can export the correlation values and grid indices of a given slice to a file.
Return to the front page .