Map Overview (020710)

***** Superceded by the FastMap commands *******************
The Map commands have been replaced by the F(ast)M(ap) system. The only reason to use the old system is if yoiu need to make a Map_cover of some part of your structure. If you want to apply operators to electron density, it might also be easier to work with the old system.
This major menu allows you to control the parameters affecting the display of density maps. Data extracted from the maps are defined as objects. Each of these objects requires the user to define a number of parameters. Thus it is possible to have different maps, colour, contour level etc. displayed at the same time. Any number of objects can be made from a particular map file but a particular object comes from just one file, one level, one volume, one colour.

The program caches the map to speed up access. This is associated with the file name so the user must issue a map_cache command before introducing a different map with the same file name during the same session.

Map objects are deleted with the delete_object command.
Here are some examples:
The following will draw a cube of electron density around the CA of residue B50. It will be drawn in an object called map_a and be coloured sky_blue :
map_file m10_a.dsn6
map_par 12. 12. 12. 0.18 sky_blue 0.5 0.1 1
map_obj map_a 2.0
map_atom b50

is useful when making photographs or plots, and you want to get rid of irrelevant density, but it is also useful just to draw the density around an object. In this case you should chose a large radius, so you don't accidentally mask out density that you want to see. In this macro, we define a sphere of atoms, and cover them with a map, using current parameter setting:
centre_id wait_id
object sph sphere 8. end
map_cover sph 5.
map_obj map_a map_draw

The datablocks for the map menus are listed below and should not be changed by the user:
1 map colour code (mpcolr)

1 contouring level (mplevl)
2 - 4 size of contour box along cell edges (mpbox)
5 - 7 centre of density (mpxyz)
8 - 9 intensity of the map, fore & aft (mpini).
10 map cover radius
1 map line type (mpltyp) - not currently used.
2 map type (mptyp)
3 - 5 map centre: molecule, residue, atom (mpacon)
6 map object name (mptyp).


map_atom_centre <[mol] residue [atom]>

Define the map centre for extracting contours by molecule, residue, and atom. The molecule and atom names are defaulted to current molecule and Ca.



Define map centre by selecting the value stored in the datablock .active_centre .



Resets all cache data structures. To speed up map access, each record that is read from a map file is cached into memory so that it can more quickly be accessed in a subsequent read operation. If a user works with a map say, and then finds it was a Fo-Fc map by mistake, he might be tempted to use the same file name after correcting the mistake. In such a case it would be necessary to clear the map cache before using the new map.


map_cover <object_name> or <Id atom> <radius>

This command allows you to display density around an object. When chosen, the command changes the crurrent values for the map box and centre. It forms a mask around each atom in the object using the input radius. This is applied the next time Map_draw is chosen, and then cleared. Therefore, the second time you choose Map_draw, you will get the whole map box contoured.



Draw a map object using current defined parameters, file, centre.


map_file <file_name>

Name the map file. This is a special electron density file made up of 8 á 8 á 8 byte cubes of density. It is made from standard maps, (CCP4, X-PLOR, PROTEIN, etc.), with a program called mappage or with progams from Gerard Kleywegt's system. This file structure is the same one used in most versions of FRODO (but not in Phillip Evans' version).



Gives information about the currently used map file. The mean and standard deviations of the map are not stored in my current map file.


map_object <object>
Name for the map object. This object cannot be picked (identified) and only the first 6 characters are used.

map_param <box_x box_y box_z>
<front_intensity back_intensity>

Define the map parameters. These are the box sides in Å 's, the level, the colour, the front and back intensity and the line type. The following line types are supported:
1 : solid line
2 : dashed line
3 : dotted line
4 : dot dash line
5 : semi-transparent solid surface.


map_xyz_centre <x y z>

Define map centre by coordinates. The coordinate system used is orthogonal Å with the a* parallel to x as in the PDB standard. This differs from the system used by Rossmann & Blow in their Rotation Function paper for monoclinic space groups. It is identical to the coordinate system used in FRODO (Jones, 1978).

