CCP4i developers workshop: Extending Frames...

Extending Frames and More...

Liz Potterton

Demo 1: A Simple Extending Frame

For example the definition of residue ranges in 'Define Protein Ranges to Refine' folder in the Demo Task Interface One task.

The relevant bit of the demo1.def file (hint: open this page in another window) is line 34:

NRANGES                _positiveint            0
RESTRAIN_MODE,0        _demo_restrain_mode     medium
CHAIN,0                _chain_id               ""
FIRST_RES,0            _res_id                 ""
LAST_RES,0             _res_id                 ""

NRANGES is the counter variable and should always be of type _positiveint. The four parameters for
that define refinement ranges are listed RESTRAIN_MODE,CHAIN,FIRST_RES,LAST_RES. These variables have index 0 and never appear in the interface but are used to initialise the variables which are created automatically. The variables used in the interface with have indices 1,2,3...

In demo1.tcl in the demo_task_window procedure (line 178) the extending frame for the user to enter refinement ranges is set up:

CreateExtendingFrame NRANGES demo_refine_range \
        "Define range(s) of residue ranges to refine" \
        "Add Refinement Range" \
       [ list RESTRAIN_MODE \
        CHAIN \
        FIRST_RES \
        LAST_RES ]

The arguments to the CreateExtendingFrame command are:

the name of the counter variable which keeps track of the number of refinement ranges

the name of the procedure to draw one line of the extending frame

text for the message line help

the text to appear on the 'Add whatever' button

a list of the indexed variables. A new instance of each of these must be created every time the user hits 'Add Refinement Range'

In the demo1.tcl file at line 58 is the procedure referenced in the CreateExtendingFrame call, demo1_refine_range which draws one line of the extending frame:

#---------------------------------------------------------------------
proc demo1_refine_range { arrayname counter } {
#---------------------------------------------------------------------
#procedure to draw one line of the 'refinement range' extending frame
upvar #0 $arrayname array

CreateLine line \
        message "Enter range of residues to refine" \
        label "Use" \
        widget RESTRAIN_MODE \
        label "restraints for chain" \
        widget CHAIN \
        label "from residue" \
        widget FIRST_RES \
        label "to residue" \
        widget LAST_RES
}

This procedure is called automatically whenever an extra line is drawn. This simple example just draws one line using the CreateLine command. The name of the variables are passed to CreateLine do not have any index number - it 'knows' these values automatically. But remember it is creating the widgets for RESTRAIN_MODE,1 CHAIN,1 etc..

The arguments passed automatically to the demo1_refine_range procedure are the arrayname and the value of the counter variable. In this simple example neither of these are used but the programmer may sometimes need these to make customisations.

Demo 2: Initialising Variables from Data Files

It is often helpful for users to set up default values in an interface by extracting information from one of the data files (MTZ, PDB etc.) selected by the user. See the example demo2.tcl. When the user selects a PDB file the chain names and the ids of the first and last residues in the chain are extracted from the PDB file and used to initialise the refinement ranges to cover ever chain in the PDB file. So after the user has selected the input PDB file the task window will look like this (note that the 'Required Parameters' folder has been closed to simplify the picture):

At line 180 the CreateInputFileLine command, which creates the line to select the input PDB file

CreateInputFileLine line \
        "Enter input coordinate file name (XYZIN)" \
      "PDB in" \
       XYZIN DIR_XYZIN \
       -fileout XYZOUT DIR_XYZOUT "_refmac" \
       -command "demo2_set_range $arrayname"

has extra optional arguments -command "demo2_set_range $arrayname" which means that when a user selects a PDB file the command "demo2_set_range $arrayname" is executed.

The procedure demo2_set_range is defined in demo2.tcl at line 58.

The details of this procedure are explained in the comments but the important steps are:

The utility PdbGetChains is used to extract the names of chains and first and last residues from the PDB file which taken from XYZIN.

The chain and residue id information are returned as lists which need to be copied into the appropriate array variables.

Putting default values into the array variables will not automatically get them displayed - the UpdateExtendingFrame command will force CCP4i to redraw the extending frames with the new data. This will call demo2_refine_range the appropriate number of times.

Demo 3: Creating a Variable Menu

In the previous examples the restraint mode for each of the refinement ranges was selected from a menu with the fixed options: tight, medium or loose. In this example the user is able to define their own restraint modes, give each mode a name and set some parameters for each mode. The task window now looks like this with an extra folder 'Restraint Modes' containing an extending frame for the user to define their own restraint modes. By default there is a 'normal' restraint mode defined when the task window is first opened. As the user enters new restraint modes they will appear in the menu for 'Use ????? restraints' in the 'Define Protein Ranges to Refine' folder. In the picture below the user has entered one additional restraint mode called 'tight bonds' and has changed the restraint mode for chains B and C to use this new restraint mode.

