PXSim User's Guide

  John W. Campbell

  PXSim icon

1 Introduction

PXSim is a program, written in Java, for carrying out simulations of Protein Crystallographic diffraction images and analysing the unique data coverage for one or more crystal settings and series of diffraction images. It is intended primarily as a teaching tool to enable the user to investigate, in some depth, the nature of X-ray diffraction patterns and the amount of data which may be collected using various settings or methods. The program may be used for simulating diffraction patterns for the Rotation, Weissenberg and Laue methods of data collection and analysing the extent of data which may be measured using those methods. The predictions are based on the set of parameters defined in the Diffraction Data Module (DDM).

The use of Java was chosen so that the program could be made available for use across the internet as well as being in a form suitable for porting to any Java supporting platform.

Much of the functionality is based on the program ROTGEN and various libraries from the CCP4 Program Suite (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 detector geometry is derived from that used in the MADNES program (Messerschmidt & Pflugrath, 1987). The program makes also use of a Java based windowing toolkit which is based on the XDL_VIEW toolkit (Campbell, 1995) and library routines from the Daresbury Laboratory Laue Software Suite (Helliwell et al., 1989).

This description does not go into detail about how the predictions are carried out or the effect that each parameter has on these predictions. Some more information may be obtained from the documentation of the Java based objects in the JdlPX section of the Java Development Library (JDL).

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

e.g. <Show Simulations> or <Return to Main Menu>

The user should assume that any prompt/reply sequences take place in the main text input/output window of the program (see below). 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. In some cases errors/problems may also be reported to the Java console.

List of sections:

Introduction to JdlView
Screen Layout
Some Basic Concepts
Outline of the Main Options
The 'Main Menu' Window
Demonstrations
The 'Read DDM File' Option
The 'Write DDM File' Option
The 'Show Simulation' Option
The 'Unique Coverage' Option
Selected DDM Parameters
References

2 Introduction to JdlView

JdlView is a windows based toolkit written in Java based, in some detail on the previously developed XDL_VIEW toolkit. It provides objects for various general functions such as menus, parameter tables and text input/output and in addition, provides some objects written for use in Protein Crystallographic programs including those for image display and displaying diffraction simulations.

JdlView 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. The active strip consists of a diamond shaped item 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 view-object, then the diamond is displayed in a cyan colour 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.

Reference should be made to Part 1 of the JdlView documentation, the JdlView User's Guide to find detailed instructions on how to manipulate the various JdlView objects used by the program.

3 Screen Layout

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

Figure 1: Main Screen of PXSim


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 <Back to Select Sets>.

Top Right

Main parameter table. This is an editable parameter table which contains the main crystal/detector parameters. The table has three layers. For PXSim, the most important parameters are displayed in the top layer. If several rotation ranges etc. are to be examined, these are defined in the second layer of the table. Other parameters may be of interest in special cases.

Bottom Left

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

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

Additional windows e.g. windows for displaying simulations or unique data coverage plots 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.

4 Some Basic Concepts

  1. The Parameters

    The parameters used by the program are those of the Diffraction Data Module (DDM) and may be stored in the form of 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 PXSim are described briefly towards the end of this document; for further details, see the full documentation for the Data Diffraction Module (DDM).

  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, by default, 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. The resolution for the analysis may be changed by the user if desired.

  4. Parameter Updates

    If only one crystal set is currently defined, then any new parameter values input will be automatically applied to all other sets in anticipation of another set or sets being added (increase NUMSETS). When more than one crystal set is being used and a parameter value is updated for the first set, a pop-up dialogue enables the user to decide whether this value is to be automatically updated for all the sets. A similar scheme applies for the update of image based parameters for the first set and/or first image of a set; in this case updates may be automatically requested for all sets and/or all images of the set as appropriate.

    However for PHI_X, PHI_Y, PHI_Z, the option to update for all sets is not given, just the update option for all images of the set as another crystal is not likely to have the same missetting angles.

5 Outline of the Main Options

The following are the main options available in PXSim 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 JdlView documentation). A new set of parameters may be read in from a keyworded parameters file using the 'Read DDM File' option. Note that the parameter table has three 'layers' of parameters accessed by selecting the required set via the green/orange parameter set selector. The parameters in the first layer are the most important for PXSim. The second layer parameters are required if multiple rotation ranges are to be defined. Others may be used in special cases. All DDM parameters are accessible if required though not all are required by PXSim (e.g. the image based corrections or image file parameters are not needed).

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

  2. Rotation/Weissenberg/Laue Simulations

    Two basic types of simulations are available, standard colour simulations and interactive colour 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 a button used for requesting printer or file (JPEG or PNG) output of the simulation. The standard colour simulations show the show the patterns with the spots colour coded in a number of different ways. The interactive simulations have a slider which allow the user to investigate the effects of changing various parameters such as the oscillation range and mosaicity (or Lambda-min, dmin for Laue); spot labelling is also available and it is possible to search for reflections by their indices.

  3. Unique Data Coverage

    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, in terms of a pictorial representation of the reciprocal lattice sections or as a three dimensional (rotatable) view of the reciprocal lattice.