Mask Overview

***** Superceded by the NCS commands *******************
Masks created with these commands can be read into the FastMap based NCS commands
Molecules frequently crystallize in space groups where there are more than one molecule in the asymmetric unit. This can be used to advantage by averaging the electron density. One requirement for this is the creation of a volume containing the non-crystallographic asymmetric unit, called the mask. The user is encouraged to read the paper Jones (1992) to get an overview of averaging but also to read the original literature. More recent programs can carry out averaging without a user defined mask, but if you want total control ....
Once a mask file has been generated, it can be edited in O with some of the Mask commands. The commands available give complete control over the final shape of the mask.
Some of he commands are illustrated by the following example (user input is high-lighted):

O > mask_read
Mask> File name of mask to be read: m12a.mask
Mask> Parameters as read from the mask file:
Mask> Grid ................. 100 110 64
Mask> Origin ............... 31 45 8
Mask> Extent ............... 48 53 61
Mask> Cell axes ............ 91.80 99.50 56.50
Mask> Cell angles .......... 90.00 90.00 90.00
Mask> Mask read OK.
Mask> 33221 points set in mask
Mask> 155184 points total
O > mask_setup
Mask> Mask value to set & display [ 1 1]: 1 0
Mask> Radius in which pixels are set & displayed [ 1.0 8.0]: 2. 9.
Mask> Radius in which to contour [ 10.0]:
Mask> Contour colour? [red]:
O > mask_on
O > mask_off
O > mask_contour
O > mask_write
Msk> File name of mask to be written: m12a_edit.mask
O >

The mask_read and mask_write commands read and write out mask files. Only one mask file can be stored at a time.
The Mask_setup command set parameters used with the mask_on and mask_off commands that control what will be displayed and how the mask is to be edited. In the above example,both Mask_on and Mask_off will display non-mask grid points within 10Å of a moving atom as dots. When editing is set 'on' by the Mask_on command, points 1.0Å from the moving atom will be set as lying within the mask. This will have the affect of erasing the dots drawn on the display. The setup values used here are, therefore, suitable for detecting holes in the mask and for removing them.
The commands Mask_on and Mask_off start the display of the mask. Both commands require the user to identify an atom that can be moved around in space. Dots will appear that represent grid points either within or outside the mask depending on the values set with Mask_setup. If Mask_off is active, then as the atom is moved around, the mask object is updated but the mask is not changed. When Mask_on is active, the mask gets changed and grid points within the specified radius are reset, according to the Mask_setup values. Activating Mask_on, deactivates Mask_off and vice versa. When either command is active, Mask_setup can be activated to change the current values.



This command allows a user to display a wire contour view of the current mask. The centre is the current active centre.


mask_object <name>

This command allows a user to define the name of the mask object that is drawn


mask_off <id an atom>

This command allows a user to travel through the mask to inspect it. The mask appears as a set of green points, either at pixels where the mask is on or off, depending on the last mask_setup. The identified atom moves under the control of the dials.


mask_off <id an atom>

This command allows a user to edit a mask. As the atom moves, pixel points within a specified radius get set to a particular value. Both these values are set by mask_setup.


mask_read <file_name>

This commands reads in a mask from the external file system. Only one mask is stored in O at a time, so an earlier mask is over-written. The format of the external mask file is fixed. It can be generated by a number of external programs, bones_mask or pdb_mask, and by Gerard Kleywegt's program system.


<value_set value_displayed>
<set_radius display_radius>

Setting a pixel point on, associates the value 1 with that point. This command allows the user to decide if the mask is to be shaved, or expanded. When the mask is being edited, it appears as a grid of dots. These dots can either represent mask on or off, depending on what the user defines in mask_setup. Radii are used to control the volume in which editing takes place, the volume to be displayed as dots, and the radius within which the mask can be contoured with mask_contour. The contoured mask can of course have a user definable colour.


mask_write <file_name>

