ChimeraX docs icon

Command: fitmap

Usage:
fitmap  fit-structure  inMap  ref-map   options   global-search-options

The fitmap command performs rigid-body local optimization(s) to fit an atomic model or map into a map. Mutually exclusive modes:

The maps usually represent electron density, but other types of volume data can also be used. See also: volume, molmap, view, sym, matchmaker, align, save PDB, Density Map Toolbar

The fit-structure, a specified set of atoms or map model, will be fit to ref-map (a map model). If atoms are specified, only those atoms will be used in the fitting calculation, but the entire model(s) containing them will be repositioned unless moveWholeMolecules is set to false.

Prior to local optimization, the fit model should be placed in a trial position relative to the reference map before fitting. This usually involves interactive manipulation unless global search is used.

The calculation will stop and the fit structure will be repositioned after convergence or a maximum number of steps (default 2000), whichever comes first. Reissuing the fitmap command may further improve results, especially if convergence was not reached.

Information such as the number of optimization steps, shift, and rotation is sent to the Log. The transformation of the fit structure relative to the reference map is given as a transformation matrix and as an axis of rotation (a unit vector), point on the axis, degrees of rotation, and shift parallel to the axis.

Options

subtractMaps  spec
Subtract the specified map (or a map generated from the specified atoms) from ref-map before fitting. If atoms are specified, the resolution for generating the map must also be specified.
resolution  r
Generate a density map from the coordinates of the specified atoms and perform map-in-map fitting instead of atoms-in-map fitting. Both types of fit values will still be reported. The map is generated by describing each atom as a Gaussian distribution of width proportional to r and amplitude proportional to the atomic number; other map generation parameters are set to molmap defaults. If atoms are specified but this option is not given, atoms-in-map fitting will be performed:
The average map value at fit atom positions is maximized. For each atom within the bounds of the reference map, the map value is found by trilinear interpolation from the eight corners of the enclosing data grid cell. Atoms outside the bounds of the map are not used for computing averages.
metric  overlap | correlation | cam
Which metric to use for map-in-map fitting:
The overlap (default except during symmetric fitting) is the sum over fit map grid points of the product of the fit map value and the reference map value at that point, determined by trilinear interpolation. It can be expressed as the inner product of vectors u and v containing the fit map values and the corresponding interpolated reference map values:
overlap = <u,v>
The other possibilities are correlation about zero (default during symmetric fitting) and cam (correlation about the mean):
<u,v>
correlation =  
u || v |
<uuave,vvave>
cam =  
|uuave||vvave|
where uave is a vector with all components equal to the average of the components of u and vave is defined analogously. The correlation equals the cosine of the angle between the vectors (after subtraction of averages) and can range from –1 to 1, whereas the range of overlap values depends on the scaling of the maps.
envelope  true | false
For map-in-map fitting, whether to use only the grid points in the fit map with values above the map's lowest contour level. Otherwise, all nonzero-valued fit map grid points will be included. (Exception: for symmetric fitting, this option controls which reference map points, rather than fit map points, are used.)
shift  true | false
Whether to allow translation of the fit structure during local optimization.
rotate  true | false
Whether to allow rotation of the fit structure during local optimization.
moveWholeMolecules  true | false
Whether to reposition the entire model(s) containing the specified atoms. If false, only the specified atoms will be moved. Regardless of this setting, only the specified atoms will be used to calculate the fit. This option is ignored (always true) when global searching is performed.
gridStepMax  max
Initial step size, default 0.5 grid unit, where a grid unit is the spacing between reference map grid points. See local optimization.
maxSteps  N
Maximum number of optimization steps per use of the fitmap command (default 2000). See local optimization.
gridStepMin  min
Criterion for convergence, when step size falls below min grid units (default 0.01). See local optimization.
eachModel  true | false
When multiple fit models are specified, whether to fit each model independently of the others (ignored if sequential fitting is also specified).
listFits  true | false
Whether to show a table of the resulting fits (not yet implemented).
sequence M
When multiple fit models are specified, whether to fit each model in turn after subtracting the density corresponding to the other models (cannot be combined with the eachModel option). Only applies to map-in-map fitting; if atomic models were specified, the resolution option must be used to generate maps from those models. M is the number of individual structure fits to perform, each time first subtracting (temporarily) from the reference map the density corresponding to the other specified fit models in their current positions (default M = 0, no sequential fitting). Thus, the fit models should be placed in trial positions beforehand by interactive manipulation and/or prior fitting runs. If M is greater than the number of fit models, the calculation will continue to cycle through those models in the order listed. In tests, good convergence was attained by cycling through all of the models five times. Currently sequential fitting cannot be done in the same command as symmetric fitting or global search.
symmetric  true | false
Whether to use the symmetry of the reference map while fitting. Only applies when the reference map has a symmetry assignment, and to map-in-map fitting; if atoms were specified, the resolution option must be used to generate a map from those atoms. During symmetric fitting, the fit map and its symmetry-related virtual copies are fit into the reference map using the metric of correlation (default) or cam. Overlaps between fit map copies additively raise the fit density and tend to lower the correlation. For computational efficiency, only one asymmetric unit of the reference map is considered explicitly (reference map grid points closer to the center of the original fit map than to the centers of its copies). The envelope setting determines whether all nonzero-valued reference map grid points in the asymmetric unit or only those above the contour level (default) are used. Currently symmetric fitting cannot be done in the same command as sequential fitting or global search. Whereas symmetric fitting uses virtual copies of the fit map, symmetry-related actual copies of the corresponding atomic model can be created with the command sym.

