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

- global search with random initial placement
- sequential fitting of multiple different structures
- symmetric fitting of copies of the same structure

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.

subtractMapsspec

Subtract the specified map (or a map generated from the specified atoms) fromref-mapbefore fitting. If atoms are specified, theresolutionfor generating the map must also be specified.

resolutionr

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 torand amplitude proportional to the atomic number; other map generation parameters are set tomolmapdefaults. If atoms are specified but this option is not given,fitting will be performed:atoms-in-mapThe 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.

metricoverlap| correlation | cam

Which metric to use forfitting:map-in-mapTheoverlap(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 vectorsuandvcontaining the fit map values and the corresponding interpolated reference map values:The other possibilities are= <overlapu,v>correlationabout zero (default during symmetric fitting) andcam(correlation about the mean):

< u,v>=correlation| u||v|where

< u–u_{ave},v–v_{ave}>=cam| u–u_{ave}||v–v_{ave}|u_{ave}is a vector with all components equal to the average of the components ofuandv_{ave}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.

envelopetrue| 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.)

shifttrue| false

Whether to allow translation of the fit structure during local optimization.

rotatetrue| false

Whether to allow rotation of the fit structure during local optimization.

moveWholeMoleculestrue| 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 (alwaystrue) when global searching is performed.

gridStepMaxmax

Initial step size, default0.5grid unit, where a grid unit is the spacing between reference map grid points. See local optimization.

maxStepsN

Maximum number of optimization steps per use of thefitmapcommand (default2000). See local optimization.

gridStepMinmin

Criterion for, when step size falls belowconvergencemingrid units (default0.01). See local optimization.

eachModeltrue |false

When multiple fit models are specified, whether to fit each model independently of the others (ignored if sequential fitting is also specified).

listFitstrue | false

Whether to show a table of the resulting fits (not yet implemented).

sequenceM

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 theeachModeloption). Only applies to map-in-map fitting; if atomic models were specified, theresolutionoption must be used to generate maps from those models.Mis 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 (defaultM=0, no sequential fitting). Thus, the fit models should be placed in trial positions beforehand by interactive manipulation and/or prior fitting runs. IfMis 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.

symmetrictrue |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, theresolutionoption 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 themetricofcorrelation(default) orcam. 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). Theenvelopesetting 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 commandsym.

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).

searchN

Number of initial placements (prior to local optimization) of the fit model within the reference map (default0, no global search). Theplacementoption can be used to constrain initial placements to only rotations or shifts from the current position.

placements | 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

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 theradiusoption. Theenvelopesetting 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 positionsr(default) - both shifts and rotationsshiftandrotate.

radiusmaxdist

Limit the global search to initial placements withinmaxdistof the current position.

clusterAngleangle

Theangle(default6°) is the rotational difference required for a fit to be considered unique.

clusterShiftshift

Theshift(default3Å) is the translational difference required for a fit to be considered unique.

asymmetricUnittrue| 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.

levelInsidefraction

Thefractionis what proportion of fit atoms or fit map grid points must lie inside the reference map contour surface for the fit to be retained (default0.1). Theenvelopesetting determines whether all nonzero-valued fit map grid points or only those above the contour level (default) are considered.

**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