The command fitmap fits atomic coordinates into a density map or one density map into another. It is the command-line implementation of Fit in Map, but it also has options that are not available in that tool:
The fit-structure, either specified atoms or a map model, will be fit to ref-map (a map model). Map models are specified by model number preceded by #. 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 and toggling models between active and immovable states. However, the fitmap command also has global search options that are not available in the Fit in Map graphical interface.
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. The Fit in Map graphical interface can be used to undo the fit. After fitting, atomic coordinates can be saved relative to the reference map.
Information such as the number of optimization steps, shift, and rotation is sent to the Reply Log. If the entire fit model is repositioned, its transformation 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.
See also: volume, measure, molmap, sym, SegFit, Values at Atom Positions, saving maps after fitting
Option keywords for fitmap can be truncated to unique strings, and their case does not matter. Synonyms for true: True, 1. Synonyms for false: False, 0. A vertical bar “|” designates mutually exclusive options, and default settings are indicated with bold.
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 | 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.
<u–uave,v–vave> cam = |u–uave||v–vave|
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 in Volume Viewer. 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 algorithm.
maxSteps N
Maximum number of optimization steps per use of the fitmap command (default 2000). See local optimization algorithm.
gridStepMin min
Criterion for convergence, when step size falls below min grid units (default 0.01). See local optimization algorithm.
eachModel true | false
When multiple fit models are specified, whether to fit each model independently of the others (cannot be combined with sequential fitting). The listFits option can be used to show the results in the Fit List dialog.
listFits true | false
Whether to show results in the Fit List dialog (default true when global searching is performed, otherwise default false).
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. See also: sequential fitting video tutorial (Web)
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. See also: symmetric fitting video tutorial (Web)
| Click for video tutorial on fitmap global search (Web)... |
|
|
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. The resulting unique fits are listed in a separate dialog, the Fit List, 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.
- s - random shifts (translations) starting from the current position, keeping the geometric center of the fit atoms or fit map grid points within the bounding box of the displayed part of the reference map. The search radius can be restricted further with the radius option. The envelope setting determines whether all nonzero-valued fit map grid points or only those above the contour level (default) are used to calculate the center.
- r - random rotations starting from the current position
- sr (default) - both shifts and rotations
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. Only unique fits are included in the list of results.
clusterShift shift
The shift (default 3 Å) is the translational difference required for a fit to be considered unique. Only unique fits are included in the list of results.
asymmetricUnit true | false
If the reference map has symmetry information (such as from measure symmetry), whether to list 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 included in the list of results.
inside 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.
Unique fits from running the fitmap command with global search are enumerated in a Fit List dialog. The listFits option can be used to show the results of other fitmap runs as well (for example, fitting multiple models independently with the eachModel option).
Clicking a row chooses the corresponding fit and moves the fit model to regenerate it. The Fit List is included in saved sessions. Columns:
on the right
hides them again):