6 The 'Main Menu' Window

This is the window that appears when the program is first started with the 'Main Menu' being displayed. The user may return to this main menu as required to select different options or to exit from the program. The main menu is as follows: 

   <Demonstrations>
   <Read DDM File>
   <Show Simulation>
   <Unique Coverage>
   <Write DDM File>

   <Exit>    (May be absent if PXSim is run as an applet)

The demonstrations enable the simulation or unique data coverage options to be tried with some built in sets of data.

Note than when the main menu is displayed, there is an item labelled 'Fil sel:' in the parameter table below the menu. This has values of yes or no (a toggle value item) to indicate whether or not the system's file selector mechanism is to be used when reading or writing DDM files. When PXSim is run as an application, the use of the File Selector is likely to be the preferred option. However, when run as an applet, security restrictions prevent general access to local file systems (and hence can prevent the use of the file selector) and permissions need to be set for any such file access to be allowed. An option to use logical names as part of file path names is available, again subject to suitable permissions being set up.

7 Demonstrations

When this option is selected the following (Demo Menu) menu is displayed: 

   <Show Simulation>
   <Unique Coverage>

   <Return to Main Menu>

When either of the two options is selected, there is a choice of two datasets to use, selected via the following (Select Menu) menu: 

   <PGM Rotation>
   <LYS Laue>

   <Return to Demo Menu>

This gives access to either a set of Rotation data parameters (for the enzyme Yeast Phosphoglycerate Mutase (e.g Campbell, Hodgson and Watson, 1974)) or of Laue data parameters (tetragonal Lysozyme).

When a dataset is selected, another short menu (Display Menu) is displayed: 

   <Display>
   <Remove>

   <Return to Select Menu>

Note that when the display menu is shown, the parameters in the table (and additional parameters for the option in the small parameter table below the menu) may be changed if desired (The Select parameter here enables a choice of the current set or all sets for the unique coverage). Full details of the simulation and unique coverage options are given below. The parameters for each of the demonstations are reset to their default value each time a choice is made from the 'Select Menu'.

8 The 'Read DDM File' Option

This option is used to read in a DDM keyworded parameter file. If the 'File Sel:' parameter (under Main Menu) was set to 'Yes', then the system File Selector box will be displayed enabling the user to browse and select a file. If the 'File Sel:' parameter was set to 'No', the following prompt is output: 

DDM File name (default ext=.ddm):

The user replies with the name of the required keyworded parameters file. Logical paths may be used if these have been set up. A blank reply will cancel the request. The program checks that the file exists and can be opened; if there is an error, an error message will be output and the prompt will be repeated.

The data are then read from the file and are checked by the program. Errors will be flagged. Values are reset for all the parameters shown in the main parameter table. Program parameter value default values will be set for all parameters not explicitly given in the keyworded data file. The current cystal set and image number will be set to one.

Note that when the program is run as an applet, the appropriate file access permissions need to be set up if files are to be accessed.

9 The 'Write DDM File' Option

This option is used to write a DDM keyworded parameter file. If the 'File Sel:' parameter (under Main Menu) was set to 'Yes', then the system File Selector box will be displayed enabling the user to select a folder/directory and set a file name. If the 'File Sel:' parameter was set to 'No', the following prompt is output: 

DDM File name (default ext=.ddm):

The user replies with the name of the requiredoutput keyworded parameters file (normal extension .ddm). Logical paths may be used if these have been set up. A blank reply will cancel the request. The program checks that can be opened; if there is an error, an error message will be output and the prompt will be repeated.

The data are then written to the file.

Note that when the program is run as an applet, the appropriate file access permissions need to be set up if files are to be accessed.

10 The 'Show Simulation' Option

10.1 Introduction

This option allows for the display of a Rotation/Weissenberg/Laue simulation based on the current parameter values for the currently selected crystal set and image.

List of subsections in this section:

Simulation Menu
Overview of the Simulations
Rotation/Weissenberg Standard Colour Plots
Rotation/Weissenberg Interactive Colour Plots
Rotation/Weissenberg Spot Details
Laue Standard Colour Plots
Laue Interactive Colour Plots
Laue Spot Details
Printer/File Output

10.2 Simulation Menu

When the 'Show Simulation' option is selected the following menu is displayed: 

   <Display>
   <Remove>

   <Return to Main Menu>

When 'Display' is selected, the simulation data are calculated and displayed using a JdlView PX Simulations Object. When a simulation is displayed, it may be removed by selecting the 'Remove' button.