The user defined restraint mode names are used to create a menu which appears in the refinement range selection so that one of the user defined restraint modes can be selected for each refinement range. The important part of this example is to demonstrate using a variable menu.

Compared to previous examples there are some additional parameters defined in the demo3.def file. See line 34.

NRESTRAINTMODES         _positiveint            1
RESTRAINT_NAME,0        _text                   ""
BOND_RESTRAINT,0        _real                   ""
ANGLE_RESTRAINT,0       _real                   ""
RESTRAINT_NAME,1        _text                   normal
BOND_RESTRAINT,1        _real                   0.5
ANGLE_RESTRAINT,1       _real                   0.5

These are used to define the possible restraint modes. The NRESTRAINTMODES parameter is the number of defined restraint modes. It is initialised as 1 and the data is provided for one default restraint mode called 'normal'. Each restraint mode has a name RESTRAINT_NAME and two parameters BOND_RESTRAINT and ANGLE_RESTRAINT. The 0'th index instance of these variables is set to "" (i.e. nothing) so the default initial values of these parameters is nothing. The index 1 instance is given some initial values to define the 'normal' restraint mode.

Two additional parameters in the def file (line 42) are:

RESTRAINT_MENU _list "normal"
RESTRAINT_ALIAS _list "normal"

These are variables which will contain the current allowed items for the restraint mode menu. Most menus have the text which appears on the menu and then a shortened alias which is associated with each item on the menu. We will not be using this facility, the aliases will be the same as the menu items but they must be defined. The variable RESTRAINT_MENU will contain a list of items to appear on the menu and RESTRAINT_ALIAS will contain the aliases for these menu items.

The code to define the restraint mode extending frame in demo3.tcl is similar to that for defining the refinement ranges. There is a call to CreateExtendingFrame at line 266 and the procedure demo3_restraint_modes (line 166) defines the appearance of one line of the extending frame. One feature of this procedure is at line 122, if the RESTRAINT_NAME is blank then it is given a default value of 'restraint_n' where n is the number of the restraint.

The important feature of this example is the procedure demo3_update_restraints_menu (line 139) which is called whenever the defined restraint mode names are changed to update the variable menu. A temporary variable restraint_list is initialised empty and then there is (line 148) a loop over the number of defined restraint modes which appends the name of the restraint mode to the list restraint_list. The procedure UpdateVariableMenu is then called to update the values of the RESTRAINT_MENU and RESTRAINT_ALIAS variables. This procedure also forces the redrawing of all instances of the menu so that they now list the updated menu items.

The procedure is called in several places:

At the beginning of the demo3_task_window procedure before the task window is drawn to ensure that the menu correctly reflects the definition of the restraint modes read in from the def file (line 177).

At the end of the demo3_restraint_modes procedure (line 134) to update the menu when the user clicks 'Add restraint mode' and a new restraint mode line is drawn.

In demo3_restraint_modes in the CreateLine command the option (line 128)

-command "demo3_update_restraints_menu $arrayname"

ensures that the procedure is called every time the user changes a RESTRAINT_NAME widget.

The extra optional arguments to the CreateExtendingFrame procedure (line 272)

-update "demo3_update_restraints_menu $arrayname"

ensure that whenever the list of restraint modes is edited via the 'Edit List' button the variable menu gets updated.

So with what is described above we will have a variable menu defined and correctly updated but we must make some small changes to how we handle the refinement range selection parameters to ensure that they present the user with the variable menu list of restraint modes.

In demo3.def (line 49) the definition of the restrain mode for each refinement range is:

RESTRAIN_MODE,0 _demo_restrain_mode normal

The only change from the previous examples is that the initial value has been set to normal to be consistent with the options available in the variable menu.

In demo3.tcl (line 23) the data type _demo_restrain_mode has a new definition:

set typedef(_demo_restrain_mode) [list varmenu RESTRAINT_MENU RESTRAINT_ALIAS 10]

The array typedef contains the definitions of all data types and this line is setting the _demo_restrain_mode element of that array to define this data type as a variable menu with the menu items stored in the variable RESTRAINT_MENU and the aliases for the menu items stored in RESTRAINT_ALIAS. The final parameter, 10, sets the width of the menu as a number of characters. Now that the data type is correctly defined the menus for selecting restraint modes will always properly reflect the currently defined restrain modes.