OVERVIEW

INTRODUCTION

The current program incorporates functions from the CCP4 (Collaborative Computational Project, Number 4, (1994)) and/or the MOSFLM suite (Wonacott, Dockerill & Brick (1980), Leslie (1992)) programs OSCGEN, UNIQUE and COMPLETE (the function of the latter now incorporated in MTZDUMP). The general treatment of the goniometry is derived from that used in the MADNES program (Messerschmidt & Pflugrath, 1987). The program makes also use of the XDL_VIEW toolkit (Campbell, 1995), library routines from the Daresbury Laboratory Laue Software Suite (Helliwell et al., 1989) and the CCP4 libraries.

The program is in the process of an on-going development. Consideration is being given to the possibility of integrating the use of the program, perhaps in a re-packaged form, with the PXGEN interface used on PX stations 9.5 and 7.2 at the Daresbury SRS (Kinder, McSweeney & Duke (1996). It is intended however that a standalone version will also be retained.

Details of setting up the program can be found in Appendix 1.

In the description of program menus, the menu items available are generally indicated by the menu button label enclosed in angled brackets.

e.g. <Rotation Simulations> or <Return to Previous Menu>

The user should assume that any prompt/reply sequences take place in the main text input/output window of the program (see below) unless otherwise stated. Errors (or warnings) may either be indicated by messages (to the main text input/output window of the program unless otherwise stated) or pop-up notices; the description 'message' in the text indicates the former and the description 'notice' indicates the latter.

List of sections:

Running the Program
Introduction to XDL_VIEW
Screen Layout
Some Basic Concepts
Outline of the Main Options
The Command Window
References

RUNNING THE PROGRAM

Normally the program may be run by typing the command rotgen though this will necessarily depend on how the particular system, on which the program is being run, has been set up. Note also that the environment variable or logical name SYMOP must point to the CCP4 space group symmetry operators file (see Appendix 1). By default a log file named rotgen.log will be created. A few parameters, including the name of the required log-file may be set to non-default values either by setting an environment variable (or logical name under VMS) and/or via a command line argument. Specifications in the command line override any specifications made via environment variables if both are defined.

The following options are available:

1. Setting the log file name

   A new log file name may be selected by setting the environment variable (logical name) ROTGEN_LOG to the name of the required log file. If the value is 'none' no log file will be written unless specified in the command line arguments. To specify a log file name via the the command line give the switch -l followed by the log file name.

2. Setting the default orientation for simulations

   A new default value for the simulations orientation may be set via the environment variable (logical name) ROTGEN_ORIENT. Valid values are 'ipdisp', 'denzo' or 'oscgen' (case insensitive). To set the default orientation via the command line, give the switch -o followed by one of the code strings given above. If no valid option is set via the comand line arguments or the environment variable, the program default is the 'ipdisp' orientation. (Note: the apostrophes are not part of the code strings)

3. Setting a different font

   A different size of font to be used for the parameter tables, menu area, io-window etc. may be chosen by setting the environment variable ROTGEN_FONT to a value from 1 to 5. The default value is 2. (See also the XDL_VIEW documentation on how to reset the 5 fonts and font sizes used by that package). The font size cannot be selected via a command line argument.

4. Changing the parameter updates policy

   The parameter updates policy (described below) may be changed by setting the ROTGEN_UPDATE environment variable or via the -u command line flag. Valid values for the environment variable or keyword following the flag are 'yes' (the default), 'no' or 'warn'.

Example of setting options via command line arguments:

rotgen -l lys_rot.log -o denzo

Other command line arguments for setting the program mode (not currently relevant) are described in Appendix 1.

INTRODUCTION TO XDL_VIEW

XDL_VIEW is a set of X-windows based routines providing 'view-objects' for various functions such as menus, parameter tables, image displays and text input/output.

View-objects, which can return data to the calling program, will normally contain an 'active strip'. This indicates whether or not the program is currently awaiting input from that object. It consists of a square at the left hand side and a rectangle at the right hand side, usually stretching across the width of the view-object. When the program is ready to receive input from the menu, then the square is filled with green (or black on a black and white display) and a message is displayed in the rectangle. When the program is not waiting to receive input then both parts of the active strip are cleared. A program may be waiting to receive input from more than one view-object at a time and from different view-objects at different times and hence the reason for indicating to the user the current 'active/inactive' state of any particular view-object.

The view-objects are basically designed for use on a colour display but will work, with limitations in some cases, on a monochrome display. For ROTGEN, a colour display should be used if at all possible and the documentation assumes the use of such a display.

Default fonts will normally be used but some user selection is possible (See Appendix 1).

Reference should be made to Volume 1 of the XDL_VIEW documentation to find detailed instructions on how to manipulate the various view-objects used by the program.

Note:

When running an XDL_VIEW based program such as ROTGEN, do not attempt to dismiss any of the windows displayed using the window manager options as this will cause the whole program to exit. ROTGEN is designed so that all windows will be automatically deleted by the program when appropriate.

SCREEN LAYOUT

The basic screen layout for the program is divided into five areas.

Figure 1 Main Screen of ROTGEN

Top Left

A menu area used for selecting the options currently available. The options within a menu are, in general arranged such that the normal order of access would be from the top downwards without necessarily using all the options available. The basic menu structure of the program is hierarchical and most menus have an item at the bottom which returns the program to the previous level with a label such as <Return to Main Menu> or <Return to Previous Menu>

Top Right

Main parameter table. This is an editable parameter table which contains the main crystal/detector parameters.

Bottom Left

Parameter table 2. This area is used for special purpose parameters relating to the current option selected.

Middle right

This area is the main text input/output window. This is used to output textual information from the program when required and also, at some stages, for prompt and reply sequences e.g. for inputting file names.

Bottom Right

Command window. This window is for inputting program options and parameters via a command line. Keyworded parameter values may be input or inspected. It is anticipated that processing functions will be added at a later stage.

Additional windows e.g. windows for displaying Rotation simulations or graphs are used at various stages of the program. These may be positioned independently of the main program window. Normally they will initially be positioned just to the right of the menu area.

SOME BASIC CONCEPTS

1. The Parameters

   The parameters used by the program form a keyworded data set. They fall essentially into two categories:

   1. The crystal parameters such as the crystal system, lattice type, cell parameters, crystal orientation parameters and the resolution limit of the diffraction.

   2. The parameters relating to the X-ray and detector system and X-ray source such the wavelength and the positioning of the detector.

   The parameters include specifications for one or more crystal orientations and sets of images. Some parameters refer to the dataset as a whole and some may have separate values for each of the crystal sets.

   The parameters used in ROTGEN are described in Appendix 2.

2. Current Set

   The program is designed to allow for processing data from several crystal sets. A crystal 'set' means a particular crystal orientation and a rotation range. The basic crystal form (e.g. space group) is assumed to be the same for each crystal set within the dataset. The current crystal set (and current image where relevant) may be selected via the main parameter table.

3. Resolution

   One of the main functions of the program is to analyse data coverage in terms of the unique section of the reciprocal lattice for the space group in question. The resolution used to determine the unique data is that specified for the first crystal set and this fact should be borne in mind if a different resolution limit is set for the different crystal sets. When analysing MTZ data alone, the resolution value from the MTZ data file may optionally be used instead.

4. Parameter Updates

   By default, most parammeter values, reset via the main parameter table for the first crystal set, are automatically applied to any subsequent sets. Exceptions to this are the parameters which define the rotation ranges, ROTSTART, ROTEND, ROTS2, ROTE2, ... ROTS5, and ROTE5. This updating may be disabled or changed to give a warning via a pop-up notice, allowing the user the choice of whether or not to update, by setting the ROTGEN_UPDATE environment variable or via the -u command line flag. When parameters are updated via the command window, the normal keyword conventions apply i.e. that the parameter will apply to all sets if it has no attached set specification or to a single set if a set is specifiied (see Appendix 2 for more details of the parameter keywords).

5. Program Modes

   The program is basically designed with the possibility of being run in three different modes though only the (default) interactive mode using X-windows has been developed to date. The other two modes are a terminal mode and a batch mode. It is anticipated that commands will be written to carry out some of the processing functions now done interactively. These could also be requested via the programs's command window when running in interactive mode.

OUTLINE OF THE MAIN OPTIONS

The following are the main options available in ROTGEN selectable via options in the program's main window and menu:

1. Setting up the parameters

   The parameters in the main parameter table are assigned default values when the program is started. Individual parameters may be reset by editing the values directly in the parameter table (see XDL_VIEW documentation). A new set of parameters may be read in from a keyworded parameters file using the 'Read Parameters File' option.

   Activating the 'edit' menu item associated with the 'detector--->' item brings up a new window to allow the values of detector parameters, not displayed in the main parameter table, to be edited. This new window will be automatically removed if no input is received over a period of a minute.

   When the required parameters have been set up, they may be saved in a keyworded parameters file for future use using the 'Write Parameters File' option.

2. Updating the orientation parameters.

   The 'Read Matrix File' option may be used to reset the parameters which define the crystal orientation using matrices produced following auto-indexing by programs such as REFIX or DENZO. The orientation parameters may also be written out for subsequent use with the MOSFLM or HKL (DENZO) packages.

3. Rotation simulations

   Two basic types of simulations are available, 'colour' simulations and 'interactive' simulations. In each case a window is created with a display area for the simulation, an area to list details of a selected reflection, a control panel and an area used for requesting hard copy (Postscript) output of the simulation. 'Colour' simulations show the show the rotation patterns with the spots colour coded in a number of different ways. 'Interactive' simulations are in black and white and have a slider which allow the user to investigate the effects of changing various parameters such as the oscillation range and mosaicity; spot labelling is also available.

4. Input MTZ data

   This option enables the input of previously processed data to be included in the data coverage analyses provided by the program. The reflection data must be stored in a MTZ format reflection data file (unmerged or merged). Some care needs to be taken when interpreting analyses including such MTZ data as not all the information normally used in the analyses is present in the MTZ files.

5. Analyse data

   This option enables the prediction of the reflections which would be recorded for the defined crystal sets and to analyse the data coverage in terms of the unique data for the space group, cell and resolution. The analysis may be done for either the current crystal set or for all crystal sets within the data set. The results may be presented in the form or histograms describing the data coverage or in terms of a pictorial representation of the reciprocal lattice sections. The analysis data equivalent to that displayed in the histograms is also written to the log file. The analyses automatically written to the log file exclude any spatially overlapped reflections. There are options for 'quick' analyses which examine the data coverage within the rotation range as a whole; these may be further speeded up by dividing the cell size (internally within the program) when carrying out the calculations. A further option enables an alternative and quicker analysis of spatial overlaps.

6. Strategy

   This option assists the user with determining the best rotation ranges to be used to maximise the data coverage following an orientation determination (made using for example REFIX or DENZO) for a crystal. Results are presented for both a single contiguous rotation range and, optionally, for two non-contiguous segments. There is also an option to determine a series of up to five successive rotation ranges each optimised for data collection following the collection of the previous segments. The data coverage maximised may either be for the unique data or for acentric pairs data. Options are available to analse spatial overlaps so that a suitable oscillation angle may be selected for the data collection.

THE COMMAND WINDOW

The command window is intended for use with non-interactive commands for processing the data which have not yet been developed. However it has a few useful functions available. These are:

1. Type in the command defaults to reset the program default values for the parameters and internal program flags.

2. Input of parameter Keyword/value pairs. This provides a means of inputting values of parameters which are not displayed in the parameter tables as well as those which are.

3. Showing the value of parameters including those not displayed in ROTGEN's own parameter tables. These are obtained by typing a question mark followed by the keyword for the parameter e.g.

   ?oscrange

   For crystal set specific parameters which are given without an explicit set specification, the value for the current set is shown.

REFERENCES

Campbell, J.W. "XDL_VIEW, an X-windows-based toolkit for crystallographic and other applications" J. Appl. Cryst. (1995), 28, 236-242

Collaborative Computational Project, Number 4 "The CCP4 Suite: Programs for Protein Crystallography" Acta Cryst. (1994) D50, 760-763

Helliwell J.R., Habash J., Cruickshank D.W.J., Harding M.M., Greenhough T.J., Campbell J.W., Clifton I.J., Elder M., Machin P.A., Papiz M.Z. and Zurek S. "The Recording and Analysis of Synchrotron X-radiation Laue Diffraction Photographs" J. Appl. Cryst. (1989) 22, 483-497

Kinder S.H., McSweeney S.M. and Duke E.M.H. "PXGEN: A general purpose graphical user interface for protein crystallography experimental control and data acquisition" J. Synchrotron. Rad. (1996), 3 accepted for publication.

Leslie A.G.W. In CCP4 and ESF-EACBM Newsletter on Protein Crystallography (1992) No. 26, DRAL Daresbury Laboratory, Warrington, WA4 4AD, England

Messerschmidt A. and Pflugrath J.W. "Crystal orientation and X-ray pattern prediction routines for area detector diffractometer systems in macromolecular crystallography" J. Appl. Cryst. (1987) 20, 306-315

Wonacott A.J., Dockerill S. and Brick P. "MOSFLM program" (1980) Unpublished Notes.