Two (or four for Laue) extra options may be selected via the parameter table below the menu. These are:
  1. Orient This selects the orientation of the simulation so that it may be matched to a particular laboratory or other program convention. All possible orientations are available via the drop down menu with some presets for selected named cases.

  2. Multfac When interactive plots are to be displayed, this parameter sets the value by which the parameters, which can be adjusted interactively via the slider, are to be multiplied so that the data required can be 'over-predicted'. By default this value is two so that the oscillation angle, for example, can be varied, using the slider, from 0 to twice that currently set in the main parameter table. (For Laue plots the ranges do not go from zero. Multfac sets the factor by which lambda-min and dmin values will be divided and the lambda-max multiplied - i.e. over-predicted - see also Limfac)

  3. Limfac For Laue interactive plots, the factor by which to extend the range of lambda-min, lambda-max, and dmin in opposite direction from multfac to determine the other limit for the slider range i.e. it increases lambda-min and dmin and decreases lambda-max).

  4. Gnom-R For Laue simulations, this is a radius which is used in calculating Gnomonic projections.

10.3 Overview of the Simulations

The simulations display uses the JdlView PX Simulations object and full details of its use may be found in the JdlView documentation. The main features are summarised here. There two modes of display, a standard mode and an interactive mode, both of which use colour codings to represent different classes of spots. In each mode there is a display area for the simulation, an area to list details of a selected spot, a control panel area where various options may be selected. The selection of Rotation/Weissenberg/Laue options depends on the current value of the DDM 'TYPE' parameter.

The object uses buttons 1 and 3 of the mouse. Button1 is used for selecting buttons, scrollbars, selecting spots and spot labelling. Button3 may be used for image zooming as follows: As an alternative to using Button3 for zooming, there are scrollbars to the left and right of the simulated pattern display and at the bottom of the display. The left hand scrollbar is used to zoom the pattern. The bottom scrollbar may be used to re-position the view of a zoomed pattern in a horizontal direction and the right hand scrollbar may be used to re-position the view of a zoomed pattern in a vertical direcion.

The mode button toggles between the standard colour display and the interactive colour display. (For Laue simulations, where gnomonic projections have been calculated, the mode button will step through the standard and interactive simulations first for the normal pattern and then for the gnomonic projection).

Where options are similar or identical to those in different cases, they are described only once in the following sub-sections. Refrences may be made to previous sub-sections as follows:

10.4 Rotation/Weissenberg Standard Colour Plots

An example of a Rotation Standard Simulation plot is shown below:

Figure 2: Example of a Standard Colour Rotation Simulation


The options for this plot selectable via the contol panel are as follows:

Colour Coding

Various colour codings are available. The display is qualified by the settings of other control panel items. The options available are:

Fulls/partials

The spots are split into three categories, fulls, partials and those which are on the edge of the cusp region and are partly visible. They are colour coded as follows:
  • blue: fulls.
  • cyan: partials (up to maximum used in the prediction).
  • red: cusp partials.

Partiality 1

The spots are colour coded by their partiality as follows:
  • blue: fulls.
  • cyan: partial <=n as set in the Partial 'n' panel item.
  • yellow: partial >n and up to the maximum used in the prediction.
  • orange: wide partial (greater than the maximum partiality used in the prediction).
  • red: cusp partial.

Partiality 2

The spots are colour coded by their partiality as follows:
  • blue: fulls.
  • cyan: partial =2.
  • green: partial =3.
  • yellow: partial >3 and up to the maximum used in the prediction.
  • orange: wide partial (greater than the maximum partiality used in the prediction).
  • red: cusp partial.

All the same

All the recorded spots are displayed in the same (blue) colour.

Overlap status

The spots are colour coded by whether or not they are spatially overlapped. The colour coding is as follows:
  • blue: not overlapped.
  • yellow: spatially overlapped spot.

Spot Types

The types of spots to be displayed may be chosen from the following three options:
Spatials

There are three options for the display of spatially overlapped spots:
Symbols

The user may select one of four spot size options, small, medium, large or actual size. For the last option, the size used is calculated from the under program 'spot_size' parameter of the Diffraction Data Module on which the display is based. Note that when an image is zoomed, the displayed symbol size remains unchanged for the first three options but is scaled appropriately for the fourth option.

Key

The display, of a key at the top left of the display area showing the colour coding, may be turned on or off via this choice item.

Partial 'n'

The partial 'n' value, used in deciding in which category a partial spot is to be included for the Partiality 1 colour coding option, can be reset via this value item. The value must be in the range of 2 to the maximum value used in the prediction.

10.5 Rotation/Weissenberg Interactive Colour Plots

An example of a Rotation Interactive Simulation plot is shown below:

Figure 3: Example of an Interactive Rotation Simulation


