**dtpredict**

SBC01-????-00

May 10, 1995

Prepared by: J.W. Pflugrath

Molecular Structure Corporation

3200 Research Forest Drive

The Woodlands, Texas 77381

\(713\) 363-1033

\(713\) 364-3628 FAX

jwp@msc.com

Prepared for: Contract No. 943072401

Mary Westbrook

Argonne National Laboratory

9700 South Cass Avenue

Argonne, Illinois 60439

\(708\) 252-8914

\(708\) 252-4021 FAX

westbrook@anlel.el.anl.gov

Reviewed by:

Approved by:

Copyright  1995, 1994 Molecular Structure Corporation

RESTRICTED RIGHT NOTICE SHORT FORM (JUNE 1987)

Use, reproduction, or disclosure is subject to restrictions set forth in
Contract No. W-31

109-ENG-38 and Contract No. 943072401 with the University of Chicago,
Operator of

Argonne National Laboratory

**TABLE OF CONTENTS**

**1 Scope and Purpose**

1.1. Definitions and Abbreviations

2 Background

3 Input images

3.1. Source keywords

3.2. Crystal keywords

3.3. Crystal goniometer keywords

3.4. Detector keywords

3.5. Detector goniometer keywords

3.6. Rotation keywords

4 Running dtpredict

4.1. Command line options

4.2. Examples

4.3. Results

4.4. Overcoming difficulties

5 Accessory programs

6 File formats

6.1. Reflection file format

**1 Scope and Purpose**

This document describes how to use the dtpredict module of d\*TREK.
dtpredict produces a list of reflections which will appear on a
2-dimensional position sensitive detector for a given rotation range.
The reflection list contains the Miller indices (hkl), the detector
pixel coordinates, the detector millimeter coordinates, the starting,
central and ending rotation angle values, the polarization correction
factor, the Lorentz correction factor, the oblique incidence correction
factor and the resolution in Ångstroms.

In order to predict the reflection list, dtpredict requires knowledge of
the source, the crystal properties, the crystal goniometer, the crystal
rotation axis, the crystal rotation range, the detector and the detector
goniometer. dtpredict gleans all this information from the header of an
image file, so that additional input is not required to predict
reflections which will fall on an image.

**1.1 Definitions and Abbreviations**

Image An **image** is the output of a position-sensitive detector. It
has a header that describes the image and how it was made. dtpredict
reads image headers to get information about images, so that users do
not need to describe the image to the program.

Rotation A **rotation** describes the goniometer movement while an image
is exposed. It has the following properties:

Rotation axis

The 3D vectorial representation of the rotation axis in world
coordinates when the crystal goniometer is at the datum position. The
axis goes from the crystal position (0,0,0) in the axis direction such
that a right-hand rotation is the positive direction. For example, if
the omega axis points along X, then Rotation axis is (1, 0, 0). General
rotation axes may be easily specified this way. In addition, the crystal
goniometer datum position specifies a rotation angle of 0 around this
axis.

Start angle The angle of the rotation axis at the start of exposure

End angle The angle of the rotation axis at the end of exposure

Increment The difference between the Start angle and End angle

Time The exposure time in seconds of the image

Oscillations The number of times the axis oscillated from the Start
angle to the End angle back to the Start angle. A simple rotation will
have Oscillations equal to 0.

Dark The number of dark images collected before the start of the
rotation and used for non-uniformity correction.

DarkUpdate The dark image update interval. After this number of images,
a new dark image should be made.

DarkLimit The dark image change limit. If the dark current changes by
more than this fraction, then a new dark image should be collected.

DCoffset The number of DC offset images collected before the start of
the rotation and used for non-uniformity correction.

DC Update The DC offset image update interval. After this number of
images, a new DC offset image should be made. This should probably
always be 0.

Scan A **scan** is a set of contiguous (in rotation angle) images with
similar properties. The images are generated by a single detector so
they have the same dimensions, exposure time, angular increment and
non-uniformity of response. A scan has the same global properties as
described for Rotation, but the Scan End Angle is the end angle of the
last image in the scan. Other Scan properties which are not pertinent to
dtpredict are described in the dtfind documentation.

**2 Background**

In order to integrate the intensities of Bragg reflections in a single
crystal diffraction experiment, their positions in images must be
predicted accurately. This can be done provided information about the
source, the crystal, the crystal goniometer, the detector, the detector
goniometer, and the rotation is known. Internally, dtpredict uses the
vectorially description of these objects in order to predict the
positions of Bragg reflections. This vectorial description has been
described in the *Proceedings of the EEC Cooperative Workshop on
Position-Sensitive Detetor Software (Phases I & II)* , *ibid. (Phase
III)*, and in *Computational Aspects of Protein Crystal Data Analysis
DL/SCI/R25*.

In the following discussion, the origin of the world coordinate system
is at the ideal crystal position.

Source Vector

The source vector goes from the origin along the primary beam in the
same direction as the photons or neutrons. If the world Z axis goes from
the crystal towards the beam, then the design source vector **s~d~** is
(0, 0, -1);

Source Orientation

