Chapter 2: Master Menus 


2.0 History

O has a rather simple graphics user interface. It is written in OpenGL, in the 3D viewing window, and the menus are actually described in 3D space too. There are disadvantages to making the GUI like this, not the least of which is the lack of a ‘standard’ interface for the computer you are using. If you are an OS X user, for example, you are used to a certain way of working and it is something of a shock to meet my system. The advantage of my way of doing things is that it is trivial to move from one OS to another. Nowadays there are widget libraries available that would allow me to do this, but these didn’t exist when I started, which is no excuse for today but ....

Since Ov6, there has been a pull-down menu system in the 3D window that contains some of the more useful commands that are a few clicks away. See the ‘Pull-down’ section ofA-Z of O’ for all of the details. As part of this system, there is one menu pane called the ‘User menu’ that is under the control of the user; it is not hard wired into the program. The master menu system manipulates this data structure to provide the user with the essential tools that the crystallographer needs for specific tasks such as working with skeletonized electron densities, rebuilding a structure, creating an inhibitor and so on.


The following description takes you through the following topics:

1/ Master Menu - an introduction to some of the details

2/ Master Rebuild - a menu for when you want to start rebuilding your structure

3/ Master Skeleton - a menu for working with skeletonised electron density and tracing a new structure in a map.

4/ Master Quick & Dirty Sketch - a menu for building new inhibitors for which you have no dictionaries or atomic model.

5/ Master Font selection - a menu to help you configure O the way you like it, but presently only allowing you to set screen fonts; the rest is not yet started.

 

If you have suggestions for adding more functionality to this system, please drop me a line. 



2.1 Master Menu Overview

2.1.1 History

O provides a number of ways for the user to supply input interactions. Since Ov6 there has been a pull-down menu system that collects together many useful commands that are just a couple of clicks away. Normal users would not usually modify the underlying control structures that are in the user’s database but there is one entry that is meant to be controlled and modified by the user. The entry .user_menu in the O DB contains instructions for how this so-called user-menu is to be drawn (colour etc) and .menu contains the actual text to be drawn in the window. Here are the default values in the distribution (contained in the file menu.odb):


 O > wr .menu ;;     

.MENU                     T         10         50

colour_text magenta                               

<Master Menu> @Master_menu                        

Save                                              

Stop                                              

<Clear flags> Clear_flags                         

<Clear ID text> Clear_Id                          

<Centre ID> Centre_id                             

Yes                                               

No                                                

<>                                                


 O > wr .user_menu ;;

.USER_MENU                T         12         50

origin -0.400 .80                                 

pane_size .350 0.05                               

step 100                                          

colour_background black                           

colour_text magenta                               

colour_inverse_background red                     

colour_inverse_text green                         

moveable                                          

text User_menu                                    

text Yes                                          

text No                                           

text Save                                         


The user can create his/her own description of the .menu entry, read it into O and use it. The default entries, however, are primed to use the master-menu system.


2.1.2 What do I do? 

Once the default menu has been loaded, the user menu will look like the image on the left:


Image

Figure: Master Menu Default


As usual, you can keep it open by clicking on the small square in the top left corner of the pane, to produce the middle image. By clicking on the text ‘Master Menu’ on the second line, the latest version of the system will be loaded into your session. As I write this (121112), the window on the right would be generated.


If you want to start using the master-menu system for the first time with an existing O user database, read the ODB file menu_master.odb into your O session and you will get the user-menu shown on the above right. This could be done when you start O or after the program is running. For example, suppose you have your project saved in a file called p2.o and an alias to run O and you have set up the environment variable ODAT to the correct directory, you could then incorporate the latest master-menu into your database by starting the program like this:


% ono p2.o menu_master.odb ‘;’


In the 3D O-window, you will then get the current master-menu system that is available to you. If you are running O and you want to update the master-menu, just read in the ODB file from the terminal prompt like this:


O > read menu_master.odb


I plan to keep improving the menu system, so watch out for updates.


In the master-menu system, the magenta coloured options will always appear at the top of the window pane; these are links to activate commands that I would classify as being essential to any O session and should always be a click away. Their functions are, I think self evident. The green text are menus that are associated with particular activities. In the above case, I have links available to menus that are designed for rebuilding your structure during crystallographic refinement, working with skeletons, creating a new ligand, and modifying fonts. If you click on one of these links, an appropriate user-menu will be loaded. 


Image

Figure: The Master-menus associated with rebuilding, skeletons, building ligands and setting fonts.


Note the magenta text at the top is unchanged and if you click on ‘Master Menu’, the latest version will be loaded from your ODAT directory. The green text contain frequently used commands that are associated with the relevant menu. The separately coloured commands at the bottom, correspond to less frequently used commands that are hidden away in what i call blinds. Clicking on one of them will cause the menu to expand and clicking a second time will contract the pane. If you open all blinds associated with the ‘Skeletons’ major menu, for example, you will have too many entries and the menu will be truncated. The blinds, therefore, are meant to be open and closed as required.


2.1.3 What you don’t need to know.

The master-menus make use of some new features in my menu creation system. 

Let’s look at the ODB entry again:


 O > wr .menu ;;     

.MENU                     T         10         50

colour_text magenta                               

<Master Menu> @Master_menu                        

Save                                              

Stop                                              

<Clear flags> Clear_flags                         

<Clear ID text> Clear_Id                          

<Centre ID> Centre_id                             

Yes                                               

No                                                

<>                                                


This ODB entry is a simple text data-block of 10 lines that are 50 characters wide, and where the text on each line gets parsed by my menu control code. The text colour_text at the start if the line is parsed to the current text colour, in this case magenta. If the text is between ‘<‘ and ‘>’ characters, this text is written out in the 3D pane, put the following text gets sent to the parser when the line is clicked in the 3D window. So if the user clicks on the text ‘Master menu’ in the 3D window, the macro Master_menu is activated. Similarly, clicking on the text ‘Centre ID’ in the user menu, activates the Centre_id command .