This command writes out the current mask to the file system.

Menu <major_menu_name or text> <on/off> <colour>
Control what menus are displayed and therefore visible to the user on the display. If the text is a major menu, all commands for that menu are put onto the screen. To add the Lego commands to the screen, for example, just do:
O > menu lego ;;
To add a macro called map, do:
O > menu @map ;
The new commands are added to the bottom of the menu.
A list of available major menus can be obtained by typing:
O > menu ?
The screen menu is maintained in a datablock called .menu and can be changed in other ways. For example, its contents can be converted in a formatted file with Write_formatted , edited with your favourite editor-remembering to correctly update the number of lines, and then added back into the database with Read_formatted command.
Here is an example:
.MENU T 15 50
colour_text green

colour_text red
colour_text yellow
colour_text magenta
In the above, I am using the colour commands to indicate distinctive actions. Blank lines are there to separate groups of commands. There are 15 lines in the menu.

Merge_atoms <from_molecule from_start from_end>
<to_molecule to_start>

This command allows one to merge a zone of atomic coordinates in one molecule, into another molecule,with an optional transformation applied. The transformation is a database vector of 12 numbers. They can be the same molecules, and the from zone can overlap with the to zone.
The command can be used to :

1.Correct out of register errors,
e.g. merge_atoms a27 a100 a110 a27 a101 ;
Each residue would need updating with lego_side_chain or lego_auto_sc and the boundaries carfeully refitted.
2.If one has a number of molecules in the asymmetric unit, to paste the coordinates of one into the other
e.g. merge_atoms a27 a100 a110 b27 .lsq_rt_a_to_b
where we assume a transformation .lsq_rt_a_to_b relating molecules A27 and B27.
3.Generate a complete molecule from CA coordinates. If the complete molecule is called M1 (made with sam_init_db), and the CA's are stored as M1CA, then
merge_atoms m1ca 1 130 m1 1 ;
Then use lego_auto_mc and lego_auto_sc

message "Hi you guys"
Send a message to be displayed on the screen. Use in your macros to say what you are doing.
Molecule_nam <name>
Redefine the name of the molecule. The name of the current object is changed to the same name. Therefore, if the object name is to be different from the molecule name, the Object_name command must be invoked after Molecule_name. Once defined, the name of the current molecule is saved, until it is explicitly changed. The names of several datablocks are generated from the molecule name. For example, if the molecule name is 'M15', a datablock called
holds the orthogonal coordinates of all atoms in molecule M15. In the current version of O, the name of the molecule must fit into 5 characters.
Move Overview

***** Superceded by the Grab commands *******************
These menus allows the user to manipulate the coordinates of a molecule by moving around an atom or groups of atoms. The coordinates in the database are updated as the atom(s) move and can therefore be tagged with distances and neighbour calculations. However, the updated coordinates are not written to disk until one of the following commands Save_DB, Stop, BackUp_db, pdb_write, sam_atom_out is issued. In general, the MOve commands are terminated by selecting Yes or No to accept or reject the new coordinates.
These commands make use of the dials (real or virtual) to control the manipulation. Each command have dial input assigned in groups of 4 (since dial booxes come like that). The actual dial assignments would depend on what commands were active when the move command was activated. The Move_atom command assigns a block of 4 dials, 3 of which control the displacement. The other move commands assign 2 blocks of four, so that the orientation can also be controlled. The user is able to switch between the dial blocks with the Dial commands.
Most users without physical dials, prefer to use the Grab commands.

move_atom <id an atom> or <mol res atom>

The identified atom moves under the influence of the dials. The atom moves in 'screen space' and not the molecular coordinate space. You should use Yes or No to terminate the command. The Clear_flag command accepts the coordinates, producing the same result as Yes. The coordinates are updated as the atom moves. The shape of the moving atom can be changed at will, an O descriptor in a text datablock called .moving_atom .


move_fragment <id an atom> or <mol res1 res2 object>