The source may be mis-oriented slightly away from the source vector.
This can be parameterized by rotations around axes perpendicular to the
source vector **u~1~** and **u~2~**. which in turn give rotation
matrices **U~1~**, **U~2~**. The actual source vector used by dtpredict
**s~0~** = **U~2~U~1~S~d~**.

Crystal

The coordinates **r** of a reciprocal lattice point with Miller indices
**h** for a crystal in a standard setting can be derived from the
following equation:

**r** = **Bh** (1)

where **B** is a matrix. The reciprocal lattice of the crystal in a
standard orientation at crystal goniometer angles all 0 as described by
Busing and Levy (1966) is used. In this orientation a\* is along **X**,
b\* is in the **XY** plane. The so-called **B** matrix looks like:

a\* b\*cosγ\* c\*cosβ\*

**B =** 0 b\*sinγ\* -c\*sinβ\*cosα (2)

0 0 c\*sinβ\*sinα

Crystal Orientation

In the real world, crystals are never aligned as described by the **B**
matrix. They are generally rotated away from the standard setting. This
rotation is described by the crystal rotation matrix **C** which can be
decomposed into 3 matrices **C~1~**, **C~2~**, **C~3~** which are
themselves rotations around 3 principle vectors **c~1~**, **c~2~**,
**c~3~**. In d\*TREK and dtpredict, the vectors **c~1~**, **c~2~**,
**c~3~** are specified. The orientation matrix encountered often in the
literature is the **C** matrix times the **B** matrix.

Crystal Goniometer

The crystal goniometer is composed of at most 3 axes which are described
vectorially as **g~1~**, **g~2~**, **g~3~**, where **g~1~** is the axis
closest to the baseplate (e.g. ω) and **g~3~** is the axis closest to
the crystal (e.g. φ) The crystal goniometer datum position describes the
values of rotations around these axes when the crystal rotation axis has
a value of 0. If the rotations around the three goniometer axis, the
overall goniometer rotation matrix **G** is **G~3~G~2~G~1~**.

Crystal Rotation

In a rotation experiment, the crystal is rotated around an axis **r~1~**
to continually bring new Bragg reflections into the diffracting
condition. This rotation can be described by the matrix **R**.

With all the rotations applied, the equation to convert a Bragg
reflection to a reciprocal lattice point in the diffracting position is:

**r~d~** = **RGCBh** (3)

With regards to predicting reflections, the matrices **G**, **C**, and
**B** are known, while the **R** matrix must be determined and the
rotation angle derived from it.

Detector

A vectorial way to relate detector pixel coordinates (in the detector
focal plane) has been described. Let **d~1~** and **d~2~** be the basis
vectors to convert the two pixel directions to the two focal plane
millimeter directions. Let **d~o~** be the vector from the world origin
to the origin of the coordinates on the detector (e.g. the 0.0, 0.0
millimeter coordinate). The coordinates on the ideal flat focal plane of
the detector that correspond to the point **r~d~** (3) satisfy (4):

X**d~1~** + Y**d~2~** + **d~o~** = α **t**

X

\[ **d~1~** \| **d~2~** \| **d~0~**\] Y = α**t** (4)

1

where **t** is a vector coincident with the scattered beam wavevector
**s** = **s~0~** + **r~d~**

Let

\[ **d~1~** \| **d~2~** \| **d~o~**\] = **d** (5)

**D** = \[**d**\]^-1^ = \[**D~1~** \| **D~2~** \| **D~o~**\]^-1^ (6)

u 

**v** =  v  **Dt** (7)

. w

X = u /w (8)

Y = v / w

Now the rotation axis angle coordinate is determined. The diffraction
condition is

**t** • **t** = **s** • **s** (9)

**r** • **r** - 2 **r** • **s** = 0

Detector Goniometer

The vectors **d~1~**, **d~2~** and **d~o~** in the preceding paragraph
describe an unrotated detector. Since the detector is often rotated by a
goniometer, especially around the 2θ axis, these vectors must be
rotated, too. Let **E** be the matrix that describes the detector
goniometer matrix. It is specified in the same way as the crystal
goniometer matrix.

Thus, numerous vectors and rotation angles around these vectors are
needed by dtpredict in order to predict a list of reflections. It gets
this information from an image header.

**3 Input image**

The dtpredict requires one or more images as input. It reads the headers
of input images to get the experimental conditions of the source,
crystal, crystal goniometer, rotation, detector and detector goniometer.
dtpredict does not read the binary pixel data in the image which may be
even be missing (i.e. the image is dimensioned 0 by 0). If the detector
spatial distortion and non-uniformity of response information in a
header requires additional images to be read in, then dtpredict does so
automatically. A typical image header is shown below followed by
descriptions of the keywords required by dtpredict.