The options for this plot selectable via the contol panel are as follows:
Colour Coding

Various colour codings are available. The display is qualified by the settings of other control panel items. [Rot-Std]

Labels

Once labels have been drawn, this item enables the labels to be displayed or not displayed as required.

Slider

This item selects the current prediction parameter which is to be varied using the slider. The following parameters may be chosen:
Key

The display of a key [Rot-Std].

Part-n

The partial 'n' value [Rot-std].

10.6 Rotation/Weissenberg Spot Details

When the mouse Button1 is pressed with the cursor on a spot position, details of that spot will be listed in the spot details area. The following information is listed:

The indices

The coordinates

The detector xf, yf coordinates in millimetres from the centre of the pattern.

The partiality

For a fully recorded spot the message 'fully recorded' is given. For a partial, the partiality is given and the offset from the current image of the start image for the spot is indicated. 'Wide' or 'Cusp' partials are flagged as such.

The overlap status

A symbol indicates whether or not the spot is spatially overlapped. For a non-overlapped spot, the symbol is a grey disk and for a spatially overlapped spot, the symbol is a grey disk partly overlapped by a red disk. If the overlap status has not been calculated, a grey circle overlayed with a red cross is shown.



The selected spot is marked by a surrounding white circle on the display area. The selection may be removed by clicking Button1 of the mouse when the cursor is within the display area but not pointing to a spot. When selecting a spot, the nearest spot to the cursor is selected provided that the distance squared (pixels) to the spot is no more than 18.

Underneath the reflection details listing, there is a value item which enables a set of indices to be input for a reflection to be searched for. If found, a cross or circle will mark the reflection position on the plot and the reflection details will be listed. If the reflection is not found, the message 'Not found:' followed by the indices will be displayed in the value area. For a found reflection,a circle will be drawn for a standard colour plot or for an interactive colour plot if the reflection is currently displayed. When a reflection has been predicted for an interactive plot, but is not currently displayed, the spot position will be marked with a cross.

10.7 Laue Standard Colour Plots

Examples of a Laue Standard Simulation plot and a Laue Gnomonic projection plot are shown below:

Figure 4: Example of a Standard Colour Laue Simulation


Figure 5: Example of a Laue Gronomic Projection Simulation


The options for this plot selectable via the contol panel are as follows:

Colour Coding

Various colour codings are available. The display is qualified by the settings of other control panel items. The options available are:

Wavelength

The wavelength range is split into eight ranges which are identified by eight different colours on a scale running from blue (low wavelength) to red (high wavelength). Multiple spots are colour coded by their highest wavelength component.

Multiplicity

The spots are colour coded by their multiplicity as follows:
  • blue: singles.
  • cyan: doubles.
  • yellow: triples.
  • red: multiplicity > 3.

Wavelength/Multiplicity

The singles are colour coded by wavelength, The wavelength range is split into eight ranges which are identified by eight different colours on a scale running from blue (low wavelength) to red (high wavelength). The multiples are colour coded white.

Nodality

The spots are colour coded by their nodality as follows:
  • blue: non-nodal spot.
  • yellow: nodal spot. The nodal index may be set via the 'Nidx' value item on the control panel and has a default starting value of 4.

Spot Types

The types of spots to be displayed may be chosen from the following three options:

Spatials

There are three options for the display of spatially overlapped spots [Rot-Std].
Symbols

The user may select one of four spot size options [Rot-Std].

Key

The display of a key [Rot-Std].

Nidx

The nodal index, used in deciding whether or not a spot is a nodal for the plot colour coded by nodality, can be reset via the 'Nidx' value item on the control panel. The value must be in the range 0 to 12.

10.8 Laue Interactive Colour Plots

An example of a Laue Interactive Simulation plot is shown below:

Figure 6: Example of an Interactive Laue Simulation


The options for this plot selectable via the contol panel are as follows:

Colour Coding

Various colour codings are available. The display is qualified by the settings of other control panel items. [Laue-Std]

Labels

The following options are available for the labels' display:
Slider

This item selects the current prediction parameter which is to be varied using the slider. The following parameters may be chosen:
Key

The display of a key [Rot-Std].

Nidx

The nodal index limit [Laue-Std].

10.9 Laue Spot Details

When the mouse Button1 is pressed with the cursor on a spot position, details of that spot will be listed in the spot details area. The following information is listed:

The indices

For a multiple spot these are for the lowest harmonic present.

The wavelength

This is given in brackets following the indices (Angstroms). For a multiple spot this is for the lowest harmonic present.

The coordinates

The detector xf, yf coordinates in millimetres from the centre of the pattern.

The multiplicity

For a multiple spot, the multiplicity is followed by the range of harmonics present.

The overlap status

