The Diffraction Data Module (DDM)

  Diffraction Data Module icon

  John W. Campbell

1 Introduction

The Diffraction Data Module (DDM) defines a set of parameters for use in the initial stages of processing or predicting sets of protein crystallographic X-ray diffraction images. It has been devised to be used with Java code built using the Java Development Library (JDL) sets of objects which include a set of objects specifically for use with protein crystallographic calculations. Its specification is very similar to that of the Rotation Data Module (RDM) but has been modified so that it can be used for the Laue and Weissenberg methods of data collection as well as with the Rotation Method. A JDL object supports the input/output and handling of DDM data. Currently it makes use of a set of keyworded data files though options for inputting the data from an alternative e.g. XML format file could be incorporated at a later stage; in such a case the basic parameter definitions would remain the same though different names from the current keywords might be need to be used for the XML tags. Having said that, the current keyworded file provides a simple, convenient and short way of holding the data in a file. All the keywords may be handled via a general purpose Keyword Data Module Java object except for the input of the crystal symmetry for which another Java object may be used.

All the DDM parameters are essentially independent of each other and may, in general, be specified in any order within a DDM parameter data file. In a few cases the value of a parameter may mean that some other parameters are not relevant for a particular case or have a slightly different meaning.

List of sections:

Scope of the Diffraction Data Module
Handling the Keyworded Parameters in Java
Coordinate Systems
Reading and Writing DDM Data
Summary of Keyworded Parameters
Detailed Specification of the Parameters
Standard Set of Output Parameters

2 Scope of the Diffraction Data Module

The DDM parameters cover those needed in the initial stages of processing or predicting a set of Rotation, Wieissenberg or Laue X-ray diffraction images. Basically they are those parameters which are needed in order to generate predicted diffraction patterns which closely match the observed images prior to the intensity integration stage. They are essentially in three categories:-
  1. The crystal parameters such as the crystal symmetry, 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 detector type, the positioning of the detector and the wavelength or wavelength range.

  3. The parameters describing the scanned images and the spots on these images such as pixel size, numbers of rasters, spot sizes and the area to be processed. Distortion correction parameters are included.
The Diffraction Data Module parameters are intended to describe the properties of the system as a whole and not the parameters which are specific to a particular program. However, data files containing DDM parameters for input to a program may also contain additional program specific data if required. The basic unit for parameter storage and processing of the data is a series of crystal sets. Each crystal set corresponds to data collection from a crystal in a given orientation with up to a maximum of five rotation ranges or sets of spindle settings defined around a single rotation axis.

3 Handling the Keyworded Parameters in Java

The parameters are set up making use of a general Keyword Data Module (KDM) handling object. Symmetry is handled separately. Parameters may be defined for individual 'sets' or 'subsets' within the overall data set. In the context of the DDM, a set refers to an individual crystal set of parameters and a subset refers to an individual diffraction image.

Parameters may be of type integer, double or String and normally have a single value associated with each keyword though some more complex options are also available. For a crystal set based parameter the keyword may have a crystal set number appended in square brackets e.g. ROTSTART[2] 50.0; if the crystal set number is omitted, it is assumed that the value following the keyword refers to all crystal sets e.g. RMAX 90.0. Similarly an image based parameter may have a crystal set and image number appended e.g. SPOTW[2][3] 0.7; SPOTW 0.6 sets the same value for all sets and subsets; SPOT_SIZE[][3] 0.75 sets the same value for image 3 of each crystal set and SPOT_SIZE[2][] 0.55 sets the value for all images of set 2. Sets and images are numbered from 1 upwards.

Other options for integer and double parameters are to have a fixed number of values (>1) e.g. for a vector or matrix. A further option can also associate a variable number of values with an integer or double value parameter. These are known as suffixed keyword parameters. The values for such parameters may be input as a variable length list of values or individual values may be input/accessed using the keyword name with a number appended indicating the position in the list of values associated with that keyword (The keywords for such parameters must not themselves end with a digit). For example take the rotation range start value parameter ROTSTART which normally has a single value e.g. ROTSTART 25.0. However if, for example, three rotation ranges are required, three values may be given e.g.

ROTSTART 25.0 66.5 120.0. 

In addition, the keywords ROTSTART1, ROTSTART2 and ROTSTART3 are automatically made available to set or access the individual values e.g.

ROTSTART1 25.0 
ROTSTART2 66.6 
ROTSTART3 120.0

The number of values currently defined for the parameter will be the largest of the number of values input following the keyword and the maximum index given in the keyword suffix. Thus for example, if ROTSTART6 180.0 was defined in addition to the previous definitions, The number of values currently defined would be taken as 6 and default values would be assigned to the values not explicitly defined e.g. for ROTSTART4 and ROTSTART5 in the above example. Naturally set/image specifications can be added as with any of the single or fixed number of values integer/double parameters e.g. ROTSTART2[3] for the value of ROTSTART2 for the third set.

For most parameters a keyword is followed by a single value. The keywords are case insensitive and need not be given in full though a certain minimum number of characters must be given in each case. In general more than one keyword/value pair may be given on a line. Keywords which may be followed by more that one value or word should be given on separate lines.