1.  {

    HEADER_BYTES= 2048;

    TYPE=mad;

    SIZE1=512;

    SIZE2=512;

    COMMENT=Header edited by dtheaderedit;

    SCAN_TITLE=start end inc time nOsc nDark nDup nDlim nDC nDCup;

    SCAN_ROTATION=0.0 12.0 0.2 4 0 1 0 100 1 0;

    SCAN_ROTATION_AXIS_NAME=omega;

    SCAN_ROTATION_VECTOR=1.0 0.0 0.0;

    SCAN_TEMPLATE=proteinX##.img;

    SCAN_SEQ_INFO=1 1 1;

    ROTATION=0.0 0.2 0.2 4 0 1 0 100 1 0;

    ROTATION_VECTOR=1.0 0.0 0.0;

    ROTATION_AXIS_NAME=Omega;

    CRYSTAL_UNIT_CELL=82.34 88.29 103.65 90.00 90.00 90.00;

    CRYSTAL_MOSAICSPREAD=0.145;

    CRYSTAL_DESCRIPTION=Test of dtpredict;

    CRYSTAL_SPACEGROUP=19;

    CRYSTAL_REFINE_FLAGS=0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0;

    CRYSTAL_ORIENT_ANGLES=10.04 -26.37 31.81;

    CRYSTAL_ORIENT_VECTORS=1 0 0 0 1 0 0 0 1;

    SOURCE_VECTORS=0.0 0.0 -1.0 1 0 0 0 1 0;

    SOURCE_POLARZ=0.5 1.0 0.0 0.0;

    SOURCE_SPECTRAL_DISPERSION=0.0002 0.0002;

    SOURCE_SIZE=0.0 0.0 0.0 0.0;

    SOURCE_CROSSFIRE=0.0 0.0 0.0 0.0;

    SOURCE_WAVELENGTH=1 1.54178;

    SOURCE_REFINE_FLAGS=0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0;

    DETECTOR_NUMBER=1;

    DETECTOR_NAMES=D0\_;

    D0_NONUNF_TYPE=Dark_only;

    D0_NONUNF_INFO=nonunf.img dark.img;

    D0_SPATIAL_DISTORTION_TYPE=Interp_spatial;

    D0_SPATIAL_DISTORTION_INFO=distor;

    D0_DETECTOR_DIMENSIONS=512 512;

    D0_DETECTOR_SIZE=50.0 50.0;

    D0_DETECTOR_VECTORS=1 0 0 0 1 0;

    D0_DETECTOR_DESCRIPTION=ANL-SBC gold detector single module;

    D0_DETECTOR_REFINE_FLAGS=0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0;

    D0_GONIO_NUM_VALUES=6;

    D0_GONIO_NAMES=RotX RotY RotZ TransX TransY TransZ;

    D0_GONIO_UNITS=deg deg deg mm mm mm;

    D0_GONIO_VECTORS=1 0 0 0 1 0 0 0 1 1 0 0 0 1 0 0 0 -1;

    D0_GONIO_VALUES=0.0 0.0 0.0 0.0 0.0 102.3;

    D0_GONIO_DESCRIPTION=A simple detector goniostat;

    CRYSTAL_GONIO_NUM_VALUES=3;

    CRYSTAL_GONIO_NAMES=Omega Chi Phi;

    CRYSTAL_GONIO_UNITS=deg deg deg;

    CRYSTAL_GONIO_VECTORS=1 0 0 0 1 0 1 0 0;

    CRYSTAL_GONIO_VALUES=0.0 0.0 0.0;

    CRYSTAL_GONIO_DESCRIPTION=A 3-circle eulerian crystal goniostat;

    FILENAME=proteinX01.img;

    BYTE_ORDER=big_endian;

    Data_type=short int;

    COMPRESSION=None;

    }

**3.1 Source keywords**

The following keywords related to source properties are required in the
header of the input image specified on the command line with the -scan
or -image option:

SOURCE_VECTORS s~0x~ s~0y~ s~0z~ s~1x~ s~1y~ s~1z~ s~2x~ s~2y~ s~2z~

Specifies the direction **s~0~** of the incident beam plus two vectors
**s~1~** and **s~2~** perpendicular to **s~0~** around which the beam
rotation is refined. *For now, always have s~0~ = (0, 0, -1), s~1~ = (1,
0, 0) and s~2~ = (0, 1, 0). This keyword need not be present as the
vectors will default to these values.*

SOURCE_ORIENT_ANGLES s~1~ s~2~

The small angles around **s~1~** and **s~2~** that the source vector
**s~0~** makes. In practice, these are usually 0, 0.

SOURCE_POLARZ f~p~ pn~x~ pn~y~ pn~z~

The degree of polarization of the source and a vector normal to the
plane of polarization as described by Kabsch (1988).

SOURCE_CROSSFIRE c~11~ c~12~ c~12~ c~22~

The source crossfire specified in degrees. This is not used yet by
dtpredict but may be used in the future.

SOURCE_WAVELENGTH w

The source wavelength in Ångstroms.

**3.2 Crystal keywords**

The following keywords related to crystal properties are required in the
header of the input image specified on the command line with the -scan
or -image option:

CRYSTAL_UNIT_CELL a b c α β γ

This specifies the crystal unit cell in Ångstroms and degrees.

CRYSTAL_ORIENT_ANGLES c~1~ c~2~ c~3~

Three angles which specify the rotation of the crystal away from the
standard orientation when the crystal goniometer angles are all 0.

CRYSTAL_ORIENT_VECTORS c~1x~ c~1y~ c~1z~ c~2x~­ c~2y~ c~2z~ c~3x~ c~3y~
c~3z~