A symbol indicates whether or not the spot is spatially overlapped. For a non-overlapped spot, the symbol is a grey disk and for a spatially overlapped spot, the symbol is a grey disk partly overlapped by a red disk. If the overlap status has not been calculated, a grey circle overlayed with a red cross is shown.



The selected spot is marked by a surrounding white circle on the display area. The selection may be removed by clicking Button1 of the mouse when the cursor is within the display area but not pointing to a spot. When selecting a spot, the nearest spot to the cursor is selected provided that the distance squared (pixels) to the spot is no more than 18.

Underneath the reflection details listing, there is a value item which enables a set of indices to be input for a spot to be searched for. If found, a cross or circle will mark the reflection position on the plot and the reflection details will be listed. If the actual reflection is not found, but a spot with the same nodal indices is present, details will be shown as before but the reflection indices will be surrounded by [[  ]] in the 'Find hkl' value area. If the reflection or harmonic is not found, the message 'Not found:' followed by the indices will be displayed in the value area. For a found reflection,a circle will be drawn for a standard colour plot or for an interactive colour plot if the reflection is currently displayed. When a reflection has been predicted for an interactive plot, but is not currently displayed, the spot position will be marked with a cross. When a reflection is selected from the plot, its indices will be shown in the 'Find hkl' value area.

10.10 Printer/File Output

Selecting the printer icon button initiates the process of either printing the displayed simulation (with selected annotation) on the printer or outputting the displayed pattern to a PNG or JPEG file. When the button is selected a dialogue window is displayed.

Figure 7: Print Dialogue



This dialogue box enables the following items/options to be set:

Title

The title, if given, will be printed underneath the simulated pattern.

Width

This is the required width of the simulated pattern plot in cms. The valid range is 0.5 to 18.0 cms.

Header

If selected, there will be a header line showing the type of plot followed by the date.

Key

If selected, a key will be printed at the bottom of the page containing details about the parameters on which the predicted simulation was based.

Black bg

If selected, the page will be printed with a black background with any text required being output in a light colour.

Comment

If present, the comment text will be output under the title line (centred on the page). It may be split into more than one line if it is too long to fit into a single line.

The alternative file output may be selected via the JPEG File or PNG File buttons depending on the format required. When one of these is selected, the dialogue box will appear as follows:

Figure 8: File Output Dialogue


The required output file name may then be given. Note that, with these type of plots with sharp features and a limited number of colours, the PNG files provide a higher quality output than JPEG files.

Note that the printer and/or file output options will not work when the PXSim is used in an applet form unless the appropriate security permissions are in place. This is a general feature of the use of Java Applets.

11 The 'Unique Coverage' Option

11.1 Introduction

The 'Unique Coverage' 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, in terms of a pictorial representation of the reciprocal lattice sections or as a three dimensional (rotatable) view of the reciprocal lattice.

Note that the space group symmetry must be defined before the analysis can be carried out.

For Rotation/Weissenberg data, the data may be classified as reflections which have been fully or partially recorded. For Laue data, the corresponding distinction is made between reflections measured as Singles and those deconvoluted (potentially - see below) from spot Multiples.

List of subsections in this section:

Laue Multiples Deconvolution
Unique Coverage Menu
Overview of Unique Coverage Plots
Reciprocal Lattice Layers Plot
Reciprocal Lattice 3-D Plot
Unique Coverage Histograms
Printer/File Output

11.2 Laue Multiples Deconvolution

The potential deconvolution of Laue multiples is based on the wavelength normalisation curve method. This is likely to be an optimistic prediction as it assumes that all spot intensities have suitable values for the deconvolution process. The wavelength normalisation curve used by PXSim is based on an experimentally determined curve from the synchrotron at Daresbury. The curve was derived for a wavelength range of 0.5 to 2.17 Angstroms. In this program this curve is expanded or contracted to fit whatever range is defined by the current values of the parameters lambda-min and lambda-max. A maximum scaling factor limit of 25.0 is applied.

11.3 Unique Coverage Menu

When the 'Unique Coverage' option is selected the following menu is displayed: 

   <Current Set>
   <All Sets>

   <Return to Main Menu>

The current set, if selected, is the one for which the parameters are currently displayed in the main parameter table. A further option may be selected via the parameter table below the menu. This enables the resolution limit for the data analysis to be reset. By default it has the current resolution limit for the first crystal set. When a selection from the 'Select Sets' menu has been made, the following 'Display Menu' menu is displayed: 

   <Display>
   <Remove>

   <Back to Select Sets>

When 'Display' is selected, the unique data coverage is calculated and the results displayed using a JdlView Show Unique Object. When a unique coverage plot is displayed, it may be removed by selecting the 'Remove' button.

11.4 Overview of Unique Coverage Plots

