Program : MAMA
Version : 990301
Author : Gerard J. Kleywegt & T. Alwyn Jones,
Dept. of Cell and Molecular Biology,
Uppsala University, Biomedical Centre, Box 590,
SE-751 24 Uppsala, SWEDEN
E-mail : gerard@xray.bmc.uu.se
Purpose : manipulation and improvement of O/RAVE-style masks
(molecular envelopes)
Package : RAVE
Reference(s) for this program:
* 1 * T.A. Jones (1992). A, yaap, asap, @#*? A set of averaging programs. In "Molecular Replacement", edited by E.J. Dodson, S. Gover and W. Wolf. SERC Daresbury Laboratory, Warrington, pp. 91-105.
* 2 * G.J. Kleywegt & T.A. Jones (1993). Masks Made Easy. CCP4/ESF-EACBM Newsletter on Protein Crystallography 28, May 1993, pp. 56-59. [http://alpha2.bmc.uu.se/usf/factory_1.html]
* 3 * G.J. Kleywegt & T.A. Jones (1994). Halloween ... Masks and Bones. In "From First Map to Final Model", edited by S. Bailey, R. Hubbard and D. Waller. SERC Daresbury Laboratory, Warrington, pp. 59-66.
* 4 * G.J. Kleywegt & R.J. Read (1997). Not your average density. Structure 5, 1557-1569. [http://www4.ncbi.nlm.nih.gov/htbin-post/Entrez/query?uid=9438862&form=6&db=m&Dopt=r]
* 5 * G.J. Kleywegt & T.A. Jones (2037 ?). Convenient single and multiple crystal real-space averaging. To be published ???
* 6 * G.J. Kleywegt & T.A. Jones (1998 ?). Software for handling macromolecular envelopes. To be published.
* 7 * G.J. Kleywegt (1998 ?). Local density correlation and ... To be published.
* 8 * G.J. Kleywegt & T.A. Jones (1999 ?). Chapter 25.2.6. O and associated programs. Int. Tables for Crystallography, Volume F. To be published.
930224 - 0.1 - initial version; max 8 masks of 1 MegaWord each;
reasonably well debugged, but no visual tests
done yet !!!
930226 - 0.2 - doubled max size of masks to 2 MegaWord;
implemented CPU-timing;
new options DUPLICATE, NOT, NBR_COUNT, UNITE,
NEW ?, NEW ORIGIN, NEW EXTENT, NEW GRID,
NEW CELL, NEW MAKE, NEW RT_OPERATOR, NEW RADIUS,
NEW PDB, NEW BONES (not tested), NEW COPY,
NEW SAME, NEW FACTOR;
did visual checks (looks good, especially when
using semi-transparent surfaces in "O" !!!)
930301 - 0.3 - added option NEW PAD; print delta-CPU-time only
if it exceeds 1.0 seconds; calculate smoothness
in NBR_COUNT; give more info in LIST; NEW_MASK
format; error traps in mask i/o routines;
COMPRESSED_MASK format; use argument for LIST
930302 - 1.0 - first production version; manual up-to-date;
NEW SPACING option
930309 - 1.1 - increased mask size to 4 MegaWord; implemented
OVERLAP ?, OVERLAP ORIGIN, OVERLAP EXTENT,
OVERLAP SYMM_OP, OVERLAP NCS_RT, OVERLAP RESET_NCS;
implemented OVERLAP TRIM; removed options
OVERLAP ORIGIN and EXTENT again since they are
not needed (YET !); implemented OVERLAP ERASE;
none of these documented yet !
930310 - 1.2 - tried to program general overlap case (> 2 NCS);
re-implemented OVERLAP ORIGIN and EXTENT;
implemented SIMILARITY, ODL, BORDER_CHECK,
ATOM_FIT, EZD, OVERLAP EZD, ISLAND_ERASE
930311 - 1.3 - debugged INTRPL (also in ES_AVERAGE); removed
some other bugs; implemented on DEC ALPHA (4 to 8
times faster than VGX or Indigo); cleaned up the
code a bit; worked example for the manual
930312 - 1.4 - tried to program NEW UNIT_CELL (seems to work okay);
included use of RT-operator here; implemented
NEW RESET_RT_OPERATOR; introduced cutoff factor
in OVERLAP TRIM and ERASE plus the option to
produce an EZD file with these commands as well
930313 - 2.0 - updated manual completely; added LABEL option
930315 - 2.1 - corrected manual; include various volumes in LIST
option; NEW UNIT_CELL now does its utmost to keep
the VOLUME of the actual mask as constant as
possible !
930416 - 2.2 - minor bug fixes; implemented MACRO facility;
made index for manual
930507 - 2.3 - bug fixes in NEW BONES; new option NEW OLDBONES
for BONES files without radii
930510 - 2.4 - new option NEW BALL (spherical mask)
930602 - 2.5 - added more hints to manual; print solvent content
in overlap calculations; made smaller version for
ESVs (only 4 masks in memory); print program
dimensioning with "?" option; NEW CUBE option;
OVERLAP ASU option
930608 - 2.6 - added $ option to issue shell commands
930614 - 2.7 - debugged handling of "O" datablock files
930616 - 3.0 - new production version; new format types (see 2.59);
made definition of asymm. unit for OVERLAP options
more liberal (see 2.51)
930624 - 3.1 - new overlap algorithm (set with OV MODE; see 2.49.i);
new option TRanslate (see 2.18.i); minor bug fixes;
increased some counter arrays (for the virus
people)
931119 - 3.2 - cleaned up (for) manual; drastically shortened
941223 - 3.3 - COMpressed mark format now default for WRite
950207 -3.3.1- removed minor bug in LIst command
950711 - 3.4 - new BLob_erase and DOt_odl options
951022 - 3.5 - made sensitive to OSYM
951030 - 3.6 - enable reading of many NCS operators from one file
for the OVerlap NCs command
951106 - 3.7 - removed long-standing bug from NEw UNitcell command
(in figuring out fractional mask bottom and top)
960415 -3.7.1- minor bug fixes
960425 -3.7.2- increase max number of atoms in PDB file to 100,000
960517 - 3.8 - implemented simple symbol mechanism
960629 -3.8.1- default mask output format changed to OMASK
961126 - 4.0 - implemented dynamic memory allocation
970626 - 4.1 - support initialisation macro (setenv GKMAMA macrofile)
970627 - 4.2 - changed ATom_fit command to include HETATMs, and to
optionally produce two new PDB files, one with all
atoms inside the mask, and one with those outside;
made the ouput of the OVerlap TRim command a bit
clearer when it checks to see if you specified an
asymmetric unit plus 1, 2 or 3 points on all sides
970722 - 5.0 - implemented VRML commands
970724 -5.0.1- added VRml CEll and VRml BOx
970922 -5.0.2- fixed a little bug so that the NEw BAll command now
actually generates a sphere rather than a cube ;-)
971204 - 5.1 - debugged NEw UNit_cell command; better error checks
for NEw COpy command
970409 -5.1.1- added NEw ENcompass command
970714 - 5.2 - added new OVerlap UNit_cell command
980901 - 5.3 - NEw BOnes will now check if reasonable atomic radii
are used (if not, probably the NEw OLd_bones command
should have been used instead of the NEw BOnes command);
new INvert_ncs command to invert O-style operators
(Cartesian space only !)
980929 - 5.4 - new ZP_restart command to re-start the program with
different memory allocation
981021 -5.4.1- new ECho command to echo command-line input (useful
in scripts)
981022 - 5.5 - implemented command history (# command)
990301 - 5.6 - the SMooth, CUt, EXpand and COntract commands now have
as an extra (optional; default = 1) parameter the number
of times the operation should be carried out. So instead
of issuing the "expand m1" command five times, you can
use "expa m1 5". Also sped up the ISland_erase command
(typically, by a factor of 5-10).
From version 4.1 on, MAMA can execute a macro at start-up (whether it is run interactively or in batch mode). This can be used to execute commands which you (almost) always want to have executed. To use this feature, set the environment variable GKMAMA to point to a MAMA macro file, e.g.:
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- setenv GKMAMA /home/gerard/mama.init ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
From version 4.0 onward, MAMA allocates memory for masks dynamically. This means that you can increase the size and number of masks that the program can handle on the fly:
1 - through the environment variables MASKSIZE and NUMMASKS (must be in capital letters !), for example put the following in your .cshrc file:
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- setenv MASKSIZE 5000000 setenv NUMMASKS 4 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
2 - by using command-line arguments MASKSIZE and NUMMASKS (need not be in capitals), for example:
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- run mama masksize 20000000 nummasks 1 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
Note that command-line arguments take precedence over environment variables. So you can set the environment variables in your .cshrc file to "typical" values, and if you have to deal with a mask which is bigger than that, you can use the command-line argument(s).
From version 5.4 on, you can also use ZP_restart from within the program itself to increase memory allocation. WARNING : all memory is reset, so any unsaved data will be lost !!!
If sufficient memory cannot be allocated, the program will print a message and quit. In that case, increase the amount of virtual memory (this will not help, of course, if you try to allocate more memory than can be addressed by your machine (for 32-bit machines, something 2**32-1 bytes, I think), or reduce the size requirements.
MAMA needs space for NUMMASKS + 2 masks.
If you're tired of editing masks, don't call for your mother, but use MAMA ! MAMA is to masks what MOLEMAN is to PDB files.
With MAMA you can fill the voids that PDB_MASK and BONES_MASK leave in your masks, you can slightly extend your mask when you are putting in side chains in your poly-Ala search model or when X-PLOR has moved them around for you, you can take away parts of the mask which overlap with a neighbour molecule, etc. etc.
In addition, MAMA contains all the functionality of Alwyn's programs PDB_MASK, BONES_MASK, and MASK_NEW_GRID as well as options to remove overlap due to (NCS-) symmetry and to copy a mask from one space group to another.
The overlap tools can also be used to investigate close contacts between various molecules in the asymmetric unit due to (non-) crystallographic symmetry.
As a bonus, you are able to emulate Delaney's cavity-finding program (using "cellular logic methods"; see the example below).
MAMA allows you to work with upto EIGHT masks simultaneously ! You may either manipulate one mask or combine two of them. The wild-card character "*" can be used for most single-mask options if you want to carry out an operation for all masks in memory.
When you read a mask, you give it a name by which you can refer to it later. All names are converted to uppercase, so "m1" and "M1" are the same masks ! MAMA checks that you don't use duplicate mask names.
MAMA is command-driven; the first TWO letters of each command are unique (so you don't have to type the rest); the commands are automatically converted to uppercase, so no worries there either.
Parameters to commands may be supplied on the same line as the command itself. MAMA will prompt you for the values of any parameters that were not supplied in this way.
MAMA runs in interactive mode by default. This means that if
(a) an input file can not be opened, MAMA will ask you what to do
(b) if you delete a mask which has unsaved changes, MAMA will
ask you if you're absolutely sure
(c) if you quit and there are masks with unsaved changes, MAMA
will ask you if you really want to quit
You may run MAMA in batch mode by supplying the command line option -b (or -batch). In that case, MAMA will crash if she can't open an input file and any unsaved changes (with QUIT or DELETE) are lost forever. You may want to use this mode if you run MAMA in batch (using an input script).
NOTE: all output files are opened as "UNKNOWN", which means that any existing files will be overwritten !
NOTE: this program is sensitive to the environment variable OSYM.
It should point to your local copy of $ODAT/symm, the directory
which contains the spacegroup symmetry operators in O format.
When asked for a file with spacegroup operators in O format,
you may either provide a filename, or the name of a sapcegroup
(including blanks if you like, case doesn't matter). The program
will try to open the following files, assuming that STRING is the
what you input:
(1) open a file called STRING
(2) if this fails, check if OSYM is defined and open $OSYM/STRING
(3) if this fails, open $OSYM/string.sym
(4) if this fails, open $OSYM/string.o
Hint: if you make soft links in the OSYM directory, you can also type
spacegroup numbers (e.g.: \ln -s p212121.sym 19.sym).
When you start MAMA, she welcomes you with a list of available commands and options:
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- *** MAMA *** MAMA *** MAMA *** MAMA *** MAMA *** MAMA *** MAMA *** MAMA ***Version - 980929/5.4 (C) 1992-98 Gerard J. Kleywegt & T. Alwyn Jones, BMC, Uppsala (S) User I/O - routines courtesy of Rolf Boelens, Univ. of Utrecht (NL) Others - T.A. Jones, G. Bricogne, Rams, W.A. Hendrickson Others - W. Kabsch, CCP4, PROTEIN, E. Dodson, etc. etc.
Started - Sat Oct 17 00:41:42 1998 User - gerard Mode - interactive Host - sarek ProcID - 9091 Tty - /dev/ttyq17
*** MAMA *** MAMA *** MAMA *** MAMA *** MAMA *** MAMA *** MAMA *** MAMA ***
Reference(s) for this program:
* 1 * T.A. Jones (1992). A, yaap, asap, @#*? A set of averaging programs. In "Molecular Replacement", edited by E.J. Dodson, S. Gover and W. Wolf. SERC Daresbury Laboratory, Warrington, pp. 91-105.
* 2 * G.J. Kleywegt & T.A. Jones (1993). Masks Made Easy. CCP4/ESF-EACBM Newsletter on Protein Crystallography 28, May 1993, pp. 56-59. [http://alpha2.bmc.uu.se/usf/factory_1.html]
* 3 * G.J. Kleywegt & T.A. Jones (1994). Halloween ... Masks and Bones. In "From First Map to Final Model", edited by S. Bailey, R. Hubbard and D. Waller. SERC Daresbury Laboratory, Warrington, pp. 59-66.
* 4 * G.J. Kleywegt & R.J. Read (1997). Not your average density. Structure 5, 1557-1569. [http://www4.ncbi.nlm.nih.gov/htbin-post/Entrez/query?uid=9438862&form=6&db=m&Dopt=r]
* 5 * G.J. Kleywegt & T.A. Jones (1998 ?). Software for handling macromolecular envelopes. To be published.
* 6 * G.J. Kleywegt (1998 ?). Local density correlation and ... To be published.
* 7 * G.J. Kleywegt & T.A. Jones (2037 ?). Convenient single and multiple crystal real-space averaging. To be published ???
* 8 * G.J. Kleywegt & T.A. Jones (1999 ?). Chapter 25.2.6. O and associated programs. Int. Tables for Crystallography, Volume F. To be published.
==> For manuals and complete references, visit: ==> http://alpha2.bmc.uu.se/usf
*** MAMA *** MAMA *** MAMA *** MAMA *** MAMA *** MAMA *** MAMA *** MAMA ***
Allocate masks of size : ( 3000000) Max number of masks : ( 5) Max nr of masks in memory : 5 Max nr of points in mask : 3000000 Max nr of symmetry operators : 120 Max nr of NCS RT operators : 120
Initialising : (XVRML - 971120/0.6) Nr of predefined colours : ( 411)
MAMA's options :
? (list options) ! (comment) @ macrofile QUit & symbol value & ? (list symbols) $ shell_command ZP_restart masksize nummasks
REad maskname filename WRite maskname filename [how] DElete maskname LIst [maskname] DUplicate newmask oldmask NBr_count maskname UNite newmask mask1 mask2 SImilarity mask1 mask2 ODl maskname filename BOrder_check maskname DOt_odl maskname filename EZd maskname ezdfile LAbel mask text TRanslate mask tx ty tz ATom_fit maskname pdbfile [pdb_inside] [pdb_outside] INvert_ncs infile outfile
NEw ? (list defaults) NEw ORigin o1 o2 o3 NEw CEll a b c al be ga NEw EXtent e1 e2 e3 NEw GRid g1 g2 g3 NEw SAme maskname NEw RAdius value NEw RT_operator filename NEw FActor value NEw PAd p1 p2 p3 NEw SPacing value NEw REset_rt_operator NEw ENcompass oldmask
NEw PDb maskname pdbfile NEw BOnes maskname bonesfile NEw COpy mask oldmask NEw MAke maskname NEw UNit_cell mask oldmask NEw OLdbones maskname bonesfile NEw BAll mask x y z rad NEw CUbe mask x y z extent
FIll_voids maskname ISland_erase maskname EXpand maskname SMooth maskname factor COntract maskname CUt maskname factor NOt maskname BLob_erase maskname min_size
ANd mask1 mask2 OR mask1 mask2 BUtnot mask1 mask2 XOr mask1 mask2
OVerlap ? (list status) OVerlap SYmm_op filename OVerlap ORigin o1 o2 o3 OVerlap EXtent e1 e2 e3 OVerlap NCs_rt filename OVerlap REset_ncs OVerlap MOde mode_type OVerlap UNit_cell mask factor trim nextra [ezdf] OV TRim mask factor [ezdf] OV ERase mask factor [ezdf] OVerlap EZd mask ezdfile OV ASu_mask newmask oldmask
VRml SEtup central_atom max_dist backgr_col default_col VRml INit [filename] VRml COlour_list VRml DOt_surface mask [colour] VRml TRace pdb_file [colour] VRml CEll mask [colour] [line_solid] [x_offset] [y_offset] [z_offset] VRml BOx mask [colour] [line_solid]
Max nr of masks in memory : 5 Max nr of points in mask : 3000000 Max nr of symmetry operators : 120 Max nr of NCS RT operators : 120
MAMA > ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > $ xterm & MAMA > $ ls -FartCos m1*E 3435 -r--r--r-- 1 gerard 1758288 Jun 2 23:54 m1_start.E 1634 -rw-r--r-- 1 gerard 836224 Jun 8 13:46 m1_startx.E ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
This command can be used to manipulate symbols. These are probably
only useful for advanced users who want to write fancier macros.
The command can be used in three ways:
(1) & ? -> lists currently defined symbols
(2) & symbol value -> sets "SYMBOL" to "value"
(3) & symbol -> prompts the user to supply a value for "SYMBOL"
(even if the program is executing a macro)
A few symbols are predefined:
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > & ? Nr of defined symbols : ( 4) Symbol PROGRAM : (MAMA) Symbol VERSION : (960517/3.8) Symbol START_TIME : (Fri May 17 20:21:40 1996) Symbol USERNAME : (gerard) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
The symbol mechanism is fairly simplistic and has some limitations:
- max length of a symbol name is 20 characters
- max length of a symbol value is 80 characters
- max number of symbols is 100
- symbols can not be deleted, but they can be redefined
- symbol values are accessed by supplying $SYMBOL_NAME as an
argument on the command line; the line that you type on the terminal
(or in a macro) is parsed once; if there are additional parameters
which the program prompts you for, you cannot use symbols for those
- only one substitution per argument (e.g., "$file1 $file2" will
lead to a substituion of the entire argument by the value of
symbol FILE1 only !)
- command names (first argument on any command line) cannot be
replaced by a symbol (e.g.: "$command $arg1 $arg2" is not valid)
- symbols may be equated to each other, e.g. "& file2 $file1" will
give FILE2 the same value as FILE1
- symbol substitution is not recursive (e.g., if you set the value
of FILE2 to be "$file1", any reference to $FILE2 will be replaced
by "$file1", not by the value of FILE1
- symbols on comment lines (starting with "!") are not expanded
- symbols on system command lines (starting with "$") are not expanded
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > wr m1 test.mask com Writing mask (compressed format) Grid points : ( 360594) Stretches : ( 1458) Mask points : ( 30854) Mask write OK ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > delet m1 WARNING - unsaved changes to mask M1 !!! Really DELETE this mask (Y/N) ? (N) y Deleted : (M1) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
From version 4.2 onward, this command checks both ATOM and HETATM atoms. In addition, there are two new optional parameters, namely a PDB file for all atoms inside the mask, and a PDB file for all atoms outside the mask. You could use this to find all internal water molecules in your model, for example.
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > at m1 1cbs.pdb inside.pdb outside.pdb Checking atoms with radius : ( 2.000) ERROR - C1 REA 200 not covered by the mask ERROR - C2 REA 200 not covered by the mask ERROR - C3 REA 200 not covered by the mask ERROR - C16 REA 200 not covered by the mask ERROR - O HOH 304 not covered by the mask ERROR - O HOH 311 not covered by the mask ERROR - O HOH 315 not covered by the mask ERROR - O HOH 316 not covered by the mask ERROR - O HOH 318 not covered by the mask ... ERROR - O HOH 398 not covered by the mask ERROR - O HOH 399 not covered by the mask Nr of atoms read : ( 1213) Nr covered by the mask : ( 1141) Below lower grid bounds : ( 0) Above upper grid bounds : ( 0) Nr not covered by mask : ( 72) ERROR --- Mask too tight ! CPU total/user/sys : 1.4 1.4 0.0 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > inv Input NCS file ? ( ) ab.rt Output NCS file ? ( ) inv.rt==> Read NCS operator : (.LSQ_RT_M1_TO_M1)
...
Nr of NCS operators to invert : ( 1)
***** Operator nr 1 *****
Nr of RT operators : 1
RT-OP 1 = 0.3884420 0.0835182 0.9176806 -16.778 0.1145766 0.9837781 -0.1380325 25.467 -0.9143222 0.1587623 0.3725714 66.911 Determinant of rotation matrix 1.000000 Column-vector products (12,13,23) 0.000000 0.000000 0.000000 Crowther Alpha Beta Gamma 171.446 -68.126 -170.149 Spherical polars Omega Phi Chi 89.041 80.798 68.137 Direction cosines of rotation axis 0.159898 0.986992 0.016733 Dave Smith -159.671 -156.110 167.866 X-PLOR polars Phi Psi Kappa 174.026 170.748 68.137 Lattmann Theta+ Theta2 Theta- -1.297 68.126 -198.405 Rotation angle 68.137
***** INVERSE Operator nr 1 *****
Nr of RT operators : 1
RT-OP 1 = 0.3884419 0.1145766 -0.9143222 64.778 0.0835182 0.9837780 0.1587623 -34.276 0.9176804 -0.1380325 0.3725714 -6.017 Determinant of rotation matrix 1.000000 Column-vector products (12,13,23) 0.000000 0.000000 0.000000 Crowther Alpha Beta Gamma 170.149 68.126 -171.446 Spherical polars Omega Phi Chi 90.959 -99.202 68.137 Direction cosines of rotation axis -0.159898 -0.986992 -0.016733 Dave Smith -23.080 23.411 -16.434 X-PLOR polars Phi Psi Kappa -5.974 -170.748 68.137 Lattmann Theta+ Theta2 Theta- 1.297 68.126 161.595 Rotation angle 68.137
Nr of NCS operators written : ( 1) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
MAMA > new rt rt_error_imp.o
NEW RT-operator : ( 0.392 0.082 0.916 0.113 0.984
-0.137 -0.913 0.158 0.377 64.649 -34.211 -6.153)
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > new same m1 MAMA > new enc m2 Current NEw ORigin : ( 4 38 -16) Current NEw EXtent : ( 43 54 49) Current mask origin : ( -4 32 -27) Current mask extent : ( 60 67 74) New origin : ( -4 32 -27) New extent : ( 60 67 74) MAMA > new make New mask ? (M3) m9 Nr of points set : ( 0) CPU total/user/sys : 1.6 1.6 0.0 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > new spa 0.8 NEW grid : ( 146 153 103) MAMA > new grid 144 156 104 NEW grid : ( 144 156 104) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
These options combine two masks, but they alter only one.
If you combine two masks, both must have unit cell constants
which are identical to within 0.01 A and 0.01 degrees ! Also,
both must be on the SAME grid and they must have a non-zero overlap.
Only points inside the common volume are compared; the others
(if any) are NOT affected !
Furthermore, MASK1 and MASK2 may not be identical.
In all cases, the result of the operation is stored in MASK1 !
Use the SIMILARITY option first if you want to get an idea of
what will happen to your mask when you use one of these options.
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > and m1 m7 ERROR --- Masks have different cell constants MAMA > and m1 m4 Mask : (M1) And Mask : (M4) Nr of points set before : ( 30854) Lower limits common volume : ( 31 45 8) Upper limits common volume : ( 78 97 68) Limits first mask : ( 11 58 12 64 10 70) Limits second mask : ( 1 48 1 53 1 61) Number of common mask points : ( 155184) Nr of points set after : ( 27761) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
When used while your brain is active, these options are very powerful. They allow you to trim your mask in places where it overlaps with (non-) crystallographically related mates or to visualise places in the structure where a molecule might interact with a (NCS-) symmetry-related partner. See the HINTS at the end of this manual for clever tricks that help you find such contacts !
The overlap commands require careful input ! In particular, you should define the asymmetric unit of your unit cell very accurately !
The overlap option works as follows:
- it creates an "overlap map" the size of your asymmetric unit
- each point in the mask is subjected to ALL the NCS operators
and forced into the asymmetric unit (by applying the symmetry
operators of your space group); the point it ends up on is
marked in the overlap map
- the overlap map is then processed so that it contains a
count of the number of times a mask point ended up at a
particular place in the asymmetric unit
- this new overlap map is "averaged" inside the mask, except that
the counts are ADDED instead of averaged; this means, that
if you have three molecules in the asymmetric unit, points
without overlap will get a value of round about three (this
is "round about" since the operators lead to non-integer
grid points which have to be interpolated)
- if you do OVERLAP ERASE, all mask points which have a count
higher than the value you supply will be removed from the
mask. This value MUST be larger than the number of NCS
operators; we recommend this number plus one.
- if you are wise, you don't use the ERASE option but rather
the TRIM option ! If there is overlap, this means that
two different parts of the mask end up in the same place
after applying the NCS and/or symmetry operators and BOTH
places will be "flagged" as giving rise to overlap. Using
ERASE removes both parts but this will usually be too much.
It is better to remove only points at the mask SURFACE which
have overlap since this may be sufficient to get rid of (most
of) the overlap ! This is exactly what TRIM does for you !
It is recommended that you use TRIM two or three times in
succession to remove all of the overlap without cutting too
much off your mask.
Note: from version 5.2 on, there is a new command, OVerlap UNit_cell, which is easier to use than OV TRim and OV ERase, and which should be spacegroup-general.
If you want to make an informed decision, here are the algorithms:
*1* in both cases, all NCS operators are applied to each of the mask points. The resulting point will in general be non-integral; therefore the eight nearest points are flagged as follows:
2A* in LABEL mode, each point is OR-ed with 2**N, where N is the number of the NCS operator (modulo 32, since we use 4-byte integers for the overlap map). Thus, this option counts for each point in the asymmetric unit WHICH operators give rise to this point, BUT NOT how often they do that, AND NOT if the number of NCS operators is greater than 31 !!! As a consequence, if you have only one NCS operator (e.g., a tetramer in the asymmetric unit for which you want to use proper symmetry), this option is useless, since each flagged point will obviously be considered to arise from operator number 1, but it is impossible to figure out HOW OFTEN a mask point gave rise to this point, i.e. to detect overlap. In general, any overlap between the mask under operator N and itself will go undetected !! On the other hand, if you have more than 31 operators, the ultimate count MAY be an underestimation of the actual overlap.
2B* in COUNT mode, for each "hit" point in the asymmetric unit a simple counter is incremented. Since each mask point, under each NCS operator, will give rise to the flagging of EIGHT points in the asymmetric unit, you would expect that a normal, non-overlapping point would be flagged around eight times. For this reason, the accumulated counters are divided by eight afterwards, so as to get numbers comparable to those obtained with the LABEL algorithm.
*3* for the ezd, trim and erase options, the asymmetric unit in which each point contains a counter (LABEL: an estimate of the number of NCS operators that "hit" that point; COUNT: the number of times that point is "hit", divided by eight) is projected back onto the mask, but rather than "averaging", the counters (obtained after interpolation) are accumulated. At the end of that, each well-behaved mask point would be expected to contain an overlap count close to the number of NCS operators (this can be used to decide on a proper cut-off to use for the tim and erase options).
NOTE: from version 3.0 onward, you may add ONE, TWO or THREE points on all sides (must be the same number of extra points for each direction !). This turns out to be necessary for "pathetic" spacegroups such as R23 where the asymmetric unit runs from 0-1/3, 0-1/3, 0-1/2.
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > ov sym symop.o Nr of symmetry operators : ( 4) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > ov reset_ncs Nr of NCS RT operators : ( 0) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > ov ncs rt_unit.o New NCS RT operator : ( 1) MAMA > ov ncs rt_error_imp.o New NCS RT operator : ( 2) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > ov ncs allncs.o==> Read NCS operator : (.LSQ_RT_M9A_TO_A)
Nr of NCS operators : 1
NCSOP 1 = 1.0000000 0.0000000 0.0000000 0.000 ... Rotation angle 0.000000
==> Read NCS operator : (.LSQ_RT_M9A_TO_B)
Nr of NCS operators : 1 ... Rotation angle 179.490646
==> Read NCS operator : (.LSQ_RT_M9A_TO_C)
Nr of NCS operators : 1 ... Rotation angle 179.362045
==> Read NCS operator : (.LSQ_RT_M9A_TO_D)
Nr of NCS operators : 1 ... Nr of NCS operators now : ( 4) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
NOTE: in the output of OVERLAP EZD, TRIM and ERASE there are
some checks as to whether or not you have picked a
proper asymmetric unit. First, there's the number of
grid points: the number of points in your asymmetric
unit TIMES the number of crystallographic symmetry
operators MUST be equal to the calculated number of
grid points in your unit cell. (Don't worry, MAMA
knows that you have added an extra point in all three
directions !)
Second, the routine that calculates the overlap map
prints something like:
Nr of errors in FRC2V : ( 0)
This is a count of the number of points which could not
be brought into your asymmetric unit by applying your
symmetry operators. If this number is not zero, you
either have a wrong asymmetric unit, or a wrong set of
symmetry operators.
Similarly, the "averaging" routine prints:
Severe FRCSYM errors : ( 0)
Again, if this number is non-zero, you made an error.
See the example for the OVERLAP TRIM option.
Finally, MAMA prints which part of the unit cell will
be checked:
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
Checking the following part of the unit cell :
Start in fractional coordinates : ( 0.000 0.000 0.000)
End in fractional coordinates : ( 0.500 0.500 1.000)
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
Naturally, these limits should coincide with those of the asymmetric unit you had in mind (check the International Tables when in doubt).
This command ignores the OV ORigin and OV EXtent settings, instead using a fixed origin of (0,0,0), and calculating the extent of your unit cell from the grid of the mask on which you work. The OV MOde is used however, so you can still use LABEL and COUNT modes. Also, the NCS and symmetry operators must still be provided.
The OVerlap UNit_cell command has the following parameters:
- mask = name of the mask for which you want to remove overlap
- factor = the overlap cutting factor (same as for the OV ERase
and OV TRim commands)
- trim = the surface cutting factor: only overlapping mask points
with at least "trim" non-mask neighbours (0 to 26) will be removed
from the mask. In the OV TRim command, this number is always fixed
at 1, in the OV ERase command, it is always 0. Here, you can set
it yourself, enabling you to emulate both the TRim and ERase
behaviours, but allowing more flexibility by letting you set the
precise number yourself. (Note: this "trim" parameter is the same
as the "factor" parameter of the CUt command.)
- nextra = number of extra points that will be added on all sides
of the unit cell (sometimes necessary; a value of 1 or 2 is
recommended)
- ezdfile = optional; see the OV TRim and ERase commands
At present, the easy way to remove overlap is as follows:
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- ! read the mask re m1 coma_okay.mask li m1 ! define spacegroup symmetry ov sym p212121 ! define all NCS operators ov ncs rt_unit.o ov ncs rt_a_to_b.o ov ncs rt_a_to_c.o ! list settings ov ? ! remove overlap (three cycles) ov un m1 4.0 5 2 ov un m1 4.0 5 2 ov un m1 4.0 5 2 ! clean up the mask a bit contract m1 island m1 expand m1 ! save the new mask wr m1 coma_ovtrim.mask ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > ov un m1 4.0 5 2 Unit-cell-based overlap removal for mask : (M1) Nr of points set before : ( 29669) Unit cell origin : ( 0 0 0) Unit cell grid : ( 100 110 64) Unit cell extent : ( 102 112 66) Unit cell spacing (A) : ( 0.918 0.905 0.883) Nr of points in unit cell : ( 704000) Nr of extra points for grid : ( 2) Nr of unit cell grid points : ( 753984) Creating overlap map (mode COUNT) ... Nr of symmetry operators : ( 4) Nr of NCS RT operators : ( 3) Checking the following part of the unit cell : Start in fractional coordinates : ( 0.000 0.000 0.000) End in fractional coordinates : ( 1.010 1.009 1.016) ... Busy ... Expanding mask ... Nr of errors in FRC2V : ( 0) Counting ... Counts for asymmetric unit : Nr of points set 0 to 1 times : 156667 Nr of points set 1 to 2 times : 241448 Nr of points set 2 to 3 times : 1688 Nr of suspect points : 1688 Nr of points in solvent areas .......... 354181 Solvent areas as %-age of asymm. unit .. 46.97 "Averaging" overlap map ... Map Cell : ( 91.800 99.500 56.500 90.000 90.000 90.000) Spacing : ( 0.918 0.905 0.883) Map origin : ( 0 0 0) Map extent : ( 102 112 66) Mask origin : ( 25 39 -8) Mask extent : ( 78 63 79) FORGN : ( 0.000 0.000 0.000) FEXT : ( 1.010 1.009 1.016) GEXT : ( 1.000 1.000 1.000) ... Busy ... Nr of boundary points : ( 0) Severe FRCSYM errors : ( 0) Counting neighbours ... Removing overlapping mask points ... Min count for removal : ( 4.000) Min nr of nbrs outside mask : ( 5) Points with count 0 - 1 = 31 Points with count 1 - 2 = 1681 Points with count 2 - 3 = 14356 Points with count 3 - 4 = 12728 Points with count 4 - 5 = 659 Points with count 5 - 6 = 213 Points with count 6 - 7 = 1 Total nr of mask points : ( 29669) Suspicious mask points : ( 873) Percentage suspicious : ( 2.942) Nr of mask points removed : ( 172) Percentage removed : ( 0.580) Nr of points set after : ( 29497) CPU total/user/sys : 16.6 16.5 0.1 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
From version 5.0 on, MAMA can produce VRML files of masks and molecules (VRML = Virtual Reality Modelling Language). Rather than writing a dedicated set of routines to display these, use of of VRML is trivial for the programmer, and easy for the user.
Some things you may need to know:
- VRML files have the extension ".wrl"
- use your favourite browser with VRML viewer plug-in to inspect
the displays (you can launch it from inside MAMA, e.g.:
"$ netscape test.wrl &")
- colours can be defined by name or by RGB values (red-green-blue,
three numbers in the range 0-1). The VRml COlour_list command
will list all (> 400) predefined colour names and their RGB
values
A typical series of commands would be:
- (generate or read mask)
- VRml SEtup (if necessary)
- VRml INit filename
- VRml DOt mask
- VRml TRace pdbfile
- VRml CEll mask
- VRml BOx mask
The VRML interface was written for two purposes:
- quick inspection of masks and models (much quicker than
first writing them, then reading them into O, etc.; also,
not all MAMA users have access to O); since you can write
any number of masks and molecules to a VRML file you can
quickly see the results of mask improvement operations,
you can compare different masks, etc.
- creating files with masks and models which you can
include in your web pages (in this case, don't forget to
compress the files with the "gzip" command to reduce their
size !)
The options have been kept simple and fast. For fancier pictures of molecules you should use dedicated software (e.g., all-atom ball-and-stick models). Masks are drawn as hollow sets of points (i.e., dot surfaces).
With this command you can define the following parameters:
- the central atom type (" CA " for proteins)
- the maximum allowed distance between two subsequent central
atoms for them to be connected on the display (4.5 Å is a
reasonable cut-off for CA-CA distances in proteins)
- the background colour (default is black)
- the default colour for molecules (default is white)
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > vr set " CA " 4.5 white "0.35 0.87 1.0" Central atom type : ( CA) Max central atom distance : ( 4.500) Background colour : (1.000000 1.000000 1.000000) Default colour : (0.3500000 0.8700000 1.000000) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > vr se Central atom type ? ( CA) Central atom type : ( CA) Max central atom distance ? ( 4.500000) Max central atom distance : ( 4.500) Background colour ? (1.000000 1.000000 1.000000) grey Background colour : (0.5000000 0.5000000 0.5000000) Default colour ? (0.3500000 0.8700000 1.000000) red Default colour : (1.000000 0.0000000E+00 0.0000000E+00) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
This command opens a new VRML file (default: same file name as before if the file name is not provided). To actually write masks and molecules to it, use the VRml DOt and VRml TRace commands
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > vr in Open VRML file : (mama.wrl) Opened VRML file ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
To help you find colours, more than 400 colour names have been predefined. This command will list their names and their RGB values.
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > vr co Nr of colours : ( 411) # 1 (black ) = 12595212 RGB 0.000 0.000 0.000 # 2 (red ) = 12596212 RGB 1.000 0.000 0.000 # 3 (green ) = 13619212 RGB 0.000 1.000 0.000 # 4 (blue ) = 1061171212 RGB 0.000 0.000 1.000 # 5 (yellow ) = 13620212 RGB 1.000 1.000 0.000 # 6 (magenta ) = 1061172212 RGB 1.000 0.000 1.000 # 7 (cyan ) = 1062195212 RGB 0.000 1.000 1.000 # 8 (light_grey ) = 852276012 RGB 0.800 0.800 0.800 # 9 (grey ) = 537395712 RGB 0.500 0.500 0.500 # 10 (dark_grey ) = 222515412 RGB 0.200 0.200 0.200 # 11 (white ) = 1062196212 RGB 1.000 1.000 1.000 # 12 (gainsboro ) = 917351274 RGB 0.862 0.862 0.862 # 13 (honeydew ) = 1000330169 RGB 0.941 1.000 0.941 # 14 (mistyrose ) = 938355700 RGB 1.000 0.894 0.882 ... # 407 (dodgerblue2 ) = 991454330 RGB 0.110 0.525 0.933 # 408 (lightsteelblue3 ) = 855328391 RGB 0.635 0.709 0.803 # 409 (green3 ) = 13417484 RGB 0.000 0.803 0.000 # 410 (orangered4 ) = 12745261 RGB 0.545 0.146 0.000 # 411 (mediumorchid1 ) = 1061582714 RGB 0.878 0.401 1.000 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
Adds the mask you select to the current VRML file in the colour you indicate (if any). Only the surface points are written (to keep the files small).
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > vr ini Closed VRML file Open VRML file : (mama.wrl) Opened VRML file MAMA > vr do m2 green VRML - Dot surface for mask M2 Nr of points written : ( 13227) CPU total/user/sys : 2.1 2.0 0.0 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
Adds the central-atom trace of the molecule in the PDB file you supply, in the colour you specify (if any), to the current VRML file. Use the VRml SEtup command to define the central atom type and the maximum distance between sequential central atoms for them to be connected.
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > vr tr /nfs/pdb/full/1cbs.pdb yellow VRML - Trace of CA atoms for PDB file /nfs/pdb/full/1cbs.pdb Nr of atoms written : ( 137) ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
Adds a unit cell. You must supply the mask name. Optionally, you can specify the drawing colour, whether the cell should be drawn as lines or as a solid body, and you can supply offsets (integeral numbers of unit cells) so you can other unit cells than the one with x,y,z = 0->1.
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > vr cel m1 green line -1 1 0 VRML - Cell for mask M1 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
Adds the box of a selected mask. This can be helpful to see if the mask extends close to the borders of its grid.
----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- MAMA > vr box m1 purple VRML - Box for mask M1 ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE ----- EXAMPLE -----
The following options accept the wildcard character "*", i.e.,
if you type an asterisk instead of a maskname, the operation
will be carried out for ALL masks in memory:
LIST, DELETE, FILL_VOIDS, ISLAND_ERASE, NBR_COUNT, BORDER_CHECK,
SMOOTH, EXPAND, CUT, CONTRACT and NOT.
Fortran code for reading/writing masks is available from the O ftp-server (directory pub/gerard/extras/fortran).
(1) Overlap removal doesn't work with pathetic asymmetric units which have borders defined as "y<x" etc.
(2) There is no provision for overlap removal when multiple domain masks are used.
Created at Tue Mar 2 00:20:35 1999
by MAN2HTML version 971024/1.6