Keywords including any set specifications may not include any embedded spaces. Round brackets may be used in place of the square brackets in the set and image specifications. If desired, the keyword/value pairs may be separated by '=' signs rather than spaces; commas may also be used as item separators. An '=' sign or a comma with surrounding white space is treated as a single separator. Comments are indicated in a KDM based file as any text following an exclamation mark to the end of that line. Line continuation is indicated by the character '-' or '&' as the last non-blank character of the line. If the continuation line is commented, the comment must follow the continuation character.

KDM files may contain references to further nested KDM files. These are specified by the '@' character followed by a file name.

KDM based methods enable the monitoring of changes to KDM parameter values during the execution of a program.

The reading and parsing methods are designed so that data may be input from data files containing parameters from more than one KDM data set provided that there is no clash of keywords. It also enables crystallographic symmetry data to be included in the input data file though this has to be interpreted using the appropriate purpose built object methods in the Jdl.JdlPX package.

4 Coordinate Systems

4.1 Introduction

This section describes the internal and external coordinate systems used in DDM and the distortion corrections which may be applied to convert from ideal detector coordinates in mm to actual detector coordinates in mm or rasters.

List of subsections in this section:

Coordinate axes
Distortion corrections
Conversion to rasters

4.2 Coordinate axes

The internal and external coordinate systems used in the DDM specification and coding are basically those used in the MOSFLM Suite. The features relevant to the description of the Diffraction Data Module are illustrated in Figures 1 and 2.

Figure 1: Laboratory and Detector Axes

Figure 2: Ideal & Detector axes and Camera Constants

4.3 Distortion corrections

The following corrections are applied to convert ideal detector coordinates in mm to distortion corrected coordinates in mm both from the pattern centre.

Let the ideal predicted spot position be xf, yf. The coordinates xq, yq with respect to the same origin but rotated to be parallel to the detector axes are given by:

   xq = xf.cos(w_c) - yf.sin(w_c)

   yq = xf.sin(w_c) + yf.cos(w_c)

   where w_c is the DDM parameter W_C (converted to radians)

Let xff, yff be the required distortion corrected coordinates in mm parallel to the detector axes prior to correcting the centre position.

For both available distortion types (DDM parameter DISTOR_TYPE), the twist and tilt corrections (DDM parameters TWIST and TILT) are applied as follows:

   xff = K*xq

   yff = K*yq

   where K=1.0+(torad/ctod)*(tilt*xq+twist*yq)

         torad is a conversion factor from 1/100 degrees to radians

         ctod is the crystal to detector distance (RDM parameter
         DISTANCE)

For a radially scanned image (DISTOR_TYPE = rtoff) the additional corrections are applied:

   Let xp = xcmid + xff

       yp = ycmid + yff

   where xcmid, ycmid are the offsets in mm of the corrected pattern
   centre from the image midpoint parallel to the detector axes.

   Re-calculate xff, yff using the following expressions:  

   xff = K*xq + 0.01*(-toff*sin(psi) + roff*cos(psi))

   yff = K*xq + 0.01*(toff*cos(psi) + roff*sin(psi))

   where cos(psi)=xp/sqrt(xp**2+yp**2), sin(psi)=yp/sqrt(xp**2+yp**2)

   and where roff and toff are the RDM parameters ROFF and TOFF

Let xfd, yfd be the required distortion corrected coordinates in mm 
parallel to the detector axes.

   xfd = x_c + xff

   yfd = (y_c + yff)*y_scale

   where x_c, y_c and y_scale are the DDM parameters X_C, Y_C and
   Y_SCALE respectively.

If the reverse calculation needs to be carried out, this cannot be done with direct expressions but requires an iterative procedure.

Java based methods are available to carry out the required calculations in both directions (JdlCrystalCalculations class).

4.4 Conversion to rasters

The conversion from distortion corrected coordinates in mm from the pattern centre to actual detector coordinates in rasters is as follows:

The distortion and centre corrected coordinates xfd, yfd are converted into image raster coordinates xd, yd using the following expressions:

   xd = x_cen + xfd*mm_rast_x

   yd = y_cen + yfd*mm_rast_y

where x_cen, y_cen are the coordinates of the measured or input pattern centre (DDM parameters X_CEN, Y_CEN), and mm_rast_x and mm_rast_y are the conversion factors from mm to rasters in the xd and yd directions respectively. mm_rast_x is calculated from the DDM parameter PIX_X and mm_rast_y from the DDM parameters PIX_Y.

The reverse expressions are as follows:

  xfd = (xd - x_cen)/mm_rast_x

  yfd = (yd - y_cen)/mm_rast_y

Java based methods are available to carry out these conversions (JdlCrystalCalculations class).

5 Reading and Writing DDM Data

Java based DDM methods are available to read and write DDM data files. The remainder of this section is included for the benefit of a Java application programmer with references to objects/methods in Java Development Library (JDL).

A complete DDM file may be read using the method readDDMFile() (object Jdl.JdlPX.JdlDiffractionDataModule). This reads the KDM based keyworded data and also the symmetry data. This method uses the general procedure which may be used to read data from a file where data from more than one KDM dataset or other program specific data is included. The general procedure for this is outlined below.