3D vectors which correspond to the directions of rotation for the
CRYSTAL_ORIENT_ANGLES. *For now, these should be defined at (1, 0, 0),
(0, 1, 0) and (0, 0, 1).* *This keyword need not be present as the
vectors will default to these values.*

CRYSTAL_SPACEGROUP n

The spacegroup of the crystal from the International Tables. This is
used to test for systematic absences which will not be predicted.

CRYSTAL_MOSAICSPREAD mosaicity

The effective mosaic spread of the crystal in degrees as described by
Greenhough and Helliwell (1982).

**3.3 Crystal goniometer keywords**

The following keywords related to the crystal goniometer are required in
the header of the input image specified on the command line with the
-scan or -image option:

CRYSTAL_GONIO_NUM_VALUES n

The number of crystal goniometer axes.

CRYSTAL_GONIO_NAMES name~1~ name~2~ name~3~ \... name~n~

The names of the axes. They must appear in the order from the goniometer
baseplate to the crystal. The rotations of the axes will be applied in
the reverse order.

CRYSTAL_GONIO_VECTORS g~1x~ g~1y~ g~1z~ g~2x~ g~2y~ g~2z~ g~3x~ g~3y~
g~3z\ \...~ g~nx~ g~ny~ g~nz~

The vectors describing goniometer rotation axes.

CRYSTAL_GONIO_VALUES g~1~ g~2~ g~3~ \... g~n~

The goniometer axes angles at the datum position. That is, the
goniometer angles when the crystal is at a rotation angle of 0.

CRYSTAL_GONIO_UNITS units~1~ units~2~ units~3~ \... units~n~

The units of the goniometer axes. This MUST be 'degs'. Other possible
units are 'mm 'which is reserved for translations.

**3.4 Detector keywords**

The following keywords related to the detector goniometer are required
in the header of the input image specified on the command line with the
-scan or -image option:

DETECTOR_NUMBER n

The number of detectors. dtpredict will predict reflections for each
detector in turn.

DETECTOR_NAMES name~1~ name~2~ name~3~ \... name~n~

Specifies the names of each of the detectors. The names are important as
each name will be prepended to a keyword in order to get the detector
properties from the image header. For readability of the image header,
each name should end with underscore character. For the following
keywords, the names found here are substituted into the *dname\_*
characters.

*dname\_*DETECTOR_DIMENSIONS dim~1~ dim~2~

The pixel dimensions of the detector image with dim~1~ being the
dimension of the fastest varying direction. In the header listing above,
there is one detector whose name is D0\_, so the keyword is
D0_DETECTOR_DIMENSIONS.

*dname\_*DETECTOR_SIZE mm~1~ mm~2~

The nominal size of the detector in millimeters.

*dname\_*DETECTOR_VECTORS p~1x~ p~1y~ p~1z~ p~2x~ p~2y~ p~2z~

The vectors which relate pixel directions 1 & 2 to laboratory
coordinates. For example, if pixel direction 1 is along Y and pixel
direction 2 is antiparallel to X, the values would be 0 1 0 -1 0 0.

*dname\_*NONUNF_TYPE nonunf_type

Specifies the type of non-uniformity correction to apply to images.
dtpredict will use the NONUNF_TYPE and NONUNF_INFO values to flag
reflections which are predicted to be in a bad non-uniformity regions.
The possible values for nonunf_type are:

None

Simple_scale

Dark_only

Dark_dcoffset

*dname\_*NONUNF_INFO dependent on nonunf_type

The values here depend on the option specified by *dname\_*NONUNF_TYPE
keyword, but generally they contain the non-uniformity files in the
order: non-uniformity image, dark current image, and Dcoffset image. In
the example above, the type is Dark_only, so only the non-uniformity
image (nonunf.img) and the dark current image (dark.img) are specified
there.

*dname\_*SPATIAL_DISTORTION_TYPE spatial_distortion_type

Specifies the type of spatial-distortion correction to apply to when
converting from millimeters to pixels and the reverse. The possible
values for spatial_distortion_type are:

Simple_spatial

Interp_spatial

Other possibilities may be added in the future. With type Simple_scale a
simple linear scaling of pixels is performed to convert to millimeters.
With type Interp_table the spatial distortion tables of the dtcalibrate
program are used. The extra information needed to complete the spatial
distortion description is found in the next keyword.

*dname\_*SPATIAL_DISTORTION_INFO dependent on spatial_distortion_type

If the spatial_distortion_type is Simple_spatial, then 4 values are read
in which specify the primary beam center in pixels and the pixel sizes
in millimeters for the fast and slow varying pixel directions in the
image. If the type is Interp_spatial as in the example above (line 35),
then keyword value specifies the interpolation table fileset basename
(line 36).

**3.5 Detector goniometer keywords**

The following keywords related to the detector goniometer are required
in the header of the input image specified on the command line with the
-scan or -image option:

*dname\_*GONIO_NUM_VALUES n

The number of crystal goniometer axes.

*dname\_*GONIO_NAMES name~1~ name~2~ name~3~ \... name~n~