Here is how I define a blind (from the Rebuild master-menu):


colour_text cyan

<** Molecular Objects **> +rebuild_mol_objects   


The text ‘** Molecular Objects **’ is drawn in the menu in cyan text, and when it is clicked, the menu expands with the menu described in the ODB entry rebuild_mol_objects:


Image


If the blind is expanded and then the text ‘** Molecular Objects **’ clicked a second time, the blind will close. in the above example, the ODB entry rebuild_mol_objects contained this menu:


rebuild_mol_objects t 5 72

<Draw Ca atoms> @rebuild_ca

<Draw Ca rainbow> @rebuild_ca_rainbow

<Draw Ca inverted rainbow> @rebuild_ca_inverted

<Draw all atoms, C yellow> @rebuild_all

<Draw all atoms, C white> @rebuild_all_c_white



2.2 Master Menu Rebuild

2.2.1 Getting Started

The following image shows the Rebuild master menu with the first 3 blinds expanded in turn:

Image

Figure: Master-menu with 3 expanded blinds; ‘User specific’; Symbols setup’; ‘Molecular objects’


The user can provide an extra specific menu of macros/instructions that are not included in my distribution. This is achieved by supplying your own version of the ODB entry user_specific. This is a text DB and here are the contents of the distribution entry:


 O > wr user_specific ;;

USER_SPECIFIC             T          5         72

<Not defined> !                                                         

<Not defined> !                                                         

<Not defined> !                                                         

<Not defined> !                                                         

<Not defined> !   


Clicking on the text ‘** User specific **’ will, therefore, generate the second menu in the above figure. So use your favourite editor to make your own version of the user-specific entry.


2.2.2 Symbols setup

Before working with this menu. you HAVE to specify a few symbols which will tell O the name of the molecule you are working with, maps etc. N.B. the molecule that you specify must be loaded into O already. If you want to understand how symbols work in O, take a look in ‘A-Z of O’, which is available from the link at the top of this page.


The blind expands to allow you to specify 3 sets of symbols; the molecule and maps symbols MUST be set, the HKL-specific symbols are only needed if you plan to calculate phases and maps in O, and the Refmac-related symbols are only required if you plan to run this refinement program from O. 


Clicking on the the ‘Molecule & Maps setup’ activates a popup into which you can update the current values of 3 symbols to define the molecule, and the 2 kinds of difference Fourier maps (2|Fo|-|Fc| and |Fo|-|Fc|) that you can work with. In this example, they have values m1, f21 and f11 respectively:


Image


and since I want to change the model to m2, I first click on the second line in the popup ‘Define the molecule name: m2’, press the <Delete>-key and then press the 2 key:


Image


To reset the macros to these values, I then click on the fifth line ‘Activate macro’ to make the change. We get a conformation of the new settings in the O Terminal-window:


 As4> Here are the new symbols

 New> REBUILD_MOL  m2

 New> REBUILD_F21  f21

 New> REBUILD_F11  f11


This output also gives you the actual names of the relevant symbols REBUILD_MOL, REBUILD_F21, REBUILD_F11.


The ‘HKL setup’ pop-up allows one to redefine the two symbols that are specific to calculating maps in O:

Image

where the O reflection project and resolution are defined (symbols HKL_PROJ and HKL_RESOL).


The ‘Refmac setup’ pop-up allows one to redefine the four symbols that are specific to running the Refmac program from O:

Image

The relevant symbols are used to describe the MTZ file to be used by Refmac, and the associated MTZ labels for structure factor, structure factor standard deviations, and R-free label (symbols MTZ, MTZ1, MTZ2, MTZ3). The labels must correspond to those in the MTZ file. It is important that the explicit MTZ file name is not too long (stick to less then 60 characters).


2.2.3 Green Commands 

The green text contains frequently used commands that are associated with rebuilding:

Save to PDB file If the molecule is M1, this creates a PDB file M1.pdb with all O prompts set to default (O command equivalent PDB_write)

Reset B-factors in residue The user is prompted to ID an atom and then all atoms in this residue have their B-factors reset to 20.0 Å2 (a macro that uses the O command DB_set_zone)

Set residue occupancy to 0. The user is prompted to ID an atom and then all atoms in this residue have their occupancies reset to 0. (a macro that uses the O command DB_set_zone)

Set residue occupancy to 1. The user is prompted to ID an atom and then all atoms in this residue have their occupancies reset to 1. (a macro that uses the O command DB_set_zone)

Add alternate conformation The user is prompted to ID an atom and then an alternate conformation for this residue is generated (O command equivalent Build_alternate)

Neighbours Allows the user to measure close contacts (O command equivalent Neighbour_at)

Distance Allows the user to measure distances (O command equivalent Dist_define)

Regularize zone Allows the user to regularize a zone of residues (O command equivalent Refi_zone)

Grab an atom Allows the user to grab an atom and move it around (O command equivalent Grab_atom)

Torsions via bonds Allows the user to change torsion angles via the bonds between ID’ed atoms (O command equivalent Tor_general)

Torsions in residue Allows the user to change torsion angles via the defined dictionary for the identified residue (O command equivalent Tor_residue)

Rotamers Allows the user to change rotamer conformations for a residue (O command equivalent Lego_side_Ch)

Start rebuilding Activates the Grab_build command; the main rebuilding command in O.

Move forwards Centres on the next residue (O command equivalent Centre_next)

Move backwards Centres on the previous residue (O command equivalent Centre_prev)


The underlying O commands are described in detail in ‘A-Z of O’.


2.2.4 Simple Rebuild Blinds 

The next pair of blinds expand to allow you to make simple molecular objects with differing colouring schemes, and to generate useful properties that can be helpful when rebuilding:


Image


The CA objects will be named <mol>_CA while all atom objects are called <mol>_ALL