In reading data from a file, the method kdmReadLine(..) (object Jdl.JdlKDM.JdlKeywordDataModule) allows for the next logical line of data to be read. Any continuation lines are combined into the single string returned and any comments are removed. Indirect file specifications are processed when encountered. In cases where data are not being read from a file but a text string containing the DDM specifications is available for processing, the method kdmReadString(..) (object Jdl.JdlKDM.JdlKeywordDataModule) is available to perform a similar function on this string again handling any indirect file references. When the next logical line of data has been obtained using one of these methods, the line is parsed for DDM data using the method parseKDMLine(..) (object Jdl.JdlKDM.JdlKeywordDataModule) If any valid DDM keywords are found, then the data values will be checked and the data will be automatically stored in the associated KDM object. DDM and non-DDM data may not be present on the same line of input. Any errors in the DDM data values or other DDM keywords on the line will be flagged. If there is no DDM data on the line then it is returned to the program for further processing and thus data from other KDM based data sets or program specific data may be given in the same file as the DDM data. An additional method parseSymmetryLine(..) (object Jdl.JdlPX.JdlSymmetry) is used to parse the lines containing the symmetry data and store the symmetry in a Jdl.JdlPX.JdlSymmetry object. This is called after parsing to find the other DDM data.

When writing DDM data files, the DDM data may be output at different levels of detail as desired though all non-default DDM parameter values will always be given. If the output data are read in again, the DDM parameter data will of course always have the same values regardless of the output level used. The four output levels are as follows:-
  1. Only output non-default values.

  2. Always output a standard set of parameters even if they have default values and also any additional parameters which have non-default values. Where possible, the minimum output will be given for set specific parameter by looking for common values throughout the sets/images. This option is recommended as the standard form of output for an DDM file.

  3. Output all DDM parameters but minimise output where possible as in the previous case.

  4. Give all DDM parameters and all individual set/image based parameters explicitly.
It is important that the DDM parameter values are output sufficiently accurately so that there is no significant loss of accuracy when a set of DDM data is written out and read in again. To ensure this, each parameter has its own default output format specified internally. This is only used if the parameter value has been recalculated within the program. Otherwise the parameter values are output with the same number of decimal places that were used when they were input thus giving more readable files with no additional loss of accuracy. A facility is also available within the DDM object to monitor parameter changes and write out only those parameters which have changed between specified points in a program. This enables a clearer record to be made of parameter value changes, e.g. to a log file, particularly if a windows based program is used where parameters may be manually changed at almost any stage.

6 Summary of Keyworded Parameters

This section gives a brief summary of the parameters available; a more detailed specification follows in the next section. Keywords followed by a pair of brackets [] may have separate values for each crystal set within the dataset if required. Keywords followed by two pairs of brackets [][] may have separate values for each set and image within the set.

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

Image directory   IMAGE_DIR[]     The directory for the image files.

Image template    IMAGE_TEMPLATE[]
                            
                                  Image file name template.

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 type     DET_TYPE[]      Specific detector type e.g. MAR

Detector geometry DET_GEOMETRY[]  Flat or Cylindrical detector

Orientation       DET_ROTATIONS[] Directions of three orthogonal 
                                  detector rotation axes.

Axes              DET_AXES[]      Detector axis vectors.

Axis name         AX1_NAME[]      Name of first local axis on detector

Axis name         AX2_NAME[]      Name of second local axis on detector

Horizontal axis   IAX_H[]         Horizontal axis number 1-3.

Vertical axis     IAX_V[]         Vertical axis number 1-3.

Scan axis         SCAN_AXIS[]     Rotation axis vector.

Detector gain     DET_GAIN[]      The detector gain

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.

Polarisation      POLARISATION[]  Degree of polarisation.

Image Based Parameters

 Image basics 

x-centre          X_CEN[]         Input/measured 'x' centre position
                                  in rasters.

y-centre          Y_CEN[]         Input/measured 'y' centre position
                                  in rasters.

Pixel size (x)    PIX_X[]        The (x) pixel size in mm.

Pixel size (y)    PIX_Y[]        The (y) pixel size in mm.

Image axis name   IX1_NAME[]      Name of first image  axis

Image axis name   IX2_NAME[]      Name of second image axis

Type              IMAGE_TYPE[]    Image type e.g. image plate or CCD.

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

Corrections and Offsets

x_c               X_C[][]         'x' centre offset in mm.

y_c               Y_C[][]         'y' centre offset in mm

w_c               W_C[][]         Omega rotation correction in degrees.

Distortion        DISTOR_TYPE[]   Distortion type e.g. standard, rtoff

twist             TWIST[][]       Detector twist in 1/100 degrees.

tilt              TILT[][]        Detector tilt  in 1/100 degrees.

roff              ROFF[][]        MAR 'radial' offset.

toff              TOFF[][]        MAR 'tangential' offset.

y_scale           Y_SCALE[][]     y/y-corrected pixel size ratio.

Image Format Parameters

File format       IMAGE_FORMAT[]  Image data format e.g. raw, i2, mar.