Moves an atomic fragment. The fragment containing the identified atom moves, with this atom as the pivot point. The breakdown of each residue into fragments is defined in a dictionary, and can be customized by the user. The dictionary is the same as that used by the RSR menus. In the distribution files, the peptide plane fragment is defined as CA C O N+ (i.e. the nitrogen of the next residue). Do not, therefore,identify a peptide nitrogen to define the fragment.
You should use Yes or No to terminate the command. The Clear_flag command accepts the coordinates, producing the same result as Yes. The coordinates are updated as the fragment moves, with 'screen space' translation.


Move_object <object>

Moves any object that is presently being displayed. This cannot be used to change the coordinates of any molecule (it does not update any coordinates). You can make a graphical entity using the Object Description Language, for example, and then place it anywhere you like. The applied transformation can be saved in the database, and the object remains transformed on acceptance. You must use Yes or No to terminate the command.The Clear_flag command accepts the operation, producing the same result as Yes.


move_zone <id two atoms> or <mol res1 res2 object>

Moves a specified zone of residues. The user is required to pick an atom in the start and the end residue. In particular, 'double clicking' on an atom in a residue makes that residue active and the identified atom is taken as the pivot point. Otherwise the centre of mass is used as the pivot point. The identified zone moves under the influence of the dials, with 'screen space' translation. You should use Yes or No to terminate the command.The Clear_flag command accepts the coordinates, producing the same result as Yes. The coordinates of all atoms in the zone are updated as the atoms move but only the displayed atoms are updated on the screen.


When this command is activated, the user is asked to identify an atom in the molecule that is going to be rotated/translated. When that is done, the user can input initial values for the eulerean angles. These are given in degrees. The initial translation can be given in fractional units .
The dials then become active, and the eulerian angles and fractional translation can be dialed in. The current values are shown on the screen. The Yes command will apply the transformation operator to the coordinates, and the No command will keep the original coordinates. If you accept the new coordinates, and reactivate MR_rt, the eulerian angles will be relative to the newly accepted coordinates, so be careful.
O > mr_rt
O > MR> Angle convention: X-PLOR
MR> Search molecule: HCAC
MR> Object: HCAC
MR> Define initial eulerian angles [ 315.60 39.60 0.00]: 0 0 0
MR> Define initial translation (fractional) [ 0.00 0.00 0.00]:
MR> Dials are now active...
O >
O > no
MR> Original coordinates restored.
O >


The MR commands are meant to let you investigate how a potential molecular replacement solution may pack in the crystal.
Set up parameters. Angle convention (only X-PLOR has been debugged), and the unit cell of the unknown structure.
O > mr_set
MR> Angle convention? [X-PLOR]:
MR> Define unit cell of unknown [42.70 41.70 73.00 90.00 104.60 90.00]:

Mutate Overview
This group of commands allows one to mutate the sequence of a molecule. Some of them can also be activated from the pull-down system (Rebuild/Mutate).
These commands delete any molecular objects that might exist, as well as certain entries in the user database (connectivity, stereochemistry information).
The molecule must exist in the data base. The commands may/will make use of the side-chain and main-chain databases and must be correctly specified via the Lego_setup command.
These commands will delete all existing objects made from the molecule to be mutated, as well as connectivity and stereo-chemical information. A macro is activated to regenerate the sterochemistry (it just does a simple refi_init & refi_gener)
Usually it will be necessary to manually modify the coordinates of your molecule after using a Mutate command. The best all-purpose command for doing this is the Grab_build command.

Mutate_1st (080218)
O has had commands to mutate the sequence of a molecule for many years. The Mutate_insert command, in particular, adds a new residue after a particular residue in the molecule. This makes it hard to place a new residue at the beginning of the molecule (although it can be done). Mutate_1st is the command you need to insert residues at the beginning of a molecule, but is otherwise very similar to mutate_insert. In particular, this commands only makes space in the various O DBs for the new residue(s), you have to do something about placing the atoms at some sensible place (e.g. with the Grab_build command). For each new residue, the user needs to specify a residue name (e.g. A0) and the residue type (e.g. PHE). All objects associated with the molecule are deleted.