Note that CA refers to CentralAtom and not just the C-alpha atom of an amino acid. These are defined in the O stereo-chemical dictionary (usually called stereo_chem.odb in your ODAT directory). If your molecule is a protein-DNA complex, the CA object will draw both of them.

The CA objects can be coloured yellow, rainbow (i.e. the first residue in the sequence is coloured red, the last is blue and all others are ramped to follow the rainbow), inverted rainbow (blue->red). The all-atom objects have my standard colouring but carbon atoms can be yellow or white.


The properties blind generates ODB entries for peptide-flip distances (O command equivalent Pep_flip) , similarities to closest rotamers (O command equivalent RSC_fit), residue-averaged electron density values (O command equivalent RS_fit with the aver evaluation function option), residue-averaged B-factors (O command equivalent Db_a2r_avera), and an update of the secondary structure classification (multiple calls to YASSPA for helix and strand assignments, then the CA object gets remade with a new colouring scheme that reflects the secondary structure). The sequence slider window and property graph window will be opened and displayed (O command equivalent Graph_prop and if the graphing window is already open, its position on the screen will be unchanged, otherwise I place it centrally).


2.2.5 HKL blind

The HKL-related blind provides access to phase and map calculations, as well as refinement and water adding tools:


Image


These actions are quite complicated macros which I will not describe in detail.

Fc & Fourier calculation Calculates new phases and electron density maps of type 2|Fo|-|Fc| as well as |Fo|-|Fc|. Outliers are removed from the map calculation, amplitudes sharpened and a graph of |Fo| vs |Fc| is drawn. Map slider are opened and positioned at bottom left and right for F11 and F21 maps, respectively.

2|Fo|-|Fc| Fourier calculation Calculates a 2|Fo|-|Fc| map with current phases (no outlier removal, sharpening).

|Fo|-|Fc| Fourier calculation Calculates a |Fo|-|Fc| map with current phases (no outlier removal, sharpening).

Chop Zone Fourier calculation Removes a zone of residues from the current phases and calculates a new F11 map called chop11.

Chop Residue Fourier calculation Removes a single residue from the current phases and calculates a new F11 map called chop11.

Sort waters on B-factors Sorts a sea of water molecule so that the new order is from low to high. The sequence slider window and atomic B-factor property graph window will be opened and displayed (if they are already open, their position on the screen will be unchanged, otherwise I place them).

Evaluate average oxygen density This calculates the electron density profile of the average carbonyl oxygen

Add waters, peak pick F11 map Waters are added according to the current profile. A pop-up is generated to allow the user to decide what fraction of an average oxygen should be used as the lower cut-off:

Image

and the pop-up default is always 1. Waters are added with the Water_add command, using the fraction profile multiplier. Initially the default of 1.0 is a good starting value, but as your refinement progresses, you might need to run this option with a lower value. Each time Water_add is run, you will get a listing to see how many waters would get added for different cut-off values. If the user activates Yes, phases and maps are updated with the new waters. If No is activated, phases and maps are not updated. 

Run Refmac This starts a background Refmac5 run in O’s job system. When it is finished, the results can be automatically incorporated into the O session, by clicking on the relevant macro in the Jobs-menu. The new coordinates are read into O with a new molecule name which has been incremented, and new phases and maps calculated (see ‘A-Z of O’ for details).

Run Chop Refmac This starts a background Refmac5 run in O’s job system. When it is finished, the results can be automatically incorporated into the O session, by clicking on the relevant macro in the Jobs-menu. The user is shown the relevant zone as well as a a new map calculated around the zone. If accepted, the new coordinates for just the relevant zone are merged into the O molecule; the rest of the molecule is unchanged (see ‘A-Z of O’ for details)


2.2.6 Averaging maps blind

Averaging is a powerful tool in the crystallographer's box of tricks. It can be a bit overwhelming, however, as one can see from the figure:

Image

This blind makes it much easier to carry out the above activities. The averaging-related blind, therefore, provides access to O’s tools that allow the user to easily work with NCS-symmetry to average electron density maps:


Image


Note that this blind assumes you have a loaded molecule that consists of the NCS-asymmetric unit, and the relevant NCS-operators. If you do not, there is a command to read in a PDB file containing the complete crystallographic asymmetric unit (‘PDB from Refmac’), which will generate the relevant NCS-molecule and operators. If your structure has been refined with strict NCS-constraints, PDB_read will take care of handling NCS-operators. The blind is not suitable for starting off with an experimental map where you know neither the NCS-operators, nor the mask boundary of the NCS-asymmetric unit.


The macros that make up this pane fix certain names associated with masks and averaged maps. These can be listed by clicking on the first item in this blind:

Show symbols

This generates the current set of symbols associated with the blind e.g.


  As4> Here are the relevant symbols for averaging.

 As4> The molecule (phases or to generate a mask): m2

 As4> The unaveraged F21 or experimental map: f21

 As4> The unaveraged F11 map, if relevant: f11

 As4> The HKL project: nati

 As4> The HKL resolution: 2.0

 As4> The mask is called MASK

 As4> The average F21-style map is AV21

 As4> The average F11-style map is AV11

 As4> The SFs are sharpened as appropriate

 As4> Outliers are removed (if difference > 5 RMS)


The F21 and F11 symbols are those defined by the ‘Symbol setup’ blind but the averaged maps and mask have fixed names. Some of the actions in this blind are quite complicated macros which I will not describe in detail.


Make molecular mask This creates a mask around the complete reference chain of the molecule. Two mask layer expansions and contractions are made to fill up any holes.

Add layer to mask This will add another layer to the existing mask.

Strip layer from mask This will strip a layer from the existing mask.

Average, no expansion This averages the F21 density into the volume corresponding to the mask. I call this zero-cycle averaging.

