CHAPTER 1 - OVERVIEW

1.1 INTRODUCTION

The program makes use of a library of X-windows based routines, called XDL_VIEW, written by John Campbell at the Daresbury Laboratory (Campbell, 1994a). The program in its original form has been described by Campbell (1994b). It has now been modified to make use of the Laue Data Module (LDM) and related developments (Campbell, Clifton, Harding and Hao, 1994). The program incorporates M. Elder's auto-indexing code from NEWLAUE. Code for handling streaky spots is based on that by T.J. Greenhough and A.K. Shrive (Greenhough and Shrive, 1994). Thanks are given to Dr M.M. Harding and her colleagues at the University of Liverpool for their continuing contribution of ideas and for carrying out user trials of the program. Thanks are also due to Dr D. Nguti for developing the LDM compatible spot finding routine and to Dr Q. Hao for developing the routines used for spot intensity integration.

Whilst the primary development of the program focussed on the interactive potential afforded by the use of an X-windows display, more recent developments include more automatic processing procedures to complement the interactive functions. These may prove to be particularly useful when re-processing data with some slighly modified set of parameters.

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. <Laue 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.

Two demonstrations are given to illustrate the use of the program LAUEGEN.

List of sections:

Introduction to XDL_VIEW
Running the Program
Screen Layout
Some Basic Concepts
Outline of the Main Options
Command Line Input
Cylindrical Cameras
References

1.2 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 LAUEGEN, 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 LAUEGEN, do not attempt to dismiss any of the windows displayed using the window manager options as this will cause the whole program to exit. LAUEGEN is designed so that all windows will be automatically deleted by the program when appropriate.

1.3 RUNNING THE PROGRAM

Normally the program may be run by typing the command 'laue lauegen ' if it is set up as part of the Laue Software Suite; this will run the program in its normal interactive mode and will prompt for a log file. To run the program in other modes, the program may be run directly with appropriate command line arguments (see Appendix 1) ; the environment variable (logical name) SYMOP must be set to point to the CCP4 symmetry operators file.

1.4 SCREEN LAYOUT

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

Figure 1.1 Main Screen of LAUEGEN

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

Parameter table 1. This is an editable parameter table which contains the main crystallographic/pack parameters which relate to the current crystal and are common for all plates of the current pack.

Bottom Left

Parameter table 3. This area is used at various stages for different tables of parameters relating to the current option selected (e.g. box size and intensity threshold when using the match spots refinement option or spot intensity integration parameters).

Middle

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

Parameter table 2. This is an editable parameter table which contains parameters relating to the current plate in the current pack being processed.

Bottom Middle

Command window. This window is for inputting program options and parameters via a command line. LDM parameter values may be input or inspected and the command line processing functions may be invoked.

Additional windows e.g. windows for displaying Laue simulations or images 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.

In some cases, the program will automatically bring a window to the front to allow user input (e.g. to reply to a question when the text input/output window is covered say by an image display) and then put it back again after the required input has been given.

1.5 SOME BASIC CONCEPTS

1. The Parameters

   The parameters used by the program are basically those of the Laue Data Module (LDM). In fact an extended LDM parameter set specific to LAUEGEN (and INTLDM) is used with new parameters being defined for the intensity integration related steps. They fall essentially into four 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 such the wavelength range and the positioning of the detector.

   3. The parameters describing the scanned images and the spots on these images such as pixel size, numbers of rasters, spot sizes and area to be processed. Distortion parameters are included.

   4. The integration related extended LDM parameters.
   The dataset and pack specific parameters appear are displayed in parameter table 1 and the plate specific parameters are displayed in parameter table 2.

   Parameters relating to the current program function are displayed, where required in parameter table 3. Where these belong to the LDM or extended LDM set of parameters they are shown in bold type. In the case of the spot_threshold parameter, this is also displayed in the parameter table 1 and may be changed from either parameter table when appropriate.

   The parameters used in LAUEGEN are described in Appendix 2 and further details may also be found in the LDM documentation.

   Laue simulations may be carried out when these parameters have been set as desired.