O > mut_1st
Mut>  Mutate a molecule by inserting residues at the start
Mut> Molecule ([A  ]) :
Mut> New residue name and type (<cr> to end) : a0 phe
Mut> New residue name and type (<cr> to end) :
Mut>  There are     1 mutations
Mut> This atom has the potential for an incorrect Z: CA
Mut> SEGIDs will be checked and updated
Mut> Cannot find a segid
Mut> Molecular connectivity deleted.
Mut> Stereochemistry entries deleted
Mut> Delete_objec CA     A      ;

where the new residue is a phenylalanine, called A0. The molecule has no segIDs associated with it. The stereochemistry is generated by activating the @on_stereo_chem macro in the database.

mutate_delete <molecule> <residue_name>i
Any number of residues can be deleted. Input is terminated by a blank input.
This command would usually leave non-standard stereochemistry. This can be corrected with refi_zone, lego_loop or Grab commands.
mutate_insert <molecule> <residue_name>
<new_residue_name new_residue_type>i
Adds new residues after a specified place in the molecule. Terminated by a blank line. The new residue names should be unique to the molecule.
This command merely makes space in the database for new residues. The user must place them. This could be done in a number of ways, but recommend lego_loop to start with
E.g. The following will insert an alanine residue after residue 102 in molecule A26:
mut_insert a26 102 102a ala ;
sel_off a26 102 103
lego_loop a100 a105
If the new residue had a longer side chain e.g. PHE it would also need to be constructed with lego_side and identify an atom.
Note that this command does not allow one to add new residues at the start of a molecule. This is done with the mutate_1st command.
mutate_replace <molecule> <residue_name new_residue_type>i
Any number of residues can be mutated until a blank line is entered. All atom properties of the specified molecule are changed in size to accommodate the new sequence. Certain properties are assigned special values, others are given default values.
_atom_z is changed to reflect the elemental type of the new atom
_atom_b new atoms have a temperature factor of 20.Å2
_atom_name new atom names are taken from the contents of the file specified in the last Connect_file command.
_atom_wt new atoms have weights of 1.0
_atom_colour all atoms in a mutated residue are coloured magenta
The default values for all other properties are 0,0.0 and ' ' for integer, real and character properties.
The new residue type must exist as an entry in the contents of the file specified in the last Connect_file command.
Because molecular objects are described in the database as link lists, their pointers are to the OLD positions in the molecule. All objects of the changed molecule are therefore deleted and must be re-made by the user. Mutated residues will appear coloured magenta.
Side chain confirmations are from the most frequent side chain rotamer. The database must therefore be correctly defined in the stereochemistry dictionary
Here is an example:
O > mut_repl
Mut> Mutate a molecule by replacing one residue type
Mut> by another.
Mut> Molecule ([TRACE ]) : a
Mut> Residue name and new type (<cr> to end) : a7 leu
Mut> Residue name and new type (<cr> to end) : a8 phe
Mut> Residue name and new type (<cr> to end) :
Mut> There are 2 mutations
Mut> Molecular connectivity deleted.
Mut> Stereochemistry entries deleted
Mut> Delete_objec ACA AALL ;
Refi > No bond distances in Db for FA
Refi > No bond angles in Db for FA
Refi > No torsion_fixed in Db for FA
Refi > No torsion_flexible in Db for FA
O > wr @on_mutate ;;
Refi_init A
Refi_generat ; ;
Build_rotome A A7 1
Build_rotome A A8 1
The strereochemistry entries for the molecule are also automatically deleted.A macro on_mutate is generated in the user's database and activated. This macro (see above) builds a simple set of stereochemistry entries and then carries out the necessary rotamer builds. The warning messages ('No bond ...') occur because the molecule (the P2 distributed coordinates) has a fatty acid for which no stereochemistry information exists.