Pixel data type   IMAGE_DATA[]    Pixel storage in file e.g. byte, i2.

Record length     IMAGE_RECL[]    Image file record length

Image header      IMAGE_HEADER[]  Length of image file header

Axis order        AXORD[]         Axis order e.g. xy, y-x.

Null pixel        NULL_PIXEL[]    Value of pixel to be ignored.

Overload          OVLD_PIXEL[]    Overload pixel value.

No. x-rasters     NXRASTS[]       The number of 'x' rasters.

No. y-rasters     NYRASTS[]       The number of 'y' rasters.

7 Detailed Specification of the Parameters

The following table gives more details about each DDM parameter. The keywords are case insensitive but in the list below, the upper case characters as the start of each keyword indicate the minimum number of characters which need to be specified for that keyword. The type of data and default and permissible value(s) for each parameter are indicated. Crystal set parameters are indicated by the [] appended to the name and set and image dependent parameters are indicated by appending [][] to the name. When data files are written, the full keywords are always output. Where necessary, additional details are given in notes following the list; in these notes a set of related parameters may be described in the same note. The note numbers for the relevant notes are given in the table.

Description       Keyword         Units   Default    Values          Notes

Dataset Parameters
 
Title            TITLe            string  ' '        <=250 chars.     1 
No. crystal sets NUMSETS          integer 1          >=1              2
Diffraction type TYPE             string  Rotation   Rotation,        3
                                                     Weissenberg,
                                                     Laue
Crystal number   CRYStal_number[] integer 0          >=0              4
Number of images NUMIMG[]         integer 1          >=1              5,2
                                                     
Crystal Based Parameters 

Sample Parameters

Crystal system   SYSTem           code    Tri        Tri, Mon, Ort,   6
                                                     Tet, Hex, Rho,
                                                     Cub
Lattice type     LATTice          code    P          P, A, B, C, I,   6
                                                     F, R
Symmetry         SYMMetry         code    (undef)    see note         7
Cell A           A[]              Angst.  100.0      >0.0             8
Cell B           B[]              Angst.  100.0      >0.0             8
Cell C           C[]              Angst.  100.0      >0.0             8
Cell alpha       ALPHa[]          degrees 90.0       >0.0             8
Cell beta        BETA[]           degrees 90.0       >0.0             8
Cell gamma       GAMMa[]          degrees 90.0       >0.0             8
Resolution limit RESOlution[]     Angst.  2.5        >0.0             9
Mosaicity        MOSAicity[]      degrees .05        >=0.0            10
Spot size        SPOT_Size[]      mm      1.0        >0.0             11
                                                     suffixed - may
                                                     have several
                                                     values
Partials limit   NWMAx[]          integer 3          3 to 1000        12

Orientation parameters:

U-matrix         UMATrix[]        9 reals 1 0 0      any              13
                                          0 1 0
                                          0 0 1
Phi-X            PHI_X[]          degrees 0.0        -360.0 to 360.0  14
Phi-Y            PHI_Y[]          degrees 0.0        -360.0 to 360.0  14
Phi-Z            PHI_Z[]          degrees 0.0        -360.0 to 360.0  14
Orientation phi  PHI_Orient[]     degrees 0.0        -360.0 to 360.0  14

Current Experiment

Rotation start   ROTStart[]       degrees 0.0        -360.0 to 360.0  15
                                                     suffixed - may
                                                     have several
                                                     values
Rotation end     ROTEnd[]         degrees 0.0        -360.0 to 360.0  15
                                                     suffixed - may
                                                     have several
                                                     values
Osc/inc          ANGLe_inc[]      degrees 1.0        >0.0             15
(alias name)     ANGLe_osc[]
Image directory  IMAGE_Dir[]      string  ' '        any              16 
Image template   IMAGE_Template[] string  img###.image
                                                     any              16

Detector and Source Parameters

Detector Setting 

Distance         DISTance[]       mm      250.0      >=0.0            17
Maximum radius   RMAX[]           mm      150.0      >0.0             18
Rotation 1       TAU_X[]          degrees 0.0        any              19
Rotation 2       TAU_Y[]          degrees 0.0        any              19
Rotation 3       TAU_Z[]          degrees 0.0        any              19
Weiss. coupling  WEISs_coupling   real    0.0        any              20

Detector Basics 

Detector type    DET_Type[]       code    unknown    unknown, mar ... 21
Det. geometry    DET_Geometry     code    flat       flat,            22
                                                     cylindrical
Orientation      DET_Rotations[]  9 real  1 0 0      -1.0 to 1.0      19
                                          0 1 0
                                          0 0 1
Detector axes    DET_Axes[]       6 real  0 1 0      -1.0 to 1.0      23
                                          0 0 1
Axis 1 name      AX1_name         string  xf         max. 4 chars     24
Axis 2 name      AX2_name         string  yf         max. 4 chars     24
Horizontal axis  IAX_H[]          integer 3          1 to 3           25
Vertical axis    IAX_V[]          integer 2          1 to 3           25
Scan axis        SCAN_axis[]      3 real  0 0 1      -1.0 to 1.0      26
Detector gain    DET_Gain         real    1.0        >0.0

