The files generated by XDS are either ASCII type files that can be inspected and modified by using a text editor, or binary, compressed image files that can be looked at using the VIEW program.

All files have a fixed name defined by XDS, which makes it mandatory to process each data set in a newly created directory to avoid name clashes. Clearly, one should not run more than one XDS-job simultaneously in any given directory.

Rotation data images are processed in 8 steps which are called in succession by XDS. Results and diagnostics from each step are documented in files with the name extension .LP for inspection by the user. Information between the steps is exchanged by files, which allows repetition of selected steps with a different set of input parameters without rerunning the whole program. Note, that by rerunning a processing step the earlier version of the output files from this step will be overwritten. Thus, these older files should first be given another name if their original contents are meant to be saved.

 

Information exchange between processing steps of XDS
Files with the extension .pck are binary, compressed images.
xds step input files output files
XYCORR XDS.INP XYCORR.LP
    X-CORRECTIONS.pck
    Y-CORRECTIONS.pck
INIT XDS.INP INIT.LP
  X-CORRECTIONS.pck BKGINIT.pck
  Y-CORRECTIONS.pck BLANK.pck
    GAIN.pck
COLSPOT XDS.INP COLSPOT.LP
  X-CORRECTIONS.pck SPOT.XDS
  Y-CORRECTIONS.pck  
  BLANK.pck  
  BKGINIT.pck  
  GAIN.pck  
IDXREF XDS.INP IDXREF.LP
  SPOT.XDS SPOT.XDS
    XPARM.XDS
DEFPIX XDS.INP DEFPIX.LP
  X-CORRECTIONS.pck BKGPIX.pck
  Y-CORRECTIONS.pck ABS.pck
  BKGINIT.pck  
  XPARM.XDS  
XPLAN XDS.INP XPLAN.LP
  BKGPIX.pck  
  XPARM.XDS  
INTEGRATE XDS.INP INTEGRATE.LP
  X-CORRECTIONS.pck INTEGRATE.HKL
  Y-CORRECTIONS.pck FRAME.pck
  BLANK.pck  
  BKGPIX.pck  
  GAIN.pck  
  XPARM.XDS  
CORRECT XDS.INP CORRECT.LP
  INTEGRATE.HKL XDS_ASCII.HKL
  REMOVE.HKL GXPARM.XDS

 

XDS.INP

This file contains the input parameters you have to provide to run XDS.

Each parameter name consists of a string of characters without intervening blanks or exclamation marks and includes an equal sign as its last character. The parameter value follows on the same line. The parameter names cannot be abbreviated; they are case sensitive, too. The parameters may be given in arbitrary order. Characters in a line to the right of an exclamation mark are comment.

XDS_ASCII.HKL

The file XDS_ASCII.HKL contains the result of data processing by XDS, namely the corrected intensities of all reflections recorded in the data images.
Output files generated by xscale adopt a similar layout but are named as defined by the user.

The file consists of a header, reflection data records, and a line marking the end of the data. Each line is at most 132 characters in length. The data records consist of a fixed number of numerical items that are separated by at least one blank. Header lines and the terminator line are distinguished from the reflection data records by the presence of the exclamation mark symbol '!'.

  • Header
    The first header line defines the file format (always FORMAT=XDS_ASCII), states whether symmetry equivalent reflections have been merged or not (MERGE=FALSE or TRUE), and whether Friedel's law holds true or not (FRIEDEL'S_LAW=TRUE or FALSE). The file XDS_ASCII.HKL generated by the CORRECT-step of XDS has always MERGE=FALSE, whereas the ouput file generated by xscale often has symmetry equivalent reflections merged together (MERGE=TRUE).
    Subsequent header lines specify experimental parameters and other information whose meaning is obvious or refers to an input parameter value explained in the section Input parameters. The amount of information given in the header may vary and is subject to future development.
    However, the header always specifies the number of numerical items in each reflection data record, which is NUMBER_OF_ITEMS_IN_EACH_DATA_RECORD=11 for the file generated by CORRECT. The meaning of each numerical item is specified by the following keywords.
    • ITEM_H=1; the first number in a data record is the reflection index h.
    • ITEM_K=2; the second number in a data record is the reflection index k.
    • ITEM_L=3; the third number in a data record is the reflection index l.
    • ITEM_IOBS=4; the fourth number in a data record is the reflection intensity.
    • ITEM_SIGMA(IOBS)=5; the fifth number is the error of the intensity. A negative sign is attached to SIGMA(IOBS) to indicate a MISFIT (IOBS is incompatible with symmetry equivalent reflection intensities). At present, such MISFITs are ignored in the subsequent processing by xscale.
    • ITEM_XD=6; X-coordinate (pixels) of reflection on detector.
    • ITEM_YD=7; Y-coordinate (pixels) of reflection on detector.
    • ITEM_ZD=8; centroid of image numbers that recorded the Bragg peak.
    • ITEM_RLP=9; reciprocal LP-correction factor that has been applied to this reflection.
    • ITEM_PEAK=10; means that the tenth item contains the percentage of observed reflection intensity. A value less than 100.0 indicates that the reflection was either incompletely recorded or overlapping with neighbouring reflections or included untrusted pixels in the profile region.
    • ITEM_CORR=11 means that the eleventh item contains the percentage of correlation between observed and expected reflection profile.

    The last line of the header is identified by !END_OF_HEADER

  • Data records
    one line per reflection, with the meaning of the data items in each line being explained in the header. Each data record line consists of numerical items which are separated by at least one blank. A negative sign is attached to SIGMA(IOBS) to indicate a MISFIT.
  • Terminator record
    !END_OF_DATA

