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.

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 Angstrom

NAME_TEMPLATE_OF_DATA_FRAMES - path and name of frames, with wildcards for numbers

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

If you know the space group and unit cell parameters of your crystal in advance you just need these two keywords:

SPACE_GROUP_NUMBER: a mapping of space group names against their numbers is near the end of IDXREF.LP.

UNIT_CELL_PARAMETERS: 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 crystal 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 which detector pixels will be used

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.
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 ice rings. Whether ice rings are a problem should be obvious by looking at frames, FRAME.pck and the "alien" statistics at the end of CORRECT.LP. Please note that there are five more "high-resolution" ice ring resolution ranges (given at the end of CORRECT.LP), in addition to the five ranges already supplied in templates of XDS.INP.

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

Keywords which affect whether indexing will succeed

In addition to Obtaining ORGX ORGY, I recommend to look at:

STRONG_PIXEL - the default is 3, but 6 is usually more appropriate.

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), don't set both MAXIMUM_NUMBER_OF_PROCESSORS and MAXIMUM_NUMBER_OF_JOBS to values >1!

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!

Written by --Kay 14:44, 8 November 2007 (CET)