The names of the axes. Rotations must appear in the sequence first and
must be in the order they will be applied. Translations must appear
after all rotations. Translations can be in any order as their values
will be summed to arrive at the detector translation vector.

*dname\_*GONIO_VECTORS g~1x~ g~1y~ g~1z~ g~2x~ g~2y~ g~2z~ g~3x~ g~3y~
g~3z~ \... g~nx~ g~ny~ g~nz~

The vectors describing goniometer rotation and translation axes.

*dname\_*GONIO_VALUES g~1~ g~2~ g~3~ \... g~n~

The goniometer values for the angles and translations at the datum
position. That is, the position of the detector when the image was
exposed.

*dname\_*GONIO_UNITS units~1~ units~2~ units~3~ \... units~n~

The units of the goniometer values. Rotation axes MUST be have units
'degs', while translations must be 'mm'.

**3.6 Rotation keywords**

The following keywords related to the crystal rotation are required in
the header of the input image specified on the command line with the
-image option. If the -scan option is used, then the keywords below are
prepended with SCAN\_. For example, instead of the ROTATION, the keyword
would be SCAN_ROTATION. As a reminder of this in the text below, this
keywords have the optional *SCAN\_* prepended to them*.*

*SCAN\_*ROTATION Start End Incr time nosc ndark ndarkup dlim ndc ndcup

The 10 values specify the Start and End angles in degrees relative to
the CRYSTAL_GONIO_VALUES, the angular increment per image, the exposure
time in seconds, the number of oscillations, the number of dark images
taken at the beginning of the rotation, the dark image update interval,
the dark image change limit, the number of DC offset images taken at the
beginning of the rotation and the DC offset image update interval. If
this keyword applies to a scan (SCAN_ROTATION), then the Start and End
specify the overall start and end of the scan. If this keyword applies
to a single image (ROTATION), the Start and End specify the rotation
angles within a scan for the image.

*SCAN\_*ROTATION_VECTOR r~x~ r~y~ r~z~

Specifies the rotation axis vector in world coordinates at the crystal
goniometer datum position.

*SCAN\_*ROTATION_AXIS_NAME name

Specifies the axis name. Usually the crystal is rotated around a crystal
goniometer hardware axis and this name helps reminds one which one was
used. The name is not used by dtpredict.

**4 Running dtpredict**

After dtpredict has been installed and placed in your PATH, just enter
dtpredict along with command line options to run it. It parses the
command line arguments, reads any required input images, spatial
distortion files, non-uniformity files and writes a reflection file if
reflections are predicted. Messages are written to stdout and stderr as
required. The syntax for running dtpredict is:

dtpredict \[-scan scanfile \| -image imagefile\] \[ -reso rmin rmax \|

‑rot start end \| -list\]

**4.1 Command line options**

Although dtpredict will run without any command line options if scan
information is found in the header of a file called scan.img in the
current working directory, most situations will benefit from the use of
one or more command line options described below.

**Command line options: Description and default**

-scan sName The header of image sName (no default) is read for the
keywords described in section 3 to set up the experiment properties
required for predicting reflections. The keywords SCAN_ROTATION,
SCAN_ROTATION_VECTOR are used to specify the rotation properties. If
neither a -scan option nor an -image option is specified, then dtpredict
uses \'-scan scan.img\' as the default.

-image sName The header of image sName (no default) is read for the
keywords described in section 3 to set up the experiment properties
required for predicting reflections. The keywords ROTATION,
ROTATION_VECTOR are used to specify the rotation properties. If neither
a -scan option nor a -image option is specified, then dtpredict uses
\'-scan scan.img\' as the default. Up to 20 -image options may be used
on a single command line.

-list The option cause the experimental conditions to be echoed to
stdout before a prediction is made. This is useful to confirm that any
image header has been interpreted properly. The default is not to list
this information.

-ref sReflectionFileName

Specifies an alternate output reflection file instead of the default
dtpredict.ref. The file format is a standard d\*TREK reflection file
format described in section 7.

-reso fReso1 fReso2

A resolution range in Ångstroms which overrides the default resolution
range determined from the source wavelength and the detector(s)
position. In order not miss any reflection on the image, do not use this
option.

-rot fStart fEnd

A rotation range in degrees which overrides the default rotation range
determined from the *SCAN\_*ROTATION keyword. fStart must be less than
fEnd. The keyword CRYSTAL_GONIO_VALUES in the image header specifies the
position of the crystal at an fStart of 0.

**4.2 Examples**

dtpredict -scan ribozyme.0003 -rot 0 5

The above command line reads image ribozyme.0003 for scan information
and overrides the rotation range value found in the image with a new
range of 0 to 5 degrees. Any non-uniformity correction information is
found in the header of image ribozyme.0003 which in turn points to the
non-uniformity files. Results are written to the file dtpredict.ref.

dtpredict -scan hivrt.0001 -reso 2 50

The above command line reads image hivrt.0001 for scan information and
overrides the default resolution value of the entire detector surface
with a resolution range of 2 to 50 Ångstroms.

dtpredict -image hivrt.0002 -image hivrt.0003 -list -ref hivrt.ref;

