density.grid_search() -- dock a structure into an EM (electron microscopy) density map

em_density_format = <str:1>	'XPLOR'	input density map file format for EM_GRID_SEARCH; 'MRC' | 'XPLOR'
num_structures = <int:1>	1	number of structures to dock in EM_GRID_SEARCH
em_pdb_name = <str:0>		PDB files to read for EM_GRID_SEARCH
start_type = <str:1>	'CENTER'	how to start EM_GRID_SEARCH; 'CENTER' | 'ENTIRE' | 'SPECIFIC'
translate_type = <str:1>	'NONE'	how to perform translations during EM_GRID_SEARCH; 'NONE' | 'RANDOM' | 'EXHAUSTIVE'
density_type = <str:1>	'SPHERE'	Function used to calculate density map cross-correlation in EM_GRID_SEARCH; 'SPHERE' | 'GAUSS' | 'HYBRID' | 'GAUSS_NORM' | 'TRACE'
number_of_steps = <int:1>	1	number of steps of Monte Carlo optimization
voxel_size = <float:1>	0	EM density map voxel size for EM_GRID_SEARCH
resolution = <float:1>	0	EM density map resolution for EM_GRID_SEARCH
angular_step_size = <float:1>	0	Angular search step size in degrees for EM_GRID_SEARCH
temperature = <float:1>	293.0	temperature for Monte Carlo simulation
best_docked_models = <int:1>	1	number of best docked models to keep in EM_GRID_SEARCH
em_fit_output_file = <str:1>	''	output file for EM_GRID_SEARCH

Requirements:

PDB files

Output:

'filename.log', 'filename_init_1.pdb', 'filename_init.xplor', 'filename_best.xplor', 'filename_1_num.pdb', 'bestCC_filename'

Description:

This command docks a structure of a protein/domain (probe) into a given EM density map. See original paper for the description of the method and the most recommended protocols [Topf et al., 2005].

The density map resolution and the map voxel size are given by resolution and voxel_size, respectively.

The probe is specified by the variable em_pdb_name. Before starting the protocol, the probe is positioned on the EM density grid based on the start_type variable:

• 'CENTER' will translate the center of mass of the probe to the center of mass of the grid.

• 'ENTIRE' will divide the grid into cells similar in volume to the probe, and will translate the probe to the center of each of these cells consecutively.

• 'SPECIFIC' will not perform any translation and will just use the coordinates specified by the user (the input PDB coordinates) as a starting position.

When docking the probe into the EM grid, the probe structure is converted first into probe density, by using the function indicated in the density_type variable. Each atom can be represented by one of several atomic density functions, including, the uniform sphere model ('SPHERE'), the Gaussian function ('GAUSS'), a normalized Gaussian function ('NORM'), a hybrid Gaussian/sphere model ('HYBRID'), and an interpolation to the closest point on the grid ('TRACE'). The recommended function is 'SPHERE'.

The best fit between the probe and the EM density map is obtained by changing the position of the model so as to maximize the cross-correlation between the probe density and the EM density.

The optimization of the cross-correlation score is performed by a 6D search of the probe on the EM grid, based on the variable translate_type. If 'NONE' is specified, only a rotational search over the three rotational Euler angles ($\phi$, $\theta$, $\psi$) is performed, with no translations. angular_step_size gives the maximal step size of searching for all combinations of Euler angles, which is recommended to be 30 degrees. The best fit from this coarse search is refined by a finer local search in all three Euler angles. For a protein of 150 residues this calculation typically takes less than 0.5 minutes on a 3.0 GHz Intel Xeon processor.

If translate_type is 'RANDOM', a Monte Carlo (MC) optimization is performed, and the number of MC steps has to be specified (by number_of_steps). A single MC step consists of (i) a random translation of the probe for one voxel on the EM grid, (ii) a search for the three Euler angles that maximize cross-correlation score, and (iii) an application of the Metropolis criterion [Metropolis et al., 1953]. The temperature used for the Metropolis criterion is specified in temperature (typically about 5000 units). This calculation typically takes about 1-2 minutes.

When translate_type is 'EXHAUSTIVE', a local search is performed with the probe on the grid. The optimal orientations at its original position and all 26 (i.e., 3x3x3 - 1) neighboring grid points are obtained successively by enumerating all three Euler angles. A Monte Carlo criterion is applied to each one of these 27 optimal orientations (usually with temperature lower than 5000). number_of_steps gives the number of steps for which this process is repeated (typically 25 times). When the EM density map covers only the probe model and start_type is 'CENTER', this protocol can be used for a translational and rotational refinement of the initial superposition of the centers of mass. When start_type is 'ENTIRE' this protocol will be applied for a local search only in those cells where the randomly oriented probe gives a positive cross-correlation score. The calculation typically takes about 10-15 minutes.

best_docked_models specifies how many best-fitted models should be saved by the program. This becomes more important at decreasing resolutions, as the best solution will not necessarily have the highest cross-correlation score.

Example: examples/commands/em_grid_search.py

log.verbose()
env = environ()

den = density(env, file='1cuk-a2_8A.xplor', em_density_format='XPLOR',
              em_map_size=32)

den.grid_search(em_density_format='XPLOR', num_structures=1,
                em_pdb_name='1cuk-a2.pdb', start_type='CENTER',
                density_type='SPHERE',
                number_of_steps=1, voxel_size=1., resolution=8.,
                angular_step_size=30., temperature=0.,
                best_docked_models=1, em_fit_output_file='test-cr.log')