2. Current Pack and Plate

   The program is designed to allow for processing data from a set of packs of images. Only those parameters for the current pack and plate are displayed at any one time. The current pack and plate may be reset via the two 'current pack' and 'current plate' items at the start of parameter table 1.

3. Key Film/Plate

   For a pack with more than one film/image-plate, one of the films/plates in the pack, normally the first, is considered to be the reference or 'key' film. This film/image plate will be the one used with the auto-indexing option and will be the first one used in refinement of the crystal orientation. It will normally be the first one in the pack though there may be cases where another one is used e.g. because a film is over-exposed or missing.

4. Parameter Updates

   When parameters are updated e.g. via the parameter tables or after a refinement procedure (orientation or soft limits) or spot size determination, the values may be automatically updated for other packs/plates as follows:

   For pack dependent parameters, values updated for the first pack will be applied to all other packs.

   For plate dependent parameters, values updated for the key plate (normally the first plate) will be updated for the other plates of the pack. If the pack is also the first pack then the parameters will be updated for all packs and plates.

   These are the general rules which by default apply to all parameters except w_c and the bulge parameter. The user may change the classes of parameter which will be automatically updated by setting the LAUEGEN_UPD environment variable as described in Appendix 1 .

5. Log File

   By default the program will write a log file named 'lauegen.log'. To obtain a log file with a different name, the user may either set the LAUEGEN_LOG environment variable to the name of the required log file prior to running the program or, when the program is executed, following the program name with the code -l filename ( filename is the user chosen log file name ). To suppress the output of a log file set the LAUEGEN_LOG environment variable to the string NONE and do not give a log file name via the command line. The log file basically contains information from the program when it is in processing mode when details will also be given of the (extended) LDM parameters on entering the processing mode and of parameter changes between selected processing options. On exiting the program, the current (extended) LDM parameter values are output.

6. Program Modes

   The program is basically designed to be run in three different modes. The most common mode is the (default) interactive mode using the facilities available on an X-windows display. The other two modes are a terminal mode and a batch mode. Commands have been written to carry out some of the processing functions which can also be done interactively. These can also be requested via the programs's command window when running in interactive mode. (See Appendix 1 for how to run the program in these non-default modes)

7. Other Considerations

   A number of other areas which affect the use of the program may need to be considered by the user. These are described in the appendices and include the following:

   • Coordinate systems
   • Distortion corrections
   • File structures
   • Use of fiducials
   • Handling of the plate 'centre'
   • Image background calculations

1.6 OUTLINE OF THE MAIN OPTIONS

The following are the main options available in LAUEGEN selectable via options in the program's main menu:

1. Setting up the crystallographic/pack/plate parameter tables

   The parameters in parameter tables 1 and 2 are assigned the LDM 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 parameters file (LDM) using the 'Read Parameters File' option.

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

2. Laue 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 Laue patterns with the spots colour coded in a number of different ways. 'Interactive' simulations are in black and white and have sliders which allow the user to investigate the effects of changing the lambda-min, lambda-max and dmin soft limits; spot labelling is also available.

3. Display/Measure Image

   This option enables a film or image-plate image to be displayed with options for inputting or determining the image centre, calculating a background image and measuring spot positions. A predicted Laue pattern, based on the current parameters, may also be displayed superimposed on the image.

4. Find Orientation

   This option enables the crystal orientation to be determined by M. Elder's auto-indexing method. The option allows spot positions to be read from a previously generated spot positions file or measured from the image.