Source parameters 
 
Synchrotron      SYNChrotron[]    code    Yes        Yes/no           27
Wavelength       WAVElength[]     Angst.  1.0        >=0.0            28
Lambda-min       LAMBDA_MIn[]     Angst.  0.5        >0.0             28
Lambda-max       LAMBDA_MAx[]     Angst.  1.5        >lambda-min      28
Dispersion       DISPersion[]     real    0.0015     >=0.0            27
Vert. divergence DIVV[]           degrees 0.01       >=0.0            27
Hori. divergence DIVH[]           degrees 0.10       >=0.0            27
Corr. dispersion DELCor[]         real    0.0        any              27
Polarisation     POLArisation     real    0.0        -1.0 to 1.0      29

Image Based Parameters

 Image basics 

x-centre         X_CEN[]          rasters 0.0 middle >= 0.0           30
y-centre         Y_CEN[]          rasters 0.0 middle >= 0.0           30
Pixel size (x)   PIX_X[]          mm      0.1        > 0.0            31
Pixel size (y)   PIX_Y[]          mm      0.1        > 0.0            31
Axis 1 name      IX1_name         string  xd         max. 4 chars     24
Axis 2 name      IX2_name         string  yd         max. 4 chars     24
Image type       IMAGE_Type[]     code    ip         unknown, ip,     32
                                                     ccd, ... 

Optional Image Limits

Minimum 2-theta  TWOTH_Min[]      degrees 0.0        >= 0.0           18
Minimum radius   RMIN[]           mm      0.0        >= 0.0           18
'rmin' x-centre  R_XCEN[]         rasters 0.0 =x_cen >= 0.0           18
'rmin' y-centre  R_YCEN[]         rasters 0.0 =y_cen >= 0.0           18
Minimum x-raster X_MIN[]          rasters 0.0 (=all) >= 0.0           18
Maximum x-raster X_MAX[]          rasters 0.0 (=all) >= 0.0           18
Minimum y-raster Y_MIN[]          rasters 0.0 (=all) >= 0.0           18
Maximum y-raster Y_MAX[]          rasters 0.0 (=all) >= 0.0           18

Corrections and Offsets

'x_c' offset     X_C[][]          mm      0.0        any              30
'y_c' offset     Y_C[][]          mm      0.0        any              30
'w_c' offset     W_C[][]          degrees 0.0        any              30
Distortion type  DISTOR_Type[]    code    standard   standard, rtoff  33
Detector twist   TWISt[][]        .01 deg 0.0        any              33
Detector tilt    TILT[][]         .01 deg 0.0        any              33
'roff' offset    ROFF[][]         10mu    0.0        any              33
'toff' offset    TOFF[][]         10mu    0.0        any              33
'y_scale'        Y_SCAle[][]      real    1.0        any              31

Image Format Parameters

Image format     IMAGE_Format[]   code    none       raw, byte, i2,   34
                                                     mar ...
Image data       IMAGE_Data[]     code    i2         byte, i2, i4,    34
                                                     squash, squash2,
                                                     squash3, squash4
Record length    IMAGE_Recl[]     int     0          >=0              34
Image header     IMAGE_Header[]   int     0          any              34
Axis order       AXORd[]          code    xy         e.g. xy, y-xs    34, 35
                                                     (see note)
Null pixel       NULL_Pixel[]     integer 0          any              34, 36
Overload pixel   OVLD_Pixel[]     integer 0          >= 0             34, 37
No. x-rasters    NXRAsts[]        integer 0          >=0              34, 38
No. y-rasters    NYRAsts[]        integer 0          >=0              34, 38