Average, full cycle This does a full cycle of averaging. The F21 map is averaged, expanded into the whole cell, new phases calculated, outliers removed (5 RMS units), sharpened, and a new map calculated. Two maps (F21 and AV21) are, therefore, available for inspection. The F21 map is usually less sensitive to masking errors. If the mask has an error, the density in the AV21 map will be severely affected.

Average, Diff.Fourier This averages the F11 density into the volume corresponding to the mask. It is well worth doing to locate solvents, ligands that are related by the NCS-operators.

PDB from Refmac This reads in a PDB file that contains multiple chains of NCS-related coordinates (as one gets from Refmac). The user is prompted for the file name; the molecule name symbol is incremented and assigned to the  new molecule. 


NB if you make a mistake, the symbol name will be wrong as in this deliberate error:

 As2> Symbol has new value: m3

 As2> Prompt> PDB file name: m3.pdb

 Util> File not found in path: m3.pdb

 Util> File not found

 Lsq > Molecule does not exist, abort.

 Lsq >  M3           is not a visible command.

 O > sym_list *

 New> REBUILD_MOL  m3

 New> REBUILD_F21  f21

 New> REBUILD_F11  f11

 New> HKL_PROJ     nati

 New> HKL_RESOL    2.0

 New> .ID_M        M2

 New> .ID_R        A501

 New> .ID_A        C14

 New> .ID_Z        A718   A501


Use Symbol_defin to reset the symbol to M2 in this case:


 O > symb_def REBUILD_MOL m2

 O > sym_list reb*

 New> REBUILD_MOL  m2

 New> REBUILD_F21  f21

 New> REBUILD_F11  f11


Or the Symbol-blind pop-up


PDB write, all NCS-chains This writes out a PDB file (<mol>_chains.pdb) containing coordinates of ALL NCS-related atoms that are expanded, via the NCS-operators, from the NCS asymmetric unit. Such a file would be suitable for using in Refmac or in another refinement program where NCS-restraints would be appropriate.

PDB write, 1 chain & ops This writes out a PDB file (<mol>_1chain.pdb) containing coordinates of one chain together with NCS-related operators. Such a file would not be suitable for using in Refmac but could in another refinement program where NCS-constraints would be appropriate.


2.2.7 Grab guide blind

 This blind allows the user to manipulate a small zone of residues using O's main-chain database via the Grab_guide command. It provides the user with simple access to the various options as well as the possibility of restoring backups of the coordinates. This command can be useful when you have a very poor region in your model and where you feel you have to rip it apart. The less violent Loop-commands have a blind of their own, which is available from the Skeleton mast-menu.


Image


After activating the command with Grab a CA zone from the menu, the user is prompted to define the start and end residues for the zone. Two objects are then created; CA contains the central atom object of the zone and SEQ will contain the sequence/residue names. If the user wishes to make use of the existing CA coordinates, one should now click on Set mode all CA's. If one now clicks on an atom and grabs it, the zone will get updated with main-chain fragments as you move the atom. The SEQ object containing the sequence-related text will also get updated as you move the atom around. Click on Accept changes when you are happy or Undo changes to return to the start coordinates.


Image


If the starting coordinates are very poor, you can have a little bit more fun. The basic idea is that the atom you grab, as well as the start/end atoms in the zone, are guide points for the database search, and the other residues in the zone are not. This is the default mode of working with the command. If you identify a CA it will be drawn in magenta to indicate it is a guide atom. The strategy, therefore, is to decide that the CA of a particular residue is associated with a particular piece of density and then move it there. Everything else will jiggle around to accomplish this. Next, select where another CA is to go and move it. The first guide atom, stays (roughly) where it was. When you have finished guiding things, you might want to switch mode back to the Set mode all CA's to make the final placement. Alternatively, if you find that you have generated too many guide atoms, you can click on Set mode alternate points to generate more freedom for the database search.


Image


The various macros in this blind that are associated with this command, merely set new values in the database for .grab_integer with values 0, 1, 2, 3 for modes guide points, all CA's, alternate points, and accept changes, respectively.



2.3 Master Menu Skeleton (121106)

2.3.1 Getting Started

The following image shows the Skeleton master menu:


Image

Figure 2.3.1 Skeleton Master-Menu showing each of the associated blinds


SIx blinds are available to assist with the different stages of working with skeletons, generating a TRACE, then decorating the trace with sequence of your new structure, and improving your loops.


2.3.2 Setup & Making the skeleton blind

Before working with editing and building tools in this master-menu, you HAVE to specify a number symbols which will tell O the name of the molecule you are working with, maps etc. If you want to understand how symbols work in O, take a look in ‘A-Z of O’, which is available from the link at the top of this page or otherwise via the web. This blind allows you to set the various symbols that are used by the Skeleton Master-menu, to read in suitable TRACE-related data suitable for working with proteins or nucleic acids, and to skeletonise the electron density map. The master-menu makes use of 8 symbols, and it is best if they are all set before working with the other commands in this master-menu. Sometimes, the user may want to change just a particular symbol, so their definition is made by 5 smaller pop-up menus rather than one big one. All symbols start with the text skel, so you can easily see the current values at the terminal interface:


 O > Symbol_list skel*

 New> SKEL_MOL     av

 New> SKEL_RAD_MC  50

 New> SKEL_RAD_MSC 30

 New> SKEL_RAD_SYM 80

 New> SKEL_MAP     av

 New> SKEL_LEV     1.5

 New> SKEL_RAD_MAP 60

 New> SKEL_NEW     p2


