Diffraction Data Module icon
John W. Campbell
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
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:-
- The crystal parameters such as the crystal symmetry, cell parameters,
crystal orientation parameters and the resolution limit of the
diffraction.
- 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.
- 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.
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.
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
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
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).
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).
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:-
- Only output non-default values.
- 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.
- Output all DDM parameters but minimise output where possible
as in the previous case.
- 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.
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.
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:
- The title parameter is a character string which is taken from the
text following the keyword to the end of the line.
- 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).
- 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.
- 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.
- 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).
- For the crystal system, only the first three characters are
matched and, for the lattice type, a single character is
matched.
- 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.
- These are the real cell parameters in Angstoms and degrees.
- 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.
- The mosaic spread in degrees.
- 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.
- 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.
- 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].
- 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.
- 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.
- 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.
- The crystal to detector distance in mm (0.0 = undefined).
- 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.
- 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'.
- 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.
- 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.
- 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.
- 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.
- 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)
- 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.
- 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.
- 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.
- 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.
- The X-ray beam polarisation factor.
- 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.
- 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.
- 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'.
- 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.
- 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.
- 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.
- The NULL_PIXEL parameter gives the value for a pixel which is to be
disregarded (e.g. not scanned).
- 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.
- 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'.
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