The above command line reads predicts reflections that are found on
images hivrt.0002 and hivrt.0003. It lists the experimental setup for
each image. All reflections are written to the file hivrt.ref instead of
dtpredict.ref.

**4.3 Results**

The command:

dtpredict -scan proteinX01.img -list

produced the following output which is explained below.

1.  File proteinX01.img successfully opened.

2.  Header of file proteinX01.img successfully read.

3.  Image is 512 by 512 pixels.

4.  Data_type in header is short int.

5.  Compression_type is None.

6.  Byte_order is big_endian.

7.  File distor.calpar successfully opened.

8.  Warning in Cimage_header::nRead, header does not have proper ending!

9.  Info in Cimage_header::nRead, able to repair ending!

10. File distor.x_int successfully opened.

11. Warning in Cimage_header::nRead, header does not have proper ending!

12. Info in Cimage_header::nRead, able to repair ending!

13. Header of file distor.x_int successfully read.

14. Image is 256 by 256 pixels.

15. Byte_order is big_endian.

16. File distor.y_int successfully opened.

17. Warning in Cimage_header::nRead, header does not have proper ending!

18. Info in Cimage_header::nRead, able to repair ending!

19. Header of file distor.y_int successfully read.

20. Image is 256 by 256 pixels.

21. Byte_order is big_endian.

22. File distor.inv_x_int successfully opened.

23. Warning in Cimage_header::nRead, header does not have proper ending!

24. Info in Cimage_header::nRead, able to repair ending!

25. Header of file distor.inv_x_int successfully read.

26. Image is 256 by 256 pixels.

27. Byte_order is big_endian.

28. File distor.inv_y_int successfully opened.

29. Warning in Cimage_header::nRead, header does not have proper ending!

30. Info in Cimage_header::nRead, able to repair ending!

31. Header of file distor.inv_y_int successfully read.

32. Image is 256 by 256 pixels.

33. Byte_order is big_endian.

34. D0_NONUNF_TYPE: \>\>Dark_only\<\<

35. Cnonunf::nInitValues called

36. File nonunf.img successfully opened.

37. Header of file nonunf.img successfully read.

38. Image is 512 by 512 pixels.

39. Data_type in header is short int.

40. Compression_type is None.

41. Byte_order is big_endian.

42. File dark.img successfully opened.

43. Header of file dark.img successfully read.

44. Image is 512 by 512 pixels.

45. Data_type in header is short int.

46. Compression_type is None.

47. Byte_order is big_endian.

48. There were 262144 pixels, with 0 bad pixels in the nonunf file.

49. Predict listing:

50. Crystal listing:

51. Unit cell lengths: 82.34, 88.29, 103.65

52. Unit cell angles: 90, 90, 90

53. Unit cell volume: 753515

54. Spacegroup number: 19

55. Orientation angles: 10.04, -26.37, 31.81

56. Mosaic Spread: 0.145

57. Description: Test of dtpredict

58. CRYSTAL_Goniometer listing:

59. Description: A 3-circle eulerian crystal goniostat

60. Number of values: 3

61. Value 0 name: Omega

62. units: deg

63. Vector: 1, 0, 0

64. Datum value: 0

65. Current value: Unknown

66. Value 1 name: Chi

67. units: deg

68. Vector: 0, 1, 0

69. Datum value: 0

70. Current value: Unknown

71. Value 2 name: Phi

72. units: deg

73. Vector: 1, 0, 0

74. Datum value: 0

75. Current value: Unknown

76. Source listing:

77. Single wavelength: 1.54178

78. Direction vector: 0, 0, -1

79. Spectral Dispersion: 0.0002, 0.0002

80. Crossfire: 0, 0, 0, 0

81. Polarization: 0.5, 1, 0, 0

82. Size: 0, 0, 0, 0

83. Intensity: 0

84. Refinement flags: Not yet available

85. D0_Detector listing:

86. Pixel dimensions: 512, 512

87. Nominal size in mm: 50, 50

88. Description: ANL-SBC gold detector single module

89. Rotation: 0, 0, 0

90. Translation: 0, 0, -102.3

91. Fast pixel vector: 1, 0, 0

92. Slow pixel vector: 0, 1, 0

93. D0_Goniometer listing:

94. Description: A simple detector goniostat

95. Number of values: 6

96. Value 0 name: RotX

97. units: deg

98. Vector: 1, 0, 0

99. Datum value: 0

100. Current value: Unknown

101. Value 1 name: RotY

102. units: deg

103. Vector: 0, 1, 0

104. Datum value: 0

105. Current value: Unknown

106. Value 2 name: RotZ

107. units: deg

108. Vector: 0, 0, 1

109. Datum value: 0

110. Current value: Unknown

111. Value 3 name: TransX

112. units: mm

113. Vector: 1, 0, 0

114. Datum value: 0

115. Current value: Unknown

116. Value 4 name: TransY

117. units: mm

118. Vector: 0, 1, 0

119. Datum value: 0

120. Current value: Unknown

121. Value 5 name: TransZ

122. units: mm

123. Vector: 0, 0, -1

124. Datum value: 102.3

125. Current value: Unknown

126. DetResolution min: 154178

127. DetResolution max: 5.23813