or you can list them from the menu by clicking on ‘List symbols’. Here is the listing that would result:


 As4> ...

 As4> Here are the relevant symbols for skeleton work.

 As4> The experimental map to be skeletonized:  av

 As4> The level at which map is to be skeletonized

 As4> (in RMS units):  1.5

 As4> The map radius

 As4> (if skeletonized within a sphere): 60

 As4> The skeleton molecule:   av

 As4> The radius for drawing main-chain skeleton atoms:  50

 As4> The radius for drawing all skeleton atoms:  30

 As4> The radius for instancing the skeleton object:  80

 As4> The new molecule that will get built: p2

 As4> Entries for the new molecule must exist in the ODB

 As4> Here they are

 Heap>  P2_CELL                   R W         6

 Heap>  P2_ATOM_XYZ               R W      3162

 Heap>  P2_ATOM_B                 R W      1054

 Heap>  P2_ATOM_WT                R W      1054

 Heap>  P2_ATOM_Z                 I W      1054

 Heap>  P2_ATOM_VISIBLE           I W      1054

 Heap>  P2_ATOM_SELECT            I W      1054

 Heap>  P2_RESIDUE_NAME           C W       132

 Heap>  P2_RESIDUE_TYPE           C W       132

 Heap>  P2_ATOM_NAME              C W      1054

 Heap>  P2_RESIDUE_POINTERS       I W       264

 Heap>  P2_RESIDUE_CG             R W       528

 Heap>  P2_DATE                   T W        25

 Heap>  P2_CONNECTIVITY           I W      1552

 Heap>  P2_ATOM_COLOUR            I W      1054

 Heap>  P2_RESIDUE_IRC            I W       132

 Heap>  P2_MOLECULE_TYPE          C W         2

 Heap>  P2_MOLECULE_CA            C W         1

 Heap>  P2_MOLECULE_CA_MXDST      R W         1

 Heap>  P2_BOND_DISTANCE          I W      4224

 Heap>  P2_BOND_ANGLE             I W      7000

 Heap>  P2_TORSION_FIXED          I W      3282

 Heap>  P2_TORSION_FLEXIBLE       I W      3132

 Heap>  P2_SYMMOP                 R W        48

 Heap>  P2_RESIDUE_2RY_STRUC      C W       132

 Heap>  P2_RESIDUE_PEPFLIP        R W       132

 Heap>  P2_RESIDUE_B              R W       132

 Heap>  P2_RESIDUE_RSC            R W       132

 Heap>  P2_ATOM_BUILT             I W      1054

 Heap>  P2_RESIDUE_GEOMETRY       R W       132


Setup skeleton objects

Image

Activates a pop-up to set the name of the skeleton molecule (initially generated from the electron density map and then probably modified by the user) and 3 radii associated with 3D objects generated from the skeleton. One radius is used to create an object (<skel_name>_MC) showing what the user considers to be the main-chain skeleton, another is a radius of an object showing all skeletons atoms (<skel_name>_MSC, i.e. main- and side-chain skeleton atoms), and then an object showing symmetry copies of the main-chain object.


Setup skeletonization

Image

This pop-up is used to specify the electron density in the FastMap system, the skeleton molecule, the radius in which to make the skeleton and the base level at which to skeletonise. More information on how skeletons can be generated from electron density maps is provided in ‘A-Z of O’ (Skeleton command) and ‘How to work with skeletons’. 


Sequence setup

Image

The Decorate step, when we actually build the molecule of interest, requires that we have all the necessary data structures for the molecule in place. This requires that we specify the protein sequence, which gets expanded into the required entries in the user’s database (using the Build_init command). This pop-up sets the molecule name and requires a file containing the sequence, provided as 1 letter code. The molecule name is not prompted with the current value of the appropriate symbol; this is to ensure that the user consciously decides to initialise the entries for the specified molecule. 


The one letter codes must match with those in the stereochemistry database, and you will be warned if more than one residue uses the same single letter code. If a code is given that does not match a residue in the database, the command will abort. Here I have deliberately made an error in defining the sequence:

O > $ cat 1letter_seq

IAPQRSCWLP

XTSSUGHYP


and then activated the pop-up with this file:

 As2> Macro will be activated.

  Build_init av 1letter_seq

 New> Number of residues     19

 New> Unrecognized 1-letter code: X

 New>  There were      15 different residues

 New>  There were       5 problems in conversion

 New> Specify 3 letter code for A : ala

 New> Specify 3 letter code for C : cyh

 New> Specify 3 letter code for X : 

 New> Unable to continue, command is aborted....


My file had amino acid, single letter codes and some of them had potential problems. A stands for ALA (alanine) and A (RNA adenosine) in the standard stereochemistry database and so O issues a warning and asks for a 3 letter code. The user has also been warned that there is no residue in the standard stereo_chem.odb file with the 1-letter code X. If I had wanted to, I could have specified a 3 letter code for residue X, but since I didn’t O aborts the option.


There are 3 SST setup options for setting up the relevant Trace-related data for proteins, RNA, or DNA. If you have a protein/nucleic acid complex, you have to trace them one at a time. These options just read in the relevant files from the user’s ODAT directory; here I’ve loaded the protein data:


 Heap>  A poly-alanine molecule of 700 residues for SST commands

 Heap> 980520 Taj

 Heap> 081003 Include connectivity

 Heap>  Database compressed.

 Heap>  Database compressed.

 Heap>  Database compressed.

 Heap>  Database compressed.

....

 Heap>  trace_2ry.odb contains SST and related molecules

 Heap>  050814 alph5 added

 Heap>  031030 Taj, PEP containing CA,C,O,N+,CA+ for use by some O commands

 Heap>  980520 Taj, contains 4 SST molecules (beta5, 7 & alph7, 9)

 Heap>  Database compressed.

 Heap>  Database compressed.

....

 Heap>  Database compressed.

 Heap>  Database compressed.

 Heap> end of trace_2ry.o


Two more options allow you to skeletonize your electron density via their respective pop-ups:


Image


Skeletonize all map makes a skeleton of all of the map at a particular base level, while Skeletonize in sphere uses the map points within the specified radius of the current screen centre. When working with skeletons, you want the density to cover your molecule, and you want the skeleton to be localised to just one complete molecule. If the electron density is just an asymmetric unit, or depending on where your molecule sits within the volume of your map, you might have to skeletonize your density a number of times, re-centring each time on your molecule. If you find that you are using too low or too high a skeletonization level, you can redefine that particular symbol. so setting a value of 2.0 instead of 1.5 would produce a skeleton with fewer bones atoms, and probably less branches.