SPOT.XDS

The file contains a list of strong observed diffraction spots. The spot centroids are located by "COLSPOT" and saved as ASCII records x,y,z,Intensity using FORMAT(3F10.2,F10.0).

The spot positions x,y (pixels) in the detector plane are already corrected for spatial distortion. z is the centroid of image numbers that contribute to the spot. The file is read subsequently by "IDXREF" and indices are attached to each spot. Indices 0 0 0 are used to indicate a spot that could not be indexed. On return, the original file contents is replaced by records
x,y,z,Intensity,h,k,l using FORMAT(3F10.2,F10.0,3I8)
for each spot, and h,k,l are the reflection indices.

XPARM.XDS
GXPARM.XDS

Each file contains all diffraction parameters necessary for computing the locations of all reflections occuring in the data images.

An initial set of parameters is determined by "IDXREF" and saved on file XPARM.XDS. A final set of parameters is computed by "CORRECT" and saved on file GXPARM.XDS. Both files are of identical format, the meaning of the parameters is as described below. In case a better solution has been obtained from the refinements in the "CORRECT" step, one could replace XPARM.XDS by GXPARM.XDS and rerun "INTEGRATE" and "CORRECT". Usually this is not necessary, but this possibility may be useful in certain critical cases.

The file comprises 11 lines of data values that code for

  1. Starting image number (STARTING_FRAME=), spindle angle at start (STARTING_ANGLE=), oscillation range, and laboratory coordinates of the rotation axis. FORMAT(I6,5F12.6)
  2. Wavelength (Å) and laboratory coordinates of the incident beam wavevector. FORMAT(4F15.6)
  3. Number of pixels along the detector X-axis (NX=) and Y-axis (NY=) in a data image and pixel sizes (mm) (QX=, QY=) along X and Y. FORMAT(2I10,2F10.5)
  4. Signed distance between crystal and detector (mm), detector X-coordinate (pixels) of origin, detector Y-coordinate (pixels) of origin. FORMAT(3F15.6)
  5. Laboratory coordinates of the unit vector along the detector X-axis. FORMAT(3F15.6)
  6. Laboratory coordinates of the unit vector along the detector Y-axis. FORMAT(3F15.6)
  7. Laboratory coordinates of the unit vector along the detector normal. FORMAT(3F15.6)
  8. Space group number and unit cell parameters (Å and degrees). FORMAT(I10,6F10.3)
  9. Laboratory coordinates of the unit cell a-axis of the unrotated crystal. FORMAT(3F15.6)
  10. Laboratory coordinates of the unit cell b-axis of the unrotated crystal. FORMAT(3F15.6)
  11. Laboratory coordinates of the unit cell c-axis of the unrotated crystal. FORMAT(3F15.6)

INTEGRATE.HKL

This file contains the results from the INTEGRATE step. The file begins with a self-explaining header. Each header record starts with a '!'. The last header record is indicated by !END_OF_HEADER; the reflection records follow immediately. A terminator record, !END_OF_DATA, follows the last reflection record.