Global Search Options

A search value N > 0 indicates some degree of global searching with the fitmap command. In global search, N initial placements of the fit model within the reference map are generated randomly, then subjected to local optimization. The whole model will be moved regardless of the moveWholeMolecules setting. Only unique fits are retained, where uniqueness depends on rotational differences, translational differences, and lack of equivalence by symmetry. In addition, the user can require some fraction of the fit atoms or fit map grid points to be inside the reference map contour surface for the fit to be retained. Only the first fit in a uniqueness cluster is listed, along with the number of cluster members (hits).

search  N
Number of initial placements (prior to local optimization) of the fit model within the reference map (default 0, no global search). The placement option can be used to constrain initial placements to only rotations or shifts from the current position.
placement  s | r | sr
In global search, how to generate initial placements of the fit model: This option does not affect what movements are allowed during local optimization, which are instead set by shift and rotate.
radius  maxdist
Limit the global search to initial placements within maxdist of the current position.
clusterAngle  angle
The angle (default 6°) is the rotational difference required for a fit to be considered unique.
clusterShift  shift
The shift (default 3 Å) is the translational difference required for a fit to be considered unique.
asymmetricUnit  true | false
If the reference map has symmetry information, whether to keep only the fits from one asymmetric unit. In other words, whether to exclude symmetry-equivalent fits from being considered unique. Of a symmetry-equivalent set of fits, the one that places the fit structure geometric center closest to volume box fractional coordinates (0.75,0.55,0.55) in the reference map is kept as the representative.
levelInside  fraction
The fraction is what proportion of fit atoms or fit map grid points must lie inside the reference map contour surface for the fit to be retained (default 0.1). The envelope setting determines whether all nonzero-valued fit map grid points or only those above the contour level (default) are considered.

Notes

Local optimization algorithm. If rotation and translation are both allowed, every even step is a translation and every odd step is a rotation. The center of rotation is the geometric center of the fit atoms or fit map grid points, whichever applies. Optimization is by steepest ascent. Map value gradients at atom positions or fit map points are calculated using trilinear interpolation of the gradients at the reference map points. Gradients at grid points are calculated by the center difference method. Atoms or fit map points outside the reference map or within one voxel of the edge of the data at a given step do not contribute to the optimal direction at that step. The initial step size is the largest (default 0.5 grid unit, where a grid unit is the spacing between reference map grid points). If after four steps the maximum cumulative displacement is less than half the displacement achievable if all steps were in the same direction (e.g., half of 2.0 grid units = 1 grid unit), the step size is halved. Successive rounds of four steps with fixed step size and halving the step size based on the maximum displacement criterion are repeated until convergence or a maximum number of steps (default 2000), whichever comes first.

Transformation matrices. The transformation matrix of the fit model relative to the reference map is reported in the Log. The first three columns of the matrix describe a rotation and the fourth describes a translation (performed after the rotation). The transformation is also described as an axis of rotation (a unit vector), point on the axis, degrees of rotation, and shift parallel to the axis.


UCSF Resource for Biocomputing, Visualization, and Informatics / July 2017