128. Rotation list:

129. Start: 0

130. End: 12

131. Increment: 0.2

132. Time: 4

133. Oscillations: 0

134. Axis vector: 1, 0, 0

135. Axis name: Omega

136. Dark start: 1

137. Dark update: 0

138. Dark change limit: 100

139. DCoffset start: 1

140. DCoffset update: 0

141. Predict resol min: 999999

142. Predict resol max: 0.5

143. dtpredict: There were 828 reflections predicted.

144. dtpredict: Reflections written to dtpredict.ref

**Explanation**

Lines 1-9 The file proteinX01.img was opened and read in.

Lines 10-35 The detector spatial distortion correction requires that an
interpolation table fileset be read in. These lines show these files
have been successfully read.

Lines 36-48 The detector non-uniformity correction requires that
non-uniformity image and a dark image be read in. These lines show these
files have been successfully read.

Lines 49-142 These lines show the properties of the crystal, crystal
goniometer, source, detector, and rotation which is the result of the
-list command line option. Most of this information is found in the
header of the input image proteinX01.img although some is calculated
from values in the header.

Lines 64, 69, 74, 99, 104, 109, 114, 119, 124

These shows the values of the crystal and detector goniometers when the
rotation angle is 0.

Lines 65, 70, 5, 100, 105, 110, 115, 120, 125

The current values of the crystal and detector goniometers are unknown
since dtpredict is not physically connected in any way to these hardware
devices. These values are not used by dtpredict in any case.

Lines 129-130 Reflections wll be predicted which diffract between a
rotation angle of 0° and 12°.

Lines 126-127 The calculated minimum and maximum resolution of pixels on
the detector. These will ultimately limit the resolution range of the
predicted reflections although the range may be restricted further by a
-reso command line option. In no case will dtpredict predict reflections
that do not fall on a detector.

Lines 141-142 The dtpredict resolution range which may be restricted
further by the detector size and position (see Lines 126-127).

Line 143 There were 828 reflections predicted.

Line 144 The reflections were written to a file called dtpredict.ref
which is the default filename.

**4.4 Overcoming difficulties**

Since dtpredict gets almost all of its input information from an image
header, difficulties may arise when the header is incomplete. Be sure
that the detector spatial distortion information and non-uniformity
information is correct and the files exist in the current directory or
the filenames in the header include the path or directory.

The output of dtpredict clearly shows when any files have not been read
properly. Use the -list command line option to display the source,
crystal, goniometers, detector and rotation properties. If these are
incorrect, then the image header is incorrect and should be modified.

In these cases, add or correct the information (use dtheaderedit, see
section 5) and run dtpredict again.

**5 Accessory programs**

Since dtpredict gets all image information from the image header, it may
be useful to create and edit image headers from time to time. Since
headers are ASCII characters, use a text editor such as GNU emacs to do
this. The program dtheaderedit may also be used. It keeps track of the
length of the header and prevents the modification of keywords that
describe the binary data in the image file. Input to dtheaderedit comes
from stdin and consists of the name of the input image file, the name of
the output image file, then keyword value pairs until an end-of-file is
found on the stdin. Separate keyword and value by a whitespace (not an
equal sign). Any value that contains whitespace must be enclosed in
single quotes.

If a keyword exists in the header, the value is replaced. If the keyword
does not exist, the keyword=value; pair is added. To delete a
keyword=value; pair enter the keyword followed by 2 single quotes:
**keyword ''**.

An example of a dtheaderedit session can be found in the dtfind
documentation.

One potential problem is that dtheaderedit requires an image file. If
one is not handy, one may be created with the dtcreate program:

1.  \% **dtcreate**

2.  dtcreate: Copyright (c) 1995 Molecular Structure Corporation

3.  dtcreate: Enter output image name,

4.  its dimensions and constant value: **predict.img 0 0 100**

5.  File predict.img successfully opened.

6.  dtcreate: Done

As shown above it is perfectly OK for an image file to have no pixels.
The file contains only a header which must be modified with dtheaderedit
to serve as input to dtpredict.

**6 File formats**

Image file formats are discussed in the calibrate documentation. An
example of an image header is given in Section 3.

**6.1 Reflection file format**

Reflection files have the following format. First they are all ASCII
characters. The first line consists of 3 numbers designating the number
of integer, float and string fields that each reflection has. After this
are the field labels as character strings, one per line for the integer
fields first, then the float fields, then the string fields. The first 3
fields of the reflection file are H, K, L. The first 2 float fields are
Intensity and SigmaI. No other fields are required. Field labels must
contain no whitespace. After the field labels, comes the reflection
data, one reflection per line in free format. This format is a prelude
to using a true CIF reflection file format.

dtpredict adds the following fields to a reflection list and calculates
their values for each reflection

Detector_number

The detector number from the DETECTOR_NAMES field. The first detector is
numbered 0.

Nonunf_flag

A non-uniformity of response flag. If not 0, the predicted pixel
position is flagged as bad in the non-uniformity file.

Calc_pixel1

Calc_pixel2