Each reflection record consists of 19 data items
h, k, l, IOBS, SIGMA, XCAL, YCAL, ZCAL, RLP, PEAK, CORR, MAXC, XOBS, YOBS, ZOBS, ALF0, BET0, ALF1, BET1
The items are separated by a blank and can be read in free-format.

  1. h: h-index of the reflection.
  2. k: k-index of the reflection.
  3. l: l-index of the reflection.
  4. IOBS: intensity of the reflection obtained by profile fitting. The intensity is already LP-corrected assuming an unpolarized incident beam. The final polarization correction is carried out in the CORRECT step.
  5. SIGMA: e.s.d. of IOBS as obtained from profile fitting.
  6. XCAL: calculated detector X-coordinate of the reflection.
  7. YCAL: calculated detector Y-coordinate of the reflection.
  8. ZCAL: calculated image number of reflection at diffraction maximum.
  9. RLP: Reciprocal Lorentz-Polarization factor computed for unpolarized incident beam.
  10. PEAK: Percentage of observed reflection intensity.
  11. CORR: Correlation factor between observed and expected reflection profile.
  12. MAXC: Largest image pixel value contributing to the reflection.
  13. XOBS: observed detector X-coordinate of the reflection. 0 if unobserved.
  14. YOBS: observed detector Y-coordinate of the reflection. 0 if unobserved.
  15. ZOBS: observed centroid of image numbers of reflection. 0 if unobserved.
  16. ALF0: incident beam direction described by polar coordinates (degrees) as sin(bet0)cos(alf0), sin(bet0)sin(alf0), cos(bet0).
  17. BET0: incident beam direction described by polar coordinate as sin(bet0)cos(alf0), sin(bet0)sin(alf0), cos(bet0).
  18. ALF1: diffracted beam direction described by polar coordinates as sin(bet1)cos(alf1), sin(bet1)sin(alf1), cos(bet1).
  19. BET1: diffracted beam direction described by polar coordinates as sin(bet1)cos(alf1), sin(bet1)sin(alf1), cos(bet1).

REMOVE.HKL

In the CORRECT step, XDS checks for the presence of a file named REMOVE.HKL in the current directory. A file of this name can be provided by the user to specify the indices of reflections that should be excluded from the final output file XDS_ASCII.HKL. Each reflection record of this file consists of the reflection indices h, k, l and possibly other information that will be ignored. Up to 10000 reflections can be specified.

Reflections that do not obey Wilson's statistic often arise from ice rings in the data images. These outliers are reported near the end of the file CORRECT.LP. To suppress the unwanted reflections from the final output file XDS_ASCII.HKL, the user copies them to a file named REMOVE.HKL in the current directory and repeats the CORRECT step.

X-CORRECTIONS.pck
Y-CORRECTIONS.pck

These two files contain look-up tables to correct the X and Y pixel positions on the detector for spatial distortions. The spatial corrections for a pixel at IX,IY (0<IX<=NX, 0<IY<=NY) are found in the tables at address IA4=IX4+NXBY4*(IY4-1) where IX4=1+(IX-2)/4, IY4=1+(IY-2)/4, and NXBY4= 1+(NX-2)/4, such that the corrected pixel-coordinates are
IX("CORRECTED")=IX+I2XCOR(IA4)/10
IY("CORRECTED")=IY+I2YCOR(IA4)/10.

BLANK.pck

BLANK.pck contains the dark current (non-Xray) background. The dark current for a pixel at IX,IY (0<IX<=NX, 0<IY<=NY) is found at address IA4=IX4+NXBY4*(IY4-1) in the table, where
IX4=1+(IX-2)/4, IY4=1+(IY-2)/4, and NXBY4= 1+(NX-2)/4.

GAIN.pck

GAIN.pck contains the ratio between variance and mean of the pixel contents in the neighbourhood of each image pixel. The table is used for classifying data image pixels into background or spot.

BKGINIT.pck
BKGPIX.pck

These files contain an image of the INTEGER*2 array IBKG(NX*NY) such that IBKG(IX+NX*(IY-1)) is the background value at pixel position IX,IY (0<IX<=NX,0<IY<=NY). NX,NY are the number of pixels along the detector X- and Y-axis. (IX is the fast index.) The pixel contents are given in XDS internal number representation:
If I16=IBKG(IX+NX*(IY-1)), the true value I32 is found by the code
I32=I16; IF (I32.LT.-4095)I32=-8*I32;
the value range -4095 ... -1 is used to mark the pixel. Untrusted pixels are marked by -3.

BKGINIT.pck is generated in the INIT step and serves as input of the DEFPIX step. DEFPIX recognizes shaded regions in the background table BKGINIT.pck and removes them from the set of trusted pixels.

BKGPIX.pck is the background table resulting from the DEFPIX step. It serves as starting background table for the INTEGRATE step.

ABS.pck

This file contains an image of the INTEGER*2 array I2ABS(NX*NY) such that I2ABS(IX+NX*(IY-1)) is the ratio between the background at IX, IY and the mean background for all pixels of the same resolution, multiplied by 10000. NX,NY are the number of pixels along the detector X- and Y-axis. (IX is the fast index.) This file is generated in the DEFPIX step of XDS and should be inspected by the user with the VIEW program. The image clearly shows shaded regions of the detector that should be removed from the trusted detector area. Pixels in the shaded region have a value below 10000, and in case the default setting was unsatisfactory, the user may change the input parameter VALUE_RANGE_FOR_TRUSTED_DETECTOR_PIXELS= and repeat the DEFPIX step. As a result from the DEFPIX step the initial pixel background table BKGPIX.pck will be obtained with untrusted pixels marked by -3.

Wolfgang Kabsch 
page last updated: December 6, 2002