Notes:

  1. The title parameter is a character string which is taken from the text following the keyword to the end of the line.

  2. The number of crystal sets for which parameters are defined from 1 up to a program defined limit of (e.g. 10). This parameter is defined when the new keyword data module is initialised for the DDM and, has therefore no shortened form (This also applies to the NUMIMG parameter described below).

  3. The diffraction type which may be 'Rotation' for monochromatic rotation images, 'Weissenberg' for monochromatic Weissenberg images or 'Laue' for Laue diffraction images. The Rotation and Weissenberg cases are essentially the same except that, in the latter case, a coupling parameter is has to be taken into account when determining spot positions on the image. For the Laue case, the LAMBDA_MIN and LAMBDA_MAX parameters are used to define the wavelength range and the monochromatic WAVELENGTH parameter is not used. The ANGLE_OSC parameter used in the Rotation/Weissenberg cases is used as a spindle increment between successive Laue images in the Laue case and can be specified using the alternative ANGLE_INC name.

  4. A crystal may be assigned a crystal number (>0) for identification, If the value is zero, then the set number is used as the crystal number.

  5. This gives the number of images for each crystal set based on the currently defined rotation (/Laue spindle angle sets). Where more than one range is defined, the image numbers continue from one range to the next. For this reason, care must be taken if these ranges are modified in a DDM file which also contains image specific data values. For a program based on the Java Jdl.JdlPX.JdlDiffractionDataModule object, all the image based parameters are automatically adjusted if any of the range parameters are reset. The NUMIMG parameter name must be given in full (see also note 2).

  6. For the crystal system, only the first three characters are matched and, for the lattice type, a single character is matched.

  7. Some calculations e.g. Rotation and Laue simulations may be done without making use of the full symmetry information and with systematic absences being based only on the lattice type. However the full symmetry must be defined to carry out the analyses of reciprocal space coverage, full data analysis etc. The SYMMETRY parameter has a number of options and may not be followed by any other parameter on the same line. These are:
          SYMMETRY CLEAR           Clears out the current symmetry
    
          SYMMETRY nspg            Space group code or number
    
          SYMMETRY op1, op2, ...   Add the symmetry operators to
                                   the current list
    
          If symmetry operators are defined explicitly, then they must
          be terminated by the line 'SYMMETRY END' otherwise the
          symmetry will not be completely defined and some of the
          symmetry handling routines will subsequently return error codes.
    

    The space group code and symmetry operation definitions are the same as those used in the CCP4 Program Suite. If any symmetry operators are input, then, on output, all symmetry operators will be written explicitly including any derived via a space group number. By default the symmetry is treated as undefined.

  8. These are the real cell parameters in Angstoms and degrees.

  9. The resolution limit in Angstroms for reflection prediction and determination of the unique data; for the latter the resolution given for the first crystal set in the dataset is used.

  10. The mosaic spread in degrees.

  11. The spot diameter in mm. Normally, circular spots of a uniform size throughout the image are assumed. The spot size parameter may be used to determine which spots will be spatially overlapped on an image.
    In the processing of Laue data, a more complex description of the spot shape is appropriate. For this reason, SPOT_SIZE has been defined as a 'suffixed' keyword allowing up to 4 values to be given. These will be the values for the spot length, spot width, spot factor and spot border as defined in the Laue Data Module (Campbell, J.W., Clifton, I.J., Harding, M.M. & Hao Q., "The Laue Data Module (LDM) - a software development for Laue X-ray diffraction data processing" J. Appl. Cryst. (1995) 28 635-640.

  12. The parameter NWMAX gives the maximum number of images over which a reflection may spread to be considered as a potentially useful partial. It may have a value from 3 up to 1000.

  13. The U-matrix [U] is a rotation matrix to define a standard orientation. It rotates the crystal cartesian coordinates (x,y,z) to the laboratory cartesian coordinate frame (X,Y,Z). It is usually a simple permutation matrix. The elements are specified in the order U[1,1], U[1,2], U[1,3], U[2,1], U[2,2], U[2,3], U[3,1], U[3,2], U[3,3].

  14. The crystal orientation is defined by a set of crystal rotations phi-X, phi-Y and phi-Z around the laboratory axes X, Y and Z respectively from the setting defined using the U-matrix. The PHI_ORIENT parameter gives the start rotation angle of the goniometer for the image from which the missetting angles were determined.

  15. The rotation ranges are defined by ROTSTART a rotation start angle in degrees and ROTEND a rotation end angle in degrees. The oscillation angle and increment between images is given by ANGLE_INC (ANGLE_OSC). Note that ANGLE_OSC is just an alternative (alias) name for the same parameter ANGLE_INC. For rotation images, where the angle increment divides exactly into the given range, the final image will start at (ROTEND-ANGLE_OSC) and end at ROTEND. For Laue diffraction, the ANGLE_INC is taken as a spindle increment between successive images with the first image setting at ROTSTART and the final one at ROTEND where the angle increment divides exactly into the given range.

    The exact treatment when the range is not a whole multiple of the increment is detailed below.

    ROTSTART and ROTEND are 'suffixed' parameters enabling more than one rotation range to be defined. If required, more than one angle value can be given after these keywords or a number from 1 upwards may be appended to the keyword to refer to a single range. ROTSTART followed by a single value is the same as using ROTSTART1. The following three cases are therefore alternative ways of defining the same pair of ranges.
        ROTSTART 20.0 150.0  ROTEND 60.0 170.0
    
        ROTSTART 20.0 ROTEND 60.0 ROTSTART2 150.0 ROTEND2 170.0
    
        ROTSTART1 20.0 ROTEND1 60.0 ROTSTART2 150.0 ROTEND2 170.0
        
    The maximum number of ranges allowed is under program control and is 6 for the program PXSim.
    If an end angle is less than the corresponding start angle, the range is ignored. The default values for ROTSTART and ROTEND are 0.0, 0.0 for the first range and 'undefined' (actually stored as values of -1000.0) for other ranges. For rotation ranges, both a ROTSTART and ROTEND value for the range must be defined; if the end value for a range is the same as the start value then a single image will be assumed for the first range but no images for other such ranges. For the Laue case only, a ROTSTART value needs to be defined if only a single image is to be recorded at that angle; a single image will also be assumed if the end value is equal to the start value or the start angle plus the angle increment is greater than the end value.

    For rotation ranges, the number of images in a range is rounded up to the nearest whole angle increment.
        no. images =  (int)((rotend-rotstart)/(angle_inc)+0.001) + 1;
        
    For Laue ranges, the number is not rounded up except in the cases described above for a single image.
        no. images =  (int)((rotend-rotstart)/(angle_inc)-0.001) + 1;
        
    Thus, for example, where the increment (e.g. 2.0) fits exactly into a range (e.g. 10.0 to 20.0) there will be 5 oscillation ranges for the rotation case starting at 10.0, 12.0, 14.0, 16.0 and 20.0 degrees but 6 images for the Laue case at 10.0, 12.0, 14.0, 16.0, 18.0, 20.0 degrees.

  16. IMAGE_DIR specifies the directory in which the image files are stored and IMAGE_TEMPLATE gives a template for forming the file names. The directory specification should be complete (e.g. with a trailing '/' in Unix) so that the file name can be directly appended to it. A field of # symbols in the template will be replaced by the image number within the crystal set. The image number will fill at least the number of positions occupied by the # characters with leading zeros being added if required. If no '#' is present in the template, the image number will be added just before the '.' of the file extension; if there is no file extension the image number will be added at the of the template string.

  17. The crystal to detector distance in mm (0.0 = undefined).

  18. The area of the image to be processed is assumed to be the same for each image of a set and is defined by a maximum radius RMAX in mm. There are optional exclusion regions. First, a minimum angle TWOTH_MIN for two theta may be defined. Secondly a minimum radius RMIN can be used to define an exclusion circle. This circle is centered at R_XCEN, R_YCEN whose default values of 0.0, 0.0 are taken to mean that the circle is the be centered at the image centre X_CEN, Y_CEN. Additionally, the processing may be restricted to a rectangular section (by default the whole image) by using the limits X_MIN, X_MAX, Y_MIN AND Y_MAX in raster units. Values of X_MIN=0.0 or Y_MIN=0.0 are the minimum limits of the image in 'x'. Values of X_MAX=0.0 or Y_MAX=0.0 are taken to mean the maximum limits of the image in 'y'. Thus the default values for X_MIN, X_MAX, Y_MIN and Y_MAX cover the whole image.

  19. The detector rotation vectors in terms of the laboratory axes define the axes around which the detector may be rotated. One is normal to the detector and the other two lie parallel to the plane of the detector. These axes pass through the laboratory axes origin (crystal position). The detector lies at the crystal to detector distance along the first detector axis. Any required rotations around these three axes are defined by the TAU_X, TAU_Y and TAU_Z angles. These are positive rotations in degrees around the three defined detector rotation axes respectively. The rotations are applied in the order 'tau_x' then 'tau_y' then 'tau_z'.

  20. When the diffraction type is set to 'Weissenberg', the Weissenberg coupling parameter gives the coupling factor between the detector movement along the second local detector axis scan and the rotation around the scan (rotation) axis. The units for the parameter are mm/degree.

  21. The detector type is a code indicating the detector type if known. This parameter does not imply values for any of the other parameters. It may be used, for example, by programs which need to access detector specific hardware or output files.

  22. The detector geometry may either be 'flat' or 'cylindrical'. In the latter case, it is assumed that the cylinder axis lies along the crystal scan (rotation) axis.

  23. Vectors defining the two local axes (xf, yf) within the plane of the detector and used to specify the predicted spot coordinates. These are defined with respect to the laboratory axes.

  24. The AX1_NAME and AX2_NAME may be used to give user defined names to the two local detector axes used in spot position prediction to give ideal coordinates based on the pattern centre ('xf', 'yf' in coordinate definition). These may, for example, refer to some locally used convention. The limit of 4 characters on the length is to provide a guide for what size of string a program should cope with (i.e. space it needs to allow) when outputting the name e.g. when listing spot coordinates. Similarly IX1_NAME and IX2_NAME may be used to give names to the image coordinate axes ('xd' and 'yd' in coordinate definition). (see Figure 1)

  25. These define which of the three laboratory axes is horizontal and which is vertical (1='X', 2='Y', 3='Z') so that the correct axes may be identified for the horizontal and vertical beam divergence parameters.

  26. In the DDM, the beam vector parameter is fixed a [-1,0,0] being the vector defining the direction of the beam looking towards the X-ray source. SCAN_AXIS is the vector defining the rotation (scan) axis (+ve rotation) both with respect to the laboratory axes.

  27. A keyword indicating whether or not the X-ray source is a synchrotron source and the synchroton parameters of dispersion (delta(lambda)/lambda), horizontal and vertical divergence of the beam in degrees and a correlated component of the wavelength dispersion.

  28. WAVELENGTH is the wavelength in Angstroms for monochromatic diffraction (Rotation or Weissenberg) (0.0 = undefined). LAMBDA_MIN and LAMBDA_MAX are the minimum and maximum wavelengths for the Laue diffraction case.

  29. The X-ray beam polarisation factor.

  30. The X_CEN and Y_CEN parameters define the input or measured position for the centre of the diffraction pattern. The exact centre use for pattern prediction is this input centre with additions of the image dependent refineable camera constants X_C, Y_C and W_C (omega_c) (see Figure 2). If both X_CEN and Y_CEN are zero, the mid point of the image will be taken as the centre position. Note that when a detector is tilted, the centre is where the beam would pass through the detector if it was rotated back to the position with TAU_X, TAU_Y and TAU_Z at zero.

  31. PIX_X and PIX_Y are the pixel dimensions in mm in the 'xd' and 'yd' directions respectively. The Y_SCALE parameter allows for a correction to be made to the relative size of the pixel dimensions in 'xd' and 'yd'. The corrected pixel size in the 'yd' direction is PIX_Y/Y_SCALE. It is treated as an image dependent refineable parameter.

  32. The image type indicates the basic detector type for use during intensity integration. Valid values are currently 'ip' for image plate, 'ccd' for a CCD detector or 'unknown'.

  33. Two ways of describing distortion in the scanned image are currently available. The 'standard' option allows for a TWIST and TILT correction to the detector orientation. The twist correction allows for a small rotation around the detector 'xf' axis and TILT allows for a small rotation around the detector 'yf' axis (see Figure 1). For use with the MAR image plate system the 'rtoff' option allows for radial and tangential offset corrections, parameters ROFF and TOFF, in addition to the twist and tilt corrections. The individuual distortion parameter values are image dependent.

  34. Note: The image format set of parameters are intended to provide the details required to read in an image into a program. It should be noted that these parameters will not necessarily be consistent with those of the image after it has been read in and stored; for example the order of the stored data, or the way in which the individual pixel intensity is held, may be changed. For programs using the JdlDiffractionImage object to read/store images, the relevant information about the image should be retrieved from that object via a JdlImageData object.

    The image format parameter, IMAGE_FORMAT, refers to the image file format used. If the type 'raw' is given then values must be specified for the IMAGE_DATA, IMAGE_RECL and IMAGE_HEADER parameters. 'byte' indicates an image file without a header and with one unsigned byte per pixel. 'i2' indicates an image file without a header and with a two byte unsigned integer value per pixel. For both these formats, the IMAGE_DATA, IMAGE_RECL and IMAGE_HEADER parameters are ignored. The image format 'mar' indicates a MAR image plate format file; for this the parameters IMAGE_DATA, IMAGE_RECL, IMAGE_HEADER, NXRASTS, NYRASTS and AXORD are ignored. Special image types such as 'mar' may also imply other information about the image e.g. the storage of overflow pixels. IMAGE_DATA, when required, indicates the storage format for the pixels. It may be one of the following:
        'byte'    = unsigned byte data
        'i2'      = unsigned two-byte data 
        'i4'      = signed 4 byte integer data 
        'squash'  = 'squashed i2' two byte data, 
                    if stored I<0 ipix = -i*8)
        'squash2' = 'squashed i2' two byte data, 
                    if stored I<0 ipix = (I+32768)*8
        'squash3' = 'squashed i2' two byte data, 
                    if stored I<0 ipix = (I+32768)*32
        'squash4' = 'squashed i2' two byte data, 
                    if stored I<0 ipix = -(I+1)*256 + 32768
        'pic'     = Picture file (pixels stored as packed RGB values)
    

    IMAGE_RECL, when required, gives the image record length in bytes but a value of 0 indicates that the record length may be calculated from the numbers of rasters (and axis order) and the storage size for the pixel as defined via IMAGE_DATA. IMAGE_HEADER, when required, gives the number of header records (if positive) or minus the header length in bytes if negative.

  35. The axis order code, AXORD, defines the axis order in the image file in terms of x and y (the detector xd, yd axes). The slower moving axis is given first followed by the faster moving axis. A minus sign is used when the order of an axis is reversed. The code 's' if present indicates that byte swapping is to be done and the code 'n' indicates that no byte swapping is to be done (byte swapping only relevant for some image data types). Characters, other than 'x', 'y', '-', '+', 's' and 'n', or their upper case equivalents, are ignored. Examples of valid axis order strings are xy, +xd+yd and -yxs. For cases where the axis order is to be determined from the image file, the code 'unset' may be given.

  36. The NULL_PIXEL parameter gives the value for a pixel which is to be disregarded (e.g. not scanned).

  37. The OVLD_PIXEL value indicates that any pixel value greater than or equal to this value is to be treated as an overloaded pixel. A value of zero means that no pixel values are treated as overloads.

  38. The number of x and y rasters (along the detector xd, yd axes) in the image. May be left as the default values of 0 if the IMAGE_FORMAT is 'mar' or 'none'.

8 Standard Set of Output Parameters

When a parameters file is written, a standard set of parameters may be output even if they have the default values. The other parameters will only be output if they have been assigned values either by reading them in from a parameters file or by resetting them within aprogram. The parameters in the standard set are:

TITLE 
NUMSETS
NUMIMG
TYPE
SYSTEM
LATTICE
SYMMETRY
A, B, C, ALPHA, BETA, GAMMA
WAVELENGTH LAMBDA_MIN LAMBDA_MAX
RESOLUTION MOSAICITY 
DISTANCE RMAX
PHI_X PHI_Y PHI_Z
ROTSTART ROTEND ANGLE_INC
NWMAX
SPOT_SIZE
SYNCHROTRON
DET_GEOMETRY
X_CEN
Y_CEN