These are the calculated pixel coordinates of the reflection centroid on
the detector and in the image. The first value corresponds to the fast
varying pixel direction and the second value to the slowest varying
pixel direction. These directions may be along a row, a column,
horizontal, vertical or none of these depending on the detector
orientation, position and spatial distortion.

Calc_1mm

Calc_2mm

The calculated millimeter coordinates for the reflection centroid on an
ideal focal plane detector. The directions of the first and second mm
axes are system dependent, but can be generally considered to lie along
the Xmm and Ymm laboratory axes.

Calc_rot_start

The calculated rotation angle in degrees when the reflection first
begins to diffract.

Calc_rot_end

The calculated rotation angle in degrees when the reflection stops
diffracting.

Calc_rot_mid

The calculated rotation angle when the reflection lies exactly on the
Ewald sphere.

Calc_rot_width

The calculated rotation angle width in degrees.

Calc_polarz

The calculated polarization correction factor P, such that I~true~ = P
I~obs~.

Calc_lorentz

The calculated Lorentz correction factor L, such that I~true~ = L
I~obs~.

Calc_oblique

The calculated oblique incidence correction factor O, such that I~true~
= O I~obs~. *Be careful as it may not be necessary to correct for this.*

Calc_partial

A field for the partiality of a reflection which is not calculated by
dtpredict.

Resolution

The resolution of the reflection in Ångstroms which is dependent on the
source wavelength (of course).

Calc_recip1

Calc_recip2

Calc_recip3

The reciprocal lattice coordinates of the reflection on the Ewald sphere
in dimensionless units (i.e. the Ewald sphere has a radius of 1 Å^-1^).

Below is a truncated example of a reflection file created by dtpredict.
Lines 24-34 are too long to fit across a page so they are wrapped below.

1.  H 5 18 0

2.  K

3.  L

4.  Detector_number

5.  Nonunf_flag

6.  Intensity

7.  SigmaI

8.  Calc_pixel0

9.  Calc_pixel1

10. Calc_0mm

11. Calc_1mm

12. Calc_rot_start

13. Calc_rot_end

14. Calc_rot_mid

15. Calc_rot_width

16. Calc_polarz

17. Calc_lorentz

18. Calc_oblique

19. Calc_partial

20. Resolution

21. Calc_recip1

22. Calc_recip2

23. Calc_recip3

24. 2 -12 0 0 -999 -999 5.539 2.48132 -21.647 -21.7509 2.84386 3.053
    2.94843 0.209144 0.979688 4.96143 -1.05489 -999 5.33334 0.200591
    0.201555 -0.0520377

25. 1 -11 0 0 -999 -999 1.5939 29.8988 -22.061 -19.4289 0.843981 1.06717
    0.955578 0.223193 0.98344 5.49488 -1.04359 -999 5.53591 0.206642
    0.181987 -0.0417703

26. 2 -11 0 0 -999 -999 31.5765 23.4825 -19.5596 -20.087 3.60743 3.81433
    3.71088 0.206898 0.982499 5.34514 -1.04954 -999 5.81014 0.182173
    0.187086 -0.0472011

27. 2 -11 0 0 -999 -999 14.9786 13.5911 -20.9124 -20.8533 -0.146523
    0.0620606 -0.0422311 0.208583 0.980817 5.10531 -1.04069 -999 5.50354
    0.19643 0.195875 -0.0390982

28. 3 -11 0 0 -999 -999 44.9524 7.10276 -18.4115 -21.517 2.3765 2.57117
    2.47383 0.194676 0.979806 4.97597 -1.04661 -999 5.74824 0.17196
    0.200966 -0.0445335

29. -1 -10 0 0 -999 -999 0.385201 82.9582 -22.2876 -14.9281 3.94615
    4.21199 4.07907 0.265837 0.990235 7.1555 -1.04417 -999 6.05412
    0.20865 0.139753 -0.0422987

30. 0 -10 0 0 -999 -999 13.6456 66.6067 -21.1375 -16.365 2.64951 2.89076
    2.77013 0.241251 0.988198 6.50901 -1.04125 -999 6.06841 0.198437
    0.153633 -0.0396151

31. 1 -10 0 0 -999 -999 26.9955 50.292 -19.9939 -17.7943 1.45457 1.67635
    1.56546 0.221777 0.985969 5.96953 -1.03835 -999 6.05412 0.188224
    0.167517 -0.0369372

32. 2 -10 0 0 -999 -999 40.2075 34.1359 -18.8567 -19.2161 0.34025
    0.546486 0.443368 0.206236 0.983546 5.51256 -1.03548 -999 6.01187
    0.178012 0.181404 -0.034265

33. 3 -10 0 0 -999 -999 69.6918 27.5982 -16.3569 -19.8671 2.93466
    3.12618 3.03042 0.191514 0.98261 5.36213 -1.04135 -999 6.29788
    0.153542 0.186493 -0.0397066

34. 4 -10 0 0 -999 -999 82.7698 11.3977 -15.2267 -21.287 1.65424 1.83562
    1.74493 0.181387 0.979925 4.99062 -1.03847 -999 6.18864 0.14333
    0.200376 -0.0370447

35. \...

The Intensity, SigmaI and Calc_partial values have not been set by
dtpredict, so they have default values of -999.