Activating either of the skeletonization macros will also set the current screen centre to the molecular centre ODB entry used by other commands in this master-menu. Two new objects will be made; one showing skeleton atoms that have been classified as main chain (AV_MC in this example), and the other showing main-chain and side-chain atoms (AV_MSC). See the ‘Bones overview  in ‘A-Z of O’ for an explanation of colouring and classification of the skeleton atoms. With the default colour values, potential main-chain atoms are coloured cyan and have an atom type of 3, while side-chain atoms are red and code 2.


2.3.3 Auto build blind


This blind contains just one pop-up Make 2ry framework at the moment:


Image


to generate a framework for identifying secondary structures elements from an experimental electron density map in one pass  using the Auto_2ry command (see A-Z of Ofor more details). This algorithm is 1-2 orders of magnitude faster than the first attempt at this (Kleywegt & Jones, 1997; Acta Cryst. D53 179-185) and is faster, more quantitative, and otherwise more successful then the Sprout-commands that have been available in O since ~2003 (Jones, 2004; Acta Cryst. D60 2115-2125). The command produces a new electron density map (called 2ry in the FastMap system) which is usually much easier to interpret than the input map. This map is skeletonized at an arbitrary value of 2.5 units to produce a new Bones molecule also called 2ry. Since these are standard maps and molecules, the map can be re-skeletonized at a different level set by the user. The skeleton can, of course, be edited with the usual tools. As a byproduct of the calculation, helical and strand segments are built from 5-mers and 3-mers respectively and added to the TRACE molecule. 


2.3.4 Edit skeleton blind

See How-To-Use-Skeletons for a description of why and how we use skeletons to trace a new structure in an electron density map. Here, I will concentrate on describing the tools.


A new skeleton will contain ‘errors’ that need to be fixed. These so-called errors depend on the map being studied but can arise because of phasing errors, or the limited resolution of the diffraction data. The changes that you can make to a skeleton include moving skeleton atoms around, modifying the connectivity, re-assigning skeleton class codes. The latter are used to indicate where you think you have main-chain and side-chain atoms. The codes get mapped to colours. More complicated schemes have been used, to indicate area where one is sure of the trace, for example, but the master-menu has been deliberately kept ‘simple’. The connectivity is changed to eventually produce a single main-chain trace through the map and to indicate where there are side-chain branches. In higher resolution electron density maps, there are also branches for peptide oxygens, for example, as well as larger branches for groups of side-chain atoms. O is able to recognise carbonyl branching during the building of a poly-alanine chain during the decoration stage, so you don’t have to worry about them if you have them, and you don’t have to worry about making carbonyl branches if you don’t have them. It always helps, however, if you indicate side-chain branches. Here are the actions available from this blind:

Grab an atom activates the Grab_atom command to allow the user to move an atom anywhere you want under the control of the mouse.

Set to molecular centre the coordinate of the molecular centre is stored in the ODB in the entry MOLECULE_CENTRE and is used as the origin for the calculation of the 2 skeleton objects. It is first defined when skeletonizing the electron density map but can be updated to the current screen centre at any time.

Add a branch This allows you to indicate a side-chain branch point, or gets you another skeleton atom that you grab and move around.

Make a bond draws a bond between two atoms

Break a bond removes all connected bonds between the two identified atoms

Set to main-chain set the class codes for all connected atoms between two identified atoms to be main-chain, class=1, coloured yellow by default.

Set to side-chain set the class codes for all connected atoms between two identified atoms to be side-chain, class=2, coloured red by default.

Set to maybe set the class codes for all connected atoms between two identified atoms to be maybe main-chain, class=3, coloured cyan by default. This sets the codes to the values generated for likely main-chain atoms by the Skeleton command.

Undo Edit operation This will undo the last edit operation, be it a class code assignment, modification in connectivity or an atom move. There are 5 levels of undo. The Grab_atom undo returns to the state when the command was activated.

Make skeleton objects regenerates the 2 skeleton objects. One doesn’t need this since the menu activates a recalculation whenever it is needed but you never know what a user is going to do.

Show main-chain modifies what objects are being displayed to show the current main-chain skeleton.

Show side-chain modifies what objects are being displayed to show the current main- and side-chain skeleton object.

Show symmetry shows the crystallographically related copies of the <skel_mol>_MC object. This is done by instancing the object and atoms in this object (called SYM_<mol>) cannot be identified. The command is there to help you see the packing and to stop you from moving into a symmetry copy.


2.3.5 SSTs blind

SSTs are Secondary Structure Templates and can be used to help you make the most of your skeleton; again look at the HowToUseTemplates page for an introduction. Here you will have access to all the tools you need for working with them. SSTs are short, regular fragments that lack sequence information but have directionality. For proteins, the fragments are poly-alanine residues for proteins, or poly-C for nucleic acids. Their directionality is only defined within the context of each fragment. The fragments are stored in a molecule called TRACE that has most of the atom and residue properties of a normal molecule.

Mea culpa: as I prepare this, I note that I have (not for the first time) concentrated on tracing proteins in this menu; I’ll add nucleic acid but drop me a line to remind me if this is important to you.


Image


Most of the commands in this menu map to a single O command.

Add ALPHA-9 to TRACE this commands adds a new fragment corresponding to a 9 residue alpha-helix to the TRACE molecule. The user has to identify a skeleton atom and then a complete rotational search is made to find the orientation of the helix that best fits the density (SST_build).

Add ALPHA-7 to TRACE ditto for 7 residue alpha-helix.

Add BETA-7 to TRACE ditto for 7 residue beta-strand.

Add BETA-5 to TRACE ditto for 5 residue beta-strand.

Remove an SST remove an SST fragment from the TRACE (SST_remove).