5. Processing

   The 'Process' option puts the program into processing mode and the processing menu will be displayed. Currently, the following processing options are available.

   1. Determine Spot Size

      This option enables an automatic search of an image to find spots and to determine suitable spot size parameters to be used in the processing of the data.

   2. Refine Orientation

      This option allows for the refinement of the crystal orientation, first for the key plate of the current pack and then, if required, for other plates in the pack. Options are available for visually matching calculated and observed spot positions or for automatically searching for matches for selected reflections. When the refinement is complete, the .ge1/.ge2 files may be written for use by the integration program.

   3. Improve Soft Limits.

      This option allows for the determination of improved values for the soft limits lambda-min and dmin by measuring integrated intensities for an over predicted pattern and by analysing the resultant intensities as a function of the wavelength or resolution.

   4. Integrate Spots.

      This option allows for the integration of spot intensities in a manner analogous to that of the INTLDM spot intensity integration program based on routines written by Dr Q. Hao.

1.7 COMMAND LINE INPUT

In interactive mode, commands may be input via the command window. In terminal or batch modes such commands (read from the terminal or input stream) provide the means by which the program is driven.

The command line input is intended mainly for use with non-interactive commands for processing the data. However it has a few additional functions available. These are:

1. Type in the command defaults to reset the program default values for the parameters and internal program flags (this is only valid when not in processing mode).

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

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

   ? nxrast

   For pack/plate specific parameters which are given without an explicit pack or plate specification, the value for the current pack and plate is shown.

4. When the main menu is displayed, typing the command process will put the program into processing mode and in the processing mode, typing the command end will return the program to the main menu.

5. Changing the current pack and/or plate numbers. The command pack or plate followed by the required pack or plate number respectively is given. These commands may, in particular, be required when running the program in its 'terminal' or 'batch' mode.

>

and in processing mode it is

process>

The command line processing commands are described in Chapter 12 and are as follows:

lg_spotsize

Determine spot dimensions.

lg_refine

Refine orientation.

lg_dmin

Determine 'dmin'.

lg_lmin

Determine 'lambda-min'.

lg_integrate

Integrate spot intensities.

lg_writeint

Write intensities files.

lg_clearint

Clear intensities list.

lg_readldm

Read an LDM file.

lg_writeldm

Write an LDM file.

1.8 CYLINDRICAL CAMERAS

The program now incorporates some changes to the LDM routines to enable a cylindrical camera to be used. The formulae for converting between reciprocal lattice coordinates and detector coordinates were provided by C. Wilkinson and M.S. Lehmann at the ILL, Grenoble.

It should be noted that some of the formulations used by the program are based on a flat plate detector and do not strictly apply to the cylindrical detector case. These are the use of elliptical masks as described in Appendix 14 and the various distortion corrections as described in Appendix 5 . The spot shape finding routine will be affected by the first of these. In general, best results are likely to be obtained assuming circular spot shapes. Satisfactory orientation refinements have been achieved using cylindrical cameras at the ILL (Neutron Laue) and at the Photon Factory.

1.9 REFERENCES

1. Campbell J.W., Clifton I.J., Elder M., Machin P.A., Zurek S., Helliwell J.R., Habash J., Hajdu J. and Harding M.M. in "Biophysics and Synchrotron Radiation" pp. 53-60, edited by A. Bianconi and A. Congiu Castellano, Springer Verlag (1987)

2. Helliwell, J.R., Habash, J., Cruikshank, 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. (1989) J. Appl. Cryst., 22 483-497.

3. Campbell J.W., (1994a) "XDL_VIEW, an X-windows based Toolkit for Crystallographic and Other Applications" (1995), J. Appl. Cryst., 28 236-242

4. Campbell J.W., (1994b) "LAUEGEN, an X-windows based Program for the Processing of Laue X-ray Diffraction Data" (1995) J. Appl. Cryst., 28 228-236

5. Campbell J.W., Clifton I.J., Harding M.M. and Hao Q. (1994) "A Laue Data Module (LDM) for use in the processing of Laue X-ray Diffraction Data" (1995) J. Appl. Cryst., 28 635-640

6. Greenhough T.J & Shrive A.K., (1994) J. Appl. Cryst., 27 111-121