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**,
**save** PDB,
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 .

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:

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

subtractMapsspec

Subtract the specified map (or a map generated from the specified atoms) fromref-modelbefore 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 (normally defaulttrue, but defaultfalsewhen the map has not been shown as an isosurface). Iffalse, all nonzero-valued points in the map will be included, plus the zero-valued points ifzerosistrue.*For symmetric fitting, the

envelopeoption controls which points in the reference map, rather than the fit map, are used.

zerostrue |false

Whether map-in-map fitting withenvelopefalseshould include the zero-valued grid points. Ifenvelopeistrue, this option is ignored.

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). ThelistFitsoption can be used to show the results in theFit List.

listFitstrue | false

Whether to show results in theFit List(defaulttruewhen global searching is performed, otherwise defaultfalse).

logFitslogfile

Write a space-delimited csv file of the rotation, translation and fit metrics for each fit found. Thelogfileis the output file pathname, enclosed in quotation marks if it includes spaces, or the wordbrowseto 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.

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 (such as fromvolume symmetryormeasure symmetry), 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.
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).

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. Only unique fits are included in the list of results.

clusterShiftshift

Theshift(default3Å) is the translational difference required for a fit to be considered unique. Only unique fits are included in the list of results.

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.

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:

**Corr**– map-in-map fitting metric: correlation about zero**Ave**– atoms-in-map fitting metric: average map value at fit atom positions**Inside**– what proportion of fit atoms (atoms-in-map fitting) or fit map grid points (map-in-map fitting) are inside the reference map contour surface. The**envelope**setting determines whether all nonzero-valued fit map grid points or only those above the contour level (default) are considered.**Molecule**– fit model**Map**– reference model**Hits**– number of fits in the uniqueness cluster

Buttons:

**Place Copy**– if atoms were specified as the fit structure, open a copy for each chosen fit as a new model**Save PDB**– if atoms were specified as the fit structure, save each chosen fit as a PDB file**Delete**– remove each chosen fit from the list**Clear List**– remove all fits

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

UCSF Resource for Biocomputing, Visualization, and Informatics / October 2022