Trim end of an SST trim an end of an SST fragment from the TRACE (SST_trim).

Split an SST split an SST fragment from the TRACE into two parts (SST_split).

Flip around an SST flip an SST fragment from the TRACE (SST_flip), a rigid body fit to the opposite directionality.

Reverse an SST reverse an SST fragment from the TRACE (SST_reverse), reverse directionality of the CA atoms and use the main-chain database to built it.

Merge SST into molecule merge an SST fragment from the TRACE into the molecule getting built (SST_merge). N.B. this is not the way to trace a large portion of your structure, that’s best done with the Decorate blind. Sometimes, however, it is useful to build a portion of your structure from a perfect little helix or something. If the TRACE fragment is too long, you will get out-of-register errors.

Combine two SSTs combine two fragments from the TRACE, following the skeleton to connect them (SST_combine). N.B. this is not the way to trace a large portion of your structure, that’s best done with the Decorate blind. I have used this option when building in low resolution to combine perfect but non-overlapping helical segments (probably trimmed to fit) into a single longer helix. 

Extend an SST extend an SST fragment from the TRACE by following the skeleton (SST_extend). N.B. this is not the way to trace a large portion of your structure, that’s best done with the Decorate blind.

Zap ALL SST’s remove all SST fragments from the TRACE (SST_zap). The TRACE molecule is NOT deleted, but the fragments are removed.

Grab an SST>move an SST fragment from the TRACE as a rigid body (Grab_group).

Optimize SST fit an SST fragment from the TRACE is automatically fitted to the electron density as a rigid group (Fm_RSR_group)’

Undo SST operation Undo any of the above SST-related operations. There are 5 levels of undo.

Draw CA TRACE make a CA drawing of the current trace, in object TRACE.

Draw TRACE make an all atom drawing of the TRACE, in object TRACE,


2.3.6 Decorate blind 

Once you have a single, as long as possible TRACE fragment, one can start thinking of how the sequence can be threaded to it. This blind allows you to do this starting from either a skeleton or the TRACE, and also allows you to build a TRACE from a skeleton (and optional bits of SSTs). This blind also allows you to control the Decorate interaction step in the threading. The blind, therefore, allows you to go fully automatically from an edited skeleton to a suggestion for how to place the sequence, to then fine-tune the suggestion and build the molecule.


Image


Decor overview a very brief introduction to the blind; it also tells you the names of skeleton, map and molecule:

 As4> Decorate Overview

 As4> These commands allow you to generate a poly-ala TRACE and thread

 As4> the sequence of your molecule onto it.

 As4> 'Decorate the skeleton' needs a skeleton that has a single path

 As4> from where you plan to position the N-terminus to the C-terminus.

 As4> If your TRACE molecule already contains SSTs, they can be

 As4> incorporated into the new TRACE that gets generated.

 As4> When finished, you should see a thread of the sequence onto the

 As4> TRACE molecule. You can now modify this thread by forcing the

 As4> dynamic programming algorithm to associate a particular residue

 As4> in the TRACE with a position in the sequence. This is done

 As4> with the 'Fix a residue in sequence' option. If you are not

 As4> happy with a fixed residue, it can be set free again with

 As4> 'Free previously fixed residue'

 As4> Once you are happy with the thread, click 'Accept threading'

 As4> to merge it into the molecule getting built.

 As4> 'Decorate, no fitting' also decorates the skeleton but does

 As4> not optimize the fit of the poly-alanine TRACE to the density,

 As4> nor calculate the goodness-of-fit values of the amino acids to

 As4> the TRACE. The thread that is shown will need to be corrected

 As4> with the 'Fix a residue' command.

 As4> If you want to make the decoration in stages, then build

 As4> the poly-ala with 'TRACE the skeleton', change it (if you want

 As4> with commands in the SST blind), and then thread the sequence

 As4> with 'Decorate the TRACE'

 As4> If you decorate a skeleton, the TRACE molecule will be changed.

 As4> If you accept a decoration, your molecule getting built will

 As4> change.

 As4> Use the Undo commands to restore changes to the TRACE molecule

 As4> or the molecule you want to build.

 As4>  As4> Here are the relevant symbols:

 As4> The skeleton is             : av

 As4> The electron density is     : av

 As4> The molecule to be built is : p2


Decorate the skeleton this goes fully automatically from start and end points in a connected skeleton to a TRACE, and then a suggestion for how the sequence can be threaded on the TRACE. This is a totally new Decor_easy with a new main-chain building algorithm that has not yet been published. It is not only better then the old version ( used in Ov12) but faster. If you have already built bits of the TRACE, you can choose to use them. With a low resolution map, I still prefer to decide on the helices myself (I’ve worked successfully at ~5 Å with a cryo EM map). This option also does a real-space refinement of the TRACE, which you might not want to do at low resolution. In this case, I would use the Decor_fast command that is activated by the next entry in this menu.

N.B. the order of identifying the skeleton atoms is CRITICAL in determining chain directionality in the TRACE and the decoration.

Decorate, no fitting this also goes fully automatically from start and end points in a connected skeleton to a TRACE, and also presents a suggestion for how the sequence can be threaded on the TRACE. However, in this case, the intermediate TRACE does not undergo a real-space refinement step, and the goodness-of-fit calculation for how each amino acid fits at each residue on the TRACE is NOT calculated. This activates the new (Ov13.1, 101201) Decor_fast command, which builds secondary structure segments and connecting loops using the same algorithm as Decor_easy. The threading that is shown on the TRACE merely places the first residue in the sequence at the first residue in the TRACE and so on throughout the TRACE. This threading has not made use of the electron density and will almost certainly be wrong. The chain directionality has again been set by the order of defining start and end points in the skeleton. If a real-space refinement of your TRACE is likely to do more harm than good (e.g. at low resolution, or in bad maps), I would recommend using this option rather than Decor_easy, which is activated in the entry above this one in the Decor blind.