There are basically three types of output which may be selected. These are:
In each case, there is a main display area on which the data is displayed and a control panel area at the top which enables various options to be selected. On each control panel, there is a 'Mode' button which is used to step through the three types of display. The three cases are described in detail below.

Where options are similar or identical to those in different cases, they are described only once in the following sub-sections. References may be made to previous sub-sections as follows: Where the Rotation/Weissenberg and Laue cases differ, the Rotation/Weissenberg options are shown first followed by the Laue equivalents enclosed in braces {  }.

11.5 Reciprocal Lattice Layers Plot

The main display area shows a single section of the reciprocal lattice at a time showing which reflections are part of the unique area of the reciprocal lattice and which of these reflections have been predicted or observed. An example is shown below:

Figure 9: Unique Coverage - Layers


Different categories of reflections e.g. fulls, singles, partials or deconvoluted multiples may be included in the plot and, where appropriate, merged or unmerged anomalous data pairs may be indicated. Spots predicted as spatial overlaps may be included or excluded as desired. Spots which are classified as unknown full/partial{/single/multiple} (e.g. derived from a merged dataset) are included in the display as fully recorded {or single} (and non-spatially overlapped) spots. If anomalous separated data is displayed then these spots may also be of unknown sign (see below for colour coding). In all cases the section axis is along 'l'. On the l=0 section the a* and b* axes are displayed. The points on the unique part of the reciprocal lattice are marked by small greenish dots for those spots which have not been predicted/measured.

The following options are available via the control panel:

Fulls {Singles}

The options are for fulls {singles} to be included or excluded.

Partials {Mults}

For partials the options are as follows:
  • none.
  • partiality = 2 partials only included.
  • partiality <= 3 partials only included.
  • partiality <= nwmax partials included (nwmax is a parameter from the Diffraction Data Module (DDM)).

{For deconvoluted multiples the options are as follows:
  • none.
  • deconvoluted from multiplicity = 2 only included.
  • deconvoluted from multiplicity <= 3 only included.
  • deconvoluted from any multiple.}

Anom

The options are as follows:
  • merged.
  • separate.
  • both I+ and I- measurements made.
  • I+ measurement made.
  • I- measurement made.

