The fitmap command performs rigid-body local optimization(s)
to fit an atomic model or map into a map.
The maps usually represent electron density, but other types of
volume data can also be used.
Some of its features are implemented as
Fit in Map.
See also:
Fit to Segments,
volume,
molmap,
resfit,
view,
sym,
matchmaker,
align,
measure correlation,
measure rotation,
saving maps after fitting,
and ChimeraX videos:
fitting and applying
symmetry,
fitting an
AlphaFold prediction
The fit-model, a specified set of atoms or map model, will be fit to ref-model (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.
Unless global search is used,
this usually involves interactive manipulation with
mouse modes that move
only the selected model(s)
or the model that was clicked
.
See selective manipulation.
Only the current display region (which may be a cropped rectangular box) of the ref-model map is used. All of the grid points in the region are used at full resolution, regardless of what step level and threshold (contour level) are used to display the ref-model map. However, for map-in-map fitting, the fit-model map data are restricted by its step level, display region, and optionally its lowest threshold level.
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 matrix in which the first three columns 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.
The following advanced modes are mutually exclusive:
subtractMaps spec
Subtract the specified map (or a map generated from the specified atoms) from ref-model 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 | 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 (normally default true, but default false when the map has not been shown as an isosurface). If false, all nonzero-valued points in the map will be included, plus the zero-valued points if zeros is true.*For symmetric fitting, the envelope option controls which points in the reference map, rather than the fit map, are used.
zeros true | false
Whether map-in-map fitting with envelope false should include the zero-valued grid points. If envelope is true, this option is ignored.
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). The listFits option can be used to show the results in the Fit List.
listFits true | false
Whether to show results in the Fit List (default true when global searching is performed, otherwise default false).
logFits logfile
Write a space-delimited csv file of the rotation, translation and fit metrics for each fit found. The logfile is the output file pathname, enclosed in quotation marks if it includes spaces, or the word browse to specify it interactively in a file browser window. The first line in the file names the fields. Some values for the metrics can be shown as None, for example, if fitting an atomic model without specifying a resolution, the correlation will be None. The “points” field is the total number of atoms fit when fitting an atomic model, or for map-map fitting, the number of grid points of the first map (within its contour surface) being fit into the target map.
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 (such as from volume symmetry or measure symmetry), 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.
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 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 [ seed M ]
The search option specifies the 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. These N initial placements of the fit model within the reference map are generated randomly, but these depend on both the current transformation of the model relative to the scene and the seed used for randomization. If reproducibility is required, the fit model position should be reset beforehand with view initial and a consistent seed M specified in the search.
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, 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.
The Fit List (see the listFits option) enumerates unique fits from global search or from fitting multiple models independently.
Clicking a row chooses the corresponding fit and moves the fit model to regenerate it. Columns:
Buttons:
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.