Accept threading accept how the current threading of the sequence is made to the TRACE and use this to build your molecule, including all gaps between secondary structures. Decor_slider should be running when you have clicked here.

Fix residue in sequence with Decor_slider running, this command allows you to force that a particular residue in the TRACE is a certain residue in your sequence (O command Decor_fix). Fixed segments are indicated by white text in the sequence that decorates the TRACE.

Free previously fixed residue remove a particular fix (O command Decor_free).

TRACE the skeleton this is the starting subset of the Decor_easy command and builds a TRACE molecule after the user identifies 2 connected skeleton atoms (O command Decor_step_1).

Decorate the TRACE this is the latter subset of the Decor_easy command and uses an existing TRACE molecule. This TRACE must have only one fragment in it. The fit to the density is optimized, the goodness-of-fit at each residue in the TRACE is evaluated, and the Decor threading is made to present the optimum placement of the sequence on the poly-ala chain (O command Decor_step_2). See my comments above about very low resolution building.

Undo the TRACE 5 levels of undo to the TRACE molecule

Undo the accepted threading 5 levels of undo to the molecule that is getting built.


2.3.7 Rebuild loops blind 

if O has to force extra residues into loops while following the skeleton, you might have some serious rebuilding to do. This blind introduces you to the Loop-commands, which are less frenetic than the Grab_guide command. The Loop-commands can be used to make some vigorous changes to your model, however, so read on.

These commands define a loop as a zone of residues connecting the end and start points of abutting secondary structural elements. It will be at least 3 residues in length, including the end/start residues of the secondary structure elements.


Image


Overview provides a brief overview of the blind:

 As4> Loop Overview

 As4> These commands allow you to make major changes to a localized

 As4> part of your structure.

 As4> You would use these commands, for example, after an initial

 As4> build with the Decor system in parts where there are errors

 As4> in the CA placements.

 As4> Using Grab_build to fix them is one way, but here we use Grab_atom

 As4> to modify the CA's, and then the database commands to remake it.

 As4> If the Decorate commands were used properly, only the loop regions

 As4> would need this rough rebuilding; hence the name.

 As4> Obviously, you are not restricted to loops; you can define

 As4> any segment you like.

 As4> Start by clicking on 'Setup', to make objects and define the

 As4> loops. Then move through each loop, or jump around as you wish.

 As4> Once you are happing with the improved model, you might want to

 As4> use Grab_build for the final touching-up.

 As4> If you don't like a change to the loop, use the 'Undo' command


Setup this YASSPA’s your molecule, then makes the first LOOP object for you, starting at the N-terminal region. This CA object is decorated with your sequence to help you place the Ca’s.

Next loop moves to the next loop in your structure

Your own loop identify two atoms to define your own ‘loop’ (then uses O command Loop_define)

Grab atom active Grab_atom to move around the CA atoms.

Update text update the placement of the sequence text

Rebuild from CA’s use the main- and side-chain databases to rebuild the loop

Fit rotamers real-space fit rotamers in the loop (O command Fm_rsr_rotam)

Fit RSR real-space fit the loop (O command Fm_rsr_zone)


2.4 Master Menu Make a Ligand (QDS)

Image


Quick and Dirty Sketcher master-menu contains a number of O commands to generate coordinates for small molecule ligands with a point and click interface. QDS is able to generate restraint entries for bonds, angles and torsion angles as well as the relevant entries for using Tor_residue. This means that the full strength of the Grab_build system can be used for electron density fitting and for general  modelling. The amount of knowledgeable chemistry in QDS, however, is rather small. It might, therefore, be necessary to edit the dictionaries that are generated by the system. Once you are happy with the dictionary, you might want to add it to your stereo_chem.odb file, or it can be kept separate since a text ODB (called <residue_type>_bonds_angles) containing the same information can also be directly generated in the O database of the user.

QDS has an explicit undo capability; it does what you tell it, and then you have a chance to undo the action. There are 5 levels of undo. Perhaps there should be more. I implement the undo feature by writing out all ODB entries associated with the molecule to an O binary database file. The QDS-molecule name is part of the file name, as is an integer in the range 1-5. For example, if the ligand is called LIG, the undo feature will generate up to 5 files with names like backup_lig_<value>.o where <value> is 1, 2, 3, 4 or 5. The files are stored in the OTMP directory.


New molecule  to create a new molecule with QDS. The user is prompted for a molecule name and residue type (QDS_setup). The user should set the atom type (by clicking on one of the 15 atom types at the bottom half of the menu) before starting a new molecule.

Extend from ID extend the developing molecule by one atom (QDS_extend). The currently set atom type is listed in the atom information line in the 3D window in the form ‘QDS atom type is C_SING’, for example. The user should ensure that this is the desired atom type before identifying where you want to extend. You can set the atom type before or after clicking on Extend from ID. After identifying an atom, the molecule is either updated with the relevant stereo-chemistry or the user may be prompted to clarify the stereochemistry of a branch, for example. The default stereo-chemistry (including tom types) is defined in qds.odb which was automatically loaded into the user database.

Make ring forces ring closure between the 2 identified atoms (QDS_ring). The molecule may be distorted and new regularizing to fore good geometry (Regularize & colour).

Undo action undoes the last action, up to a depth of 5 undos.

Regularize & colour regularizes the current molecule and redraws.

Save stereochemistry writes a file called <res_type>_stereo_chem.odb to the file system and creates an identical entry in the user database called <res_type>_bonds_angles containing the necessary dictionary items to work with this residue type in O.

Save to PDB file generates a PDB file of the molecule in the file system. This could be cut and paste into an existing PDB dataset, for example, which lacked the necessary ligand under study,


2.5 Master Menu Font Selection


Image

This menu allows the user to customise the font used in the GUI. The default is 12 point Helvetica. Only the User Menu changes at first, but as menus get remade and atoms identified, the new font will be used. The wider fonts might be useful if you have a high pixel density display.