For merged data, all measured reflections are shown as yellow spots. For the other cases, the colour coding is as follows:
  • yellow: Both an I+ and an I- reflection are present.
  • red: Only the I+ reflection is present.
  • blue: Only the I- reflection is present.
  • white : Unknown sign (i.e. both I+ and I- are not present though I+ or I- may be present in addition to measurements flagged as being of unknown sign.

Spatials

Spatially overlapped spots may be either included or excluded.

Up and Down buttons and slider

Clicking on one of these buttons moves up or down one layer of the reciprocal lattice. The slider between the buttons enables rapid access to the different layers though, if there are a large number of layers, a final adjustment may be needed using the Up/Down buttons to get to the exact layer required. The current layer number is shown at the bottom left of the plot.

Cycle button and slider

Clicking the Cycle button will start/stop automatically cycling through the layers. The speed of the cycling may be adjusted using the slider to the left of the Cycle button.

11.6 Reciprocal Lattice 3-D Plot

In this case, the main display area shows a three dimensional perspective view of the unique section of the reciprocal lattice. The picture indicates by colour coded dots which of these reflections have been predicted or observed. This view may be rotated automatically or its orientation changed by means of a slider. An example is shown below:

Figure 10: Unique Coverage - 3D Plot


Different categories of reflections e.g. fulls, {singles,} partials {or deconvoluted multiples} may be included in the plot and, where appropriate, merged or unmerged anomalous data pairs may be indicated. Spots predicted as spatial overlaps may be included or excluded as desired. Spots which are classified as unknown full/partial{/single/multiple} (e.g. derived from a merged dataset) are included in the display as fully recorded {or single} (and non-spatially overlapped) spots. If anomalous separated data are displayed, then these spots may also be of unknown sign (see below for colour coding). The a* and b* axes are displayed in the horizontal plane an c* is in an upwards direction. The points on the unique part of the reciprocal lattice are marked by small greenish dots for those spots which have not been predicted/measured.

The following options are available via the control panel (the case for the Rotation data case is shown first with any variation for the Laue case following in braces {}):

Fulls {Singles}

The options are for fulls {singles} to be included or excluded.

Partials {Mults}

For including categories of partials {deconvoluted multiples} [Layers].

Anom

Handling of anomalous data [Layers]

Spatials

Spatially overlapped spots may be either included or excluded.

Up and Down buttons and slider

Clicking on one of these buttons moves the viewing angle of the three dimensional plot up or down 5 degrees at a time up to a maximum view angle of plus or minus 45 degrees. The slider between the buttons enables the 3D plot to be rotated to any of the positions within the possible 360 degrees of rotation.

Cycle button and slider

Clicking the Cycle button will start/stop automatically rotating the 3D view of the reciprocal lattice. The speed of the rotation may be adjusted using the slider to the left of the Cycle button.

11.7 Unique Coverage Histograms

In this case, the main display area shows one of a series of histograms. These are all plots against resolution. The requested resolution range is divided into eight equal bins of 4.sin**2(theta)/lambda**2. An example is shown below:

Figure 11: Unique Coverage - Histogram


Different categories of reflections e.g. fulls, {singles} and/or partials {deconvoluted multiples} may be included in the plots.

The three types of histogram available are as follows:

  1. Unique Data

    This plot shows the percentage of coverage of the unique data within each resolution bin. Where partials {deconvoluted multiples} are included two coloured bars are drawn, an orange one indicating the coverage for the full {single} reflections and an additional green section showing the coverage with the included partials {deconvoluted multiples}. The overall percentage coverage for each of these cases is given at the top of the plot. Where no partials {deconvoluted multiples} are included, an orange bar shows the coverage for the fulls {singles} data and the overall coverage by the fulls {singles} data is given at the top of the plot.

  2. Acentric Pairs

    This plot shows the percentage coverage of the unique acentric data within each resolution bin. A reflection must be present for each mate of a Bijvoet pair to be included. Where partials {deconvoluted multiples} are included in the analysis, two coloured bars are drawn, an orange one indicating the coverage for the full {single} reflections and an additional green section showing the coverage with the included partials {deconvoluted multiples}. The overall percentage coverage for each of these cases is given at the top of the plot. Where no partials {deconvoluted multiples} are included, an orange bar shows the coverage for the fulls {singles} data and the overall coverage by the fulls {singles} data is given at the top of the plot. Reflections of unknown sign are excluded from the analyses of acentric pairs.

  3. Multiplicity

    This plot shows the average reflection measurement multiplicity within each resolution bin. This refers to the number of times each reflection was measured and not, in the case of Laue data, to the multiplicity of individual spots (multiples). Where partials {deconvoluted multiples} are included, two coloured bars are drawn, an orange one indicating the multiplicity for the full {single} reflections and an additional green section showing the multiplicity with the included partials {deconvoluted multiples}. Note: It can happen in some cases that the multiplicity in a resolution bin decreases when partials {deconvoluted multiples} data are included as there will be additional reflections which could have any measurement multiplicities; in such cases, a green line will be drawn through the orange bar at the appropriate height. The overall average multiplicity for each of these cases is given at the top of the plot. Where no partials {deconvoluted multiples} are included, an orange bar shows the multiplicity for the fulls {singles} data and the average multiplicity for the fulls {singles} data is given at the top of the plot.

The following options are available via the control panel:

Fulls {Singles}

The options are for fulls {singles} to be included or excluded.

Partials {Mults}

For including categories of partials {deconvoluted multiples} [Layers].
Type

This selects the type of histogram to be displayed.The options are as follows:
  1. Unique.
  2. Acentric Data.
  3. Multiplicity.

Spatials

Spatially overlapped spots may be either included or excluded.

11.8 Printer/File Output

When the printer icon button is selected a dialogue window is displayed, for example as follows:

Figure 12: Print Dialogue


The 'Multiple' check box is only present for the first type of unique data coverage plot (Reciprocal Lattice Layers). In general, the dialogue box enables the following items/options to be set:

Title

The title, if given, will be printed underneath the displayed plot.

Width

This is the required width of the simulated pattern plot in cms. The valid range is 0.5 to 18.0 cms.

Header

If selected, there will be a header line showing the type of plot followed by the date.

Multiple

This is only present for the Reciprocal Lattice Layers type of plot. If selected, this enables the output of a plot with a whole series of layers shown (up to 9 per page). The dialogue changes in that the 'Header' and 'Width' options are removed but there is instead a 'Layers or All' option. In this, the user may give a list of layer numbers and/or ranges of layers (e.g. 1, 2, 3, 10-20, 25) or the code 'All' (the initial default) for all layers.

Black bg

If selected, the page will be printed with a black background with any text required being output in a light colour.

Comment

If present, the comment text will be output under the title line (centred on the page). It may be split into more than one line if it is too long to fit into a single line.

The alternative file output may be selected via the JPEG File or PNG File buttons depending on the format required. When one of these is selected, the dialogue box will appear as follows:

Figure 13: File Output Dialogue


The required output file name may then be given. Note that, with these type of plots with sharp features and a limited number of colours, the PNG files provide a higher quality output than JPEG files.

12 Selected DDM Parameters

The table below summarises the Diffraction Data Module (DDM) parameters most relevant to the use of PXSim. Some of the other DDM parameters such as selecting areas of the image or non-default detector geometry, will affect the predictions made if non-default values are used. Full details of the DDM parameters are given in the documentation of the Diffraction Data Module. In the table below keywords followed by [] indicate crystal set based parameters and those followed by [][] indicate image based parameters. 

Dataset Parameters

Title             TITLE           A title for the dataset.

No. crystal sets  NUMSETS         Number of crystal sets defined within
                                  this dataset.

Diffraction type  TYPE            Diffraction type: Rotation/Weiss/Laue

Crystal number    CRYSTAL_NUMBER[]
                                  Crystal number (if 0 assumed to be 
                                  same as crystal set number)

No. images        NUMIMG[]        Number of images for each crystal set

Crystal Based Parameters 

Sample Parameters

Crystal system    SYSTEM          The crystal system Tri, Mon, Ort, 
                                  Tet, Hex, Rho or Cub.  

Lattice type      LATTICE         Lattice type P, A, B, C, I, F or R.

Crystal symmetry  SYMMETRY        The space group symmetry followed by 
                                  the space group number, space group
                                  name or symmetry operators or 'clear'
                                  'clear' to clear current symmetry.

Cell              A[], B[], C[], ALPHA[], BETA[], GAMMA[]

                                  The cell parameters in Angstroms and
                                  degrees.

Resolution        RESOLUTION[][]  The resolution limit in Angstroms.

Mosaicity         MOSAICITY[][]   The mosaic spread in degrees.

Spot size         SPOT_SIZE[][]   The spot diameter in mm. This is
                                  a suffixed parameter so that several
                                  values may be input for defining
                                  Laue spot shapes. Thus SPOT_SIZE1,
                                  SPOT_SIZE2 etc. could be used.

Partials limit    NWMAX[]         Only consider partials occurring on
                                  up to this number of images.

Orientation parameters:

U-matrix          UMATRIX[]       The basic 'U' setting matrix 
                                  (9 values).

Missetting angles PHI_X[][], PHI_Y[][], PHI_Z[][]

                                  The missetting angles in degrees.

Orienting phi     PHI_ORIENT[]    Goniometer angle for image used to
                                  set the orientation PHI's.
Current Experiment

Rotation ranges   ROTSTART[], ROTEND[]      

                                  Rotation start and end angles in 
                                  degrees. This is a suffixed
                                  parameter so several ranges may
                                  be input if required. May use
                                  ROTSTART1, ROTSTART2 etc.

Osc or inc angle  ANGLE_INC[]     Oscillation angle in degrees or
                  ANGLE_OSC[]     spindle increment for Laue (+ve).
                                  (aliased names).

Detector and Source Parameters

Detector Setting 

Distance          DISTANCE[][]    The crystal to detector distance 
                                  in mm.

Maximum radius    RMAX[]          Maximum radius on detector in mm.

Rotations         TAU_X[], TAU_Y[], TAU_Z[]
  
                                  Rotations of the detector around the 
                                  three detector axes. Theta tilt
                                  is TAU_Z.

Weiss. coupling   WEISS_COUPLING[]
                                  Weissenberg coupling constant.


Detector Basics 

Detector geometry DET_GEOMETRY[]  Flat or Cylindrical detector

Scan axis         SCAN_AXIS[]     Rotation axis vector.

Source parameters 
 
Synchrotron       SYNCHROTRON[]   Synchrotron - yes or no.

Wavelength        WAVELENGTH[]    The wavelength in Angstroms.

Lambda-min        LAMBDA_MIN[]    Minimum wavelength for Laue

Lambda-max        LAMBDA_MAX[]    Maximum wavelength for Laue

Dispersion        DISPERSION[]    The dispersion delta(lambda)/lambda.

Vertical divrg.   DIVV[]          Vertical divergence in degrees.

Horizontal divrg. DIVH[]          Horizontal divergence in degrees.

Corr. dispersion  DELCOR[]        Correlated dispersion.

Image Limits

2-theta           TWOTH_MIN[]     Minimum two theta angle to consider
                                  in degrees.

Minimum radius    RMIN[]          Minimum radius in mm.

'rmin' x-centre   R_XCEN[]        'x' centre of 'rmin' circle in 
                                  rasters.

'rmin' y-centre   R_YCEN[]        'y' centre of 'rmin' circle in
                                  rasters .

x,y limits        X_MIN[], X_MAX[] Y_MIN[], Y_MAX[]

                                  Limits on 'x' and 'y' in rasters.

13 References

Campbell J.W., Watson H.C. and Hodgson G.I., "The Structure of Yeast Phosphoglycerate Mutase at 3.5A Resolution", Nature (1974) 250, 301

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

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

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

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

Campbell J.W. and Hao Q. "Evaluation of Reflection Intensities for the Components of Multiple Laue Diffraction Spots. II. Using the Wavelength-Normalisation Curve" Acta Cryst. (1993) A49, 889-893

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

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