XDS.INP
XDS.INP is a user-provided file that is read by XDS. Each line consists of one or more <keyword>=<parameter(s)> pairs. Anything after a "!" is a comment.
Complete documentation is at http://www.mpimf-heidelberg.mpg.de/~kabsch/xds/html_doc/xds_parameters.html .
Templates for various detectors are at http://www.mpimf-heidelberg.mpg.de/~kabsch/xds/html_doc/xds_prepare.html .
Required keywords
These keywords have no default parameters and must be given with the correct values.
The values may be obtained from logfiles of the beamline software, your notes, or (for many types of frames) from the headers of the frames (using 'strings <filename>|more'). A good way to retrieve them is by using MOSFLM.
A minimal XDS.INP needs at least these keywords and their parameters:
- Keywords that describe the detector:
DETECTOR NX NY QX QY - for a list of supported detectors and possible geometries, see Table of supported detectors
DIRECTION_OF_DETECTOR_X-AXIS - often 1 0 0
DIRECTION_OF_DETECTOR_Y-AXIS - often 0 1 0
INCIDENT_BEAM_DIRECTION - often 0 0 1
ROTATION_AXIS - often 1 0 0 at a synchrotron
- Keywords that describe your particular dataset:
ORGX ORGY - in pixels The most critical parameters for a successful data reduction . See Obtaining ORGX ORGY
DETECTOR_DISTANCE - in millimeters
OSCILLATION_RANGE - in degrees
X-RAY_WAVELENGTH - in Ångström
NAME_TEMPLATE_OF_DATA_FRAMES - path and name of frames, with wildcards for numbers, plus type of frames (e.g. "CBF")
DATA_RANGE - numbers of frames to be reduced
BACKGROUND_RANGE - numbers of frames to be used for initial background estimation, "1 5" is usually enough, and "1 20" should be ample.
Keywords that additionally describe your experiment
FRACTION_OF_POLARIZATION and POLARIZATION_PLANE_NORMAL should be specified for detectors at synchrotron sites. If they are not specified (or inaccurate), their effect will to some extent be absorbed by the scale factors determined in CORRECT.
Keywords for space group assignment
A dataset can be reduced by XDS in space group P1. If you know the space group and unit cell parameters of your crystal in advance you just need these two keywords:
- SPACE_GROUP_NUMBER
- If you don't know the space group, put a 0 or comment out the line. The space group will then be automatically determined in the CORRECT step. A mapping of space group names against their numbers is near the end of IDXREF.LP.
- UNIT_CELL_PARAMETERS
- If you don't know the space group, put six 0s or comment out the line. Unit cell parameters need to respect the constraints of the Laue group, e.g. all angles must be exactly 90.0 for orthorhombic and tetragonal space groups, a and b must be equal for trigonal and tetragonal, and so on.
If you want to assign a space group and unit cell parameters to a dataset that was reduced in P1, you most probably need this keyword as well:
- REINDEX
- 12 numbers, 9 of which are used as a re-indexing matrix (the other 3 are normally 0). These 12 numbers can be obtained from IDXREF.LP.
The way how to determine a space group (and unit cell parameters) is described in space group determination.
Keywords which affect completeness and resolution limits
- TRUSTED_REGION
- The default is "0.00 1.05" but if you have a square detector, and their are reflections visible in the corners, you may go as high as "0. 1.4142". Depending on the symmetry of your crystal, this may give you useful high-resolution data. If you change the values, you'll have to re-run INIT and DEFPIX to make INTEGRATE use the changed region.
- VALUE_RANGE_FOR_TRUSTED_DETECTOR_PIXELS
- the default is "7000. 30000." but the first number is probably on the low side. See Determining_VALUE_RANGE_FOR_TRUSTED_DETECTOR_PIXELS.
- MINIMUM_ZETA
- the default of 0.15 is rather on the safe side. A lower value increases completeness. See MINIMUM_ZETA.
- INCLUDE_RESOLUTION_RANGE
- the default is "20.0 0.0" but it would be good to change this to sensible values for your data set, e.g. 50.0 for the lower resolution limit and the limiting resolution, where the average signal-to-noise ratio drops below 1, for the upper limit (the latter number could be obtained from CORRECT.LP).
- EXCLUDE_RESOLUTION_RANGE
- to exclude reflections in ice rings (CORRECT step). Whether ice rings are a problem should be obvious by looking at individual frames (often later frames are affected more than earlier ones), FRAME.pck and the "alien" statistics at the end of CORRECT.LP. Also see Wishlist, and VIEW misfits.pck (produced by XDSSTAT).
Keywords which affect aspects of geometry parameter refinement
- REFINE(IDXREF)
- The defaults (REFINE(IDXREF)=DISTANCE BEAM ORIENTATION CELL AXIS i.e. refine everything) are OK, but only if COLSPOT has seen all (or rather, a significant fraction of the) frames (see SPOT_RANGE below). If only a small SPOT_RANGE was used (which is not the best way, but possible), one should use REFINE(IDXREF)= AXIS BEAM ORIENTATION CELL . (The next thing to omit would be AXIS)
- REFINE(INTEGRATE)
- The defaults (REFINE(INTEGRATE)=DISTANCE BEAM ORIENTATION CELL) could be modified by omitting DISTANCE, because one should assume that the distance is constant. This is particularly recommended if SPACE_GROUP_NUMBER=0 or 1. Furthermore, by fixing the distance one can better see from the results of the refinement whether the cell parameters are stable, or whether they change due to radiation damage. There are situations when one wants to reduce the number of parameters to be refined even more, see Optimization.
- REFINE(CORRECT)
- The defaults (REFINE(CORRECT)=DISTANCE BEAM ORIENTATION CELL AXIS i.e. refine everything) are OK. For low resolution datasets the distance refinement may not be stable (i.e. refined distance differs more than a few mm from expected distance). In this case one should remove DISTANCE from the list.
Keywords which affect whether indexing will succeed
Again, the most important parameters are ORGX ORGY. Often the software which writes the frames puts these numbers into the headers of the frames. However, these numbers are sometimes wrong, and furthermore, XDS does not read and interpret headers of frames. How to obtain estimates for ORGY ORGY from frames is described in Obtaining ORGX ORGY.
- SPOT_RANGE
- If this line is omitted (and MINUTE=0), the whole DATA_RANGE is used. This is usually a good way to proceed. If there is radiation damage, I would advise to use the first half of the DATA_RANGE as SPOT_RANGE. The SPOT_RANGE in principle may comprise a single frame.
Attention: if MINUTE= has a parameter >0, a small SPOT_RANGE will be used if SPOT_RANGE is not explicitly provided! - STRONG_PIXEL
- the default is 3, but 6 is usually more appropriate.
See also the article Ice_rings.
Keywords which affect the speed of data reduction
- MAXIMUM_NUMBER_OF_PROCESSORS
- speeds up XDS by use of several (e.g. 2-4) CPUs within a single machine.
- MAXIMUM_NUMBER_OF_JOBS
- speeds up XDS by chopping the DATA_RANGE into pieces, and feeding each piece to a new process. That process may run on the local machine, or a different one (but this needs to be configured by the system administrator). Unless specifically set up for a given computer environment (e.g., at a synchrotron site), usually don't set both MAXIMUM_NUMBER_OF_PROCESSORS and MAXIMUM_NUMBER_OF_JOBS to values >1 !
Some amount of "overcommiting of resources" is OK, i.e. if you are the sole user of a Dual-core workstation, you may set both parameters to 2. Wolfgang Kabsch found that this utilizes the machine even a bit better than either MAXIMUM_NUMBER_OF_PROCESSORS=2 or MAXIMUM_NUMBER_OF_JOBS=2.
How to tweak data quality
See Optimization#Final_polishing.
What can go wrong with this file?
The most important possible pitfalls are:
- Lines longer than 80 characters are not allowed. This happens most often with the NAME_TEMPLATE_OF_DATA_FRAMES keyword line, because the path to the directory with the frames may be long. Fix: use a symlink to the directory with the frames.
- Error due to omitting the "=" directly after the keyword (i.e. having an intervening blank).
- There may be decoding errors in the parameter which may lead to obscure error messages. E.g., see what happens if you provide only one cell parameter instead of six!
Example XDS.INP files for ADSC, MarCCD and Pilatus detectors
ADSC Quantum Q315r @ ESRF ID23-1
JOB=XYCORR INIT COLSPOT IDXREF DEFPIX INTEGRATE CORRECT ! for this experiment: ORGX= 1541 ORGY= 1550 DETECTOR_DISTANCE=350 OSCILLATION_RANGE=0.25 X-RAY_WAVELENGTH=1.0001 NAME_TEMPLATE_OF_DATA_FRAMES=../mk/mk04_1_???.img DATA_RANGE=1 720 SPOT_RANGE=1 720 BACKGROUND_RANGE=1 10 SPACE_GROUP_NUMBER=0 UNIT_CELL_CONSTANTS= 70 80 90 90 90 90 ! remove the exclamation marks if anom signal is present ! FRIEDEL'S_LAW=FALSE ! STRICT_ABSORPTION_CORRECTION=TRUE ! but read Tips_and_Tricks in XDSwiki ! parameters with changes wrt default values: TRUSTED_REGION=0.00 1.35 VALUE_RANGE_FOR_TRUSTED_DETECTOR_PIXELS=8000. 30000. MINIMUM_ZETA=0.05 INCLUDE_RESOLUTION_RANGE=50 0 STRONG_PIXEL=6 REFINE(INTEGRATE)=CELL BEAM ORIENTATION MAXIMUM_NUMBER_OF_PROCESSORS=4 ! parameters specifically for this detector and beamline: DETECTOR= ADSC MINIMUM_VALID_PIXEL_VALUE= 1 OVERLOAD= 65000 NX= 3072 NY= 3072 QX= 0.10260 QY= 0.10260 DIRECTION_OF_DETECTOR_X-AXIS=1 0 0 DIRECTION_OF_DETECTOR_Y-AXIS=0 1 0 INCIDENT_BEAM_DIRECTION=0 0 1 ROTATION_AXIS=1 0 0 FRACTION_OF_POLARIZATION=0.98 POLARIZATION_PLANE_NORMAL=0 1 0
MarCDD 225mm @ SLS, BL X06SA
JOB=XYCORR INIT COLSPOT IDXREF DEFPIX INTEGRATE CORRECT ! for this experiment: ORGX=1533 ORGY=1536 DETECTOR_DISTANCE=350 OSCILLATION_RANGE=0.25 X-RAY_WAVELENGTH=1.0001 NAME_TEMPLATE_OF_DATA_FRAMES=../mk/mk04_1_???.img DIRECT TIFF DATA_RANGE=1 720 SPOT_RANGE=1 720 BACKGROUND_RANGE=1 10 SPACE_GROUP_NUMBER=0 UNIT_CELL_CONSTANTS= 70 80 90 90 90 90 ! remove the exclamation marks if anom signal is present ! FRIEDEL'S_LAW=FALSE ! STRICT_ABSORPTION_CORRECTION=TRUE ! but read Tips_and_Tricks in XDSwiki ! parameters with changes wrt default values: TRUSTED_REGION=0.00 1.35 VALUE_RANGE_FOR_TRUSTED_DETECTOR_PIXELS=8000. 30000. MINIMUM_ZETA=0.05 INCLUDE_RESOLUTION_RANGE=50 0 STRONG_PIXEL=6 REFINE(INTEGRATE)=CELL BEAM ORIENTATION MAXIMUM_NUMBER_OF_PROCESSORS=4 ! parameters specifically for this detector and beamline: NX=3072 NY=3072 QX=0.073242 QY=0.073242 !MARCCD 225mm version !NX=2048 NY=2048 QX=0.079092 QY=0.079092 !MARCCD 165mm version !NX=4096 NY=4096 QX=0.079346 QY=0.079346 !MARCCD 325mm version !NX=4096 NY=4096 QX=0.073242 QY=0.073242 !MARCCD 300mm at APS (22-ID) DETECTOR=CCDCHESS MINIMUM_VALID_PIXEL_VALUE=0 OVERLOAD=65000 DIRECTION_OF_DETECTOR_X-AXIS=1 0 0 DIRECTION_OF_DETECTOR_Y-AXIS=0 1 0 INCIDENT_BEAM_DIRECTION=0 0 1 ROTATION_AXIS=1 0 0 FRACTION_OF_POLARIZATION=0.99 POLARIZATION_PLANE_NORMAL=0 1 0
Pilatus 6M @ SLS, BL X06SA
JOB=XYCORR INIT COLSPOT IDXREF DEFPIX INTEGRATE CORRECT ! for this experiment: ORGX=1330 ORGY=1321 DETECTOR_DISTANCE=550 OSCILLATION_RANGE=0.25 X-RAY_WAVELENGTH=1.0001 NAME_TEMPLATE_OF_DATA_FRAMES=../mk/mk04_1_0????.cbf CBF DATA_RANGE=1 720 SPOT_RANGE=1 720 BACKGROUND_RANGE=1 10 SPACE_GROUP_NUMBER=0 UNIT_CELL_CONSTANTS= 70 80 90 90 90 90 ! remove the exclamation marks if anom signal is present ! FRIEDEL'S_LAW=FALSE ! STRICT_ABSORPTION_CORRECTION=TRUE ! but read Tips_and_Tricks in XDSwiki ! parameters with changes wrt default values: TRUSTED_REGION=0.00 1.15 VALUE_RANGE_FOR_TRUSTED_DETECTOR_PIXELS=8000. 30000. MINIMUM_ZETA=0.05 INCLUDE_RESOLUTION_RANGE=50 0 STRONG_PIXEL=6 REFINE(INTEGRATE)=CELL BEAM ORIENTATION MAXIMUM_NUMBER_OF_PROCESSORS=4 ! parameters specifically for this detector and beamline: ! X-GEO_CORR=/some/directory/GD_6M_X06SA_SLS_27022007_X.pck ! as of April 2009, these files ! Y-GEO_CORR=/some/directory/GD_6M_X06SA_SLS_27022007_Y.pck ! should no longer be used, I heard DETECTOR=PILATUS NX=2463 NY=2527 QX=0.172 QY=0.172 !PILATUS 6M DIRECTION_OF_DETECTOR_X-AXIS=1 0 0 DIRECTION_OF_DETECTOR_Y-AXIS=0 1 0 INCIDENT_BEAM_DIRECTION=0 0 1 ROTATION_AXIS=1 0 0 FRACTION_OF_POLARIZATION=0.99 POLARIZATION_PLANE_NORMAL=0 1 0 SENSOR_THICKNESS=0.32 UNTRUSTED_RECTANGLE= 487 495 1 2527 UNTRUSTED_RECTANGLE= 981 989 1 2527 UNTRUSTED_RECTANGLE=1475 1483 1 2527 UNTRUSTED_RECTANGLE=1969 1977 1 2527 UNTRUSTED_RECTANGLE= 1 2463 195 213 UNTRUSTED_RECTANGLE= 1 2463 407 425 UNTRUSTED_RECTANGLE= 1 2463 619 637 UNTRUSTED_RECTANGLE= 1 2463 831 849 UNTRUSTED_RECTANGLE= 1 2463 1043 1061 UNTRUSTED_RECTANGLE= 1 2463 1255 1273 UNTRUSTED_RECTANGLE= 1 2463 1467 1485 UNTRUSTED_RECTANGLE= 1 2463 1679 1697 UNTRUSTED_RECTANGLE= 1 2463 1891 1909 UNTRUSTED_RECTANGLE= 1 2463 2103 2121 UNTRUSTED_RECTANGLE= 1 2463 2315 2333 NUMBER_OF_PROFILE_GRID_POINTS_ALONG_ALPHA/BETA=13 !used by: INTEGRATE ! NUMBER_OF_PROFILE_GRID_POINTS_ALONG_GAMMA= 9 !used by: INTEGRATE