This is a set of utilities intended for working with crystallographic maps.


Installation:
-------------

Go to the source directory, find the correct Makefile for your system,
and make a link from it to Makefile. So for example for linux:

ln -sf Makefile.lnx Makefile.

Now a simple 'make' should do the trick. Alternatively, you can directly
compile your stuff with: 'make -f Makefile.sys' with "sys" substituded
by the correct suffix for your operating system. If your operating system 
is not supported, please try to find out the correct compiler flags
(from one of the other makefiles) and let me now if it works. 

The MAPTOOLSRC file in this directory may be edited and 'source'd to
set the required environment variables and add the maptools to your
"PATH".

******************************************
IMPORTANT:
******************************************
set the atscat.dat link in the lib directory to the correct file
(em for Electron Microscopy, xray for Xray crystallography)



The programs:
-------------

Each of the programs, when invoked without command line arguments, will
give some usage information and will tell very briefly what it does.

Please note that when working with PDB files, the programs read the 
B-factor and occupancy columns and APPLY the read values in the 
calculations. If you don't want this (or want to apply different values),
edit the corresponding columns in your PDB files. The script "editpdb"
in the bin directory can be used for this purpose. When working at limited 
resolution, the atomic scattering functions change shape, compared to
high resolution experiments. In principle, one could adapt the atomic 
scattering parameters for the resolution at hand. However, the result would
be almost identical to increasing the B-factor(s), by e.g ~100 A^2 at 3.5 A
resolution. This is what I suggest to do. Therefore, setting the  correct 
B factors (or overall B factor) is crucial for reliable operation of these 
programs (most notably rottrans).


pdb2map:
--------

Usage: pdb2map in.map in.pdb out.map

Generates a map "out.map" based on "in.pdb", using the map parameters from 
"in.map". "in.map" has to be x-plor formatted format for now.


pdb2mask:
---------

Usage: pdb2mask atomradius in.map < in.pdb > out.mask

Generates a mask from "in.pdb" based on the map parameters from "in.map".
"in.map" has to be x-plor formatted format for now.

mapstat:
--------

Usage: mapstat in.map in.pdb

The program performs all kinds of statistics over the map:
Overall statistics and statistics over a mask built from "in.pdb"
"in.map" has to be x-plor formatted format for now.


rottrans:
---------

Usage: rottrans in.map in.mask out.scores shift scale < in.pdb 

Performs a rigid body search of "in.pdb" through the map
for the best-fitting orientations within the mask.
in.map has to be x-plor formatted map for now.
masks can be made based on .pdb files with pdb2mask.
Values for shift and scale can be obtained by running "mapstat".

NOTE: masks are mandatory. If you are very unsure about possible locations
of your fragments, then you probably should not be using this software.
For an initial mask, collect fragment positions that roughly fit the
map, and run pdb2mask with a relatively large atom radius (10 A or so).
You can later refine the results by decreasing the mask volume.

NOTE(2): the compiler directive -DDISTANCE can be used to switch scoring
functions in rottrans. Switched on, it uses a least squares
difference function between calculated and (masked) experimental map.
Switched off (default), it uses a correlation type of scoring function. 
The distance type of function seems to work better in some cases but has 
the disadvantage that it depends on the choice for "shift" and "scale" 
whereas the correlation function is not sensitive to those.


extract:
--------

Usage: extract in.map in.scores nr_of_structures < in.pdb

It reads output from "rottrans" ("in.scores") and generates corresponding
coordinate files. Please use the same "in.map" and "in.pdb" as in "rottrans".
"in.map" has to be x-plor formatted format for now.


display:
--------

Usage: display in.map inscore nscore inpdb nfiles out.map

Generates a scoremap "out.map" from output of multiple "rottrans" runs.
Well-fitting fragments will show up in the map and hopefully simplify 
interpretation. "out.map" will have the same parameters as "in.map".
"inscore" and "inpdb" are basic file names to which a number (1..nfiles) and 
suffix will be added (none and .pdb respectively).
"nscore" is the number of scores per file that will be taken into account.
"in.map" has to be x-plor formatted format for now.


Enjoy!

Bert de Groot

please send your bugs and comments to: bgroot@gwdg.de

