[Chimera-users] fitting map into map

[Thomas Goddard]

Hi Gabor,

  I added a dialog to Chimera for fitting one density map in another density
map.  Here is the code

	https://www.cgl.ucsf.edu/cgi-bin/chimera-get.py?file=experimental/fitmapinmap.zip

The fitmapinmap.zip archive contains two directories FitMap and VolumeViewer
that replace those in your Chimera distribution in chimera/share.  I've
tested this code with Chimera version 1.2309 (most recent snapshot).

  Installing the above code will create a new menu entry

	Tools / Volume Data / Fit Map in Map

that shows the new dialog.  You open the two maps using Chimera menu entry
File / Open, then choose these maps in the fit map dialog and press the Fit
button.  This code does oly a local optimization so you have to position one
map at approximately the right position in the other map before you optimize.
It is very similar to the "Fit Models in Maps" tool distributed with
Chimera that fits atomic models into maps.  Use the Model Panel (menu entry
Favorites / Model Panel) to freeze (switch active button off) one map and
move the other map with the mouse.  After pressing the Fit button
the first map is rotated and shifted to increase the "overlap".
The overlap is defined as the sum over the pointwise product of the two
maps with given relative orientation.  By default the sum is carried out
over the grid points in the first map that are above the displayed contour
level.  The correlation of the two maps is the overlap divided by two
normalization factors, the squareroot of the sum of squares of map values
at the grid points for each map.  If the values of the two maps at the
grid points are represented as vectors u and v then in mathematical terms

	overlap = (u,v)
	correlation = (u,v)/|u||v|  (= cosine of angle between vectors)

where (u,v) means inner-product of vectors u,v and |u| means norm of u.
The correlation is always in the range [-1,1] while the range of overlap
values depends on the scaling of the maps.  Optimizing the overlap is not
the same as optimizing the correlation.  I may add an option in the future
to optimize correlation.

  The resulting position of one map in the other is given in the Reply Log
(menu entry Favorites / Reply Log) as a 3 by 4 matrix (3x3 rotation matrix
and the last column is a translation).  Also the size of the shift and
rotation angle is listed so you can get an idea about convergence.

  If you turn off the switch "Use only data above contour level from first
map" then the set of grid points used includes all grid points of the first
map having non-zero data values.  The contour level is ignored.  But points
with data value = 0 (probably masked out in processing the map) are not used
for the fit.

  By pressing the Correlation button (instead of the Fit) button you can
get the correlation and overlap for the current map positions without moving
either map.

  I encountered a bug in the Chimera gradient calculation code when
interpolating values near the boundary of a map.  It caused Chimera to
crash when fitting a map in an identical copy of itself.  I have fixed
this bug, but the fix is in C++ code and is not included in the above zip
archive.  I don't think you will hit this bug when fitting a map in
another map of differing size.  This fit map in map tool and the bug fix
will be in the next Chimera snapshot.

  I observed that sometimes I need to press the Fit button a second or
third time to get convergence to the best fit.  The fitting will make
at most 100 gradient descent steps, but sometimes it decides it has
converged even before then even though it is not yet at a locally optimal
solution.  The dialog does not give control over the convergence criteria
(which is the same as the Fit Models in Maps tool) although in the future
I may add access to these settings.  Set the Fit Models in Maps documentation
in the Chimera User's Guide for details on the method.

	http://www.cgl.ucsf.edu/chimera/docs/ContributedSoftware/fitmodels/fitmodels.html

Documentation for this Fit Map in Map tool is not yet available other than
this description.

  Suggestions welcome!  I'll be off for Thanksgiving until Monday.

	Tom