XSCALE Input Parameters


All input parameters needed for scaling data sets (obtained from processing with xds) are collected in the file named XSCALE.INP which must reside in the current directory where XSCALE will be invoked. To simplify the task of preparing the input file, a file template (example) for XSCALE.INP is included in the xds package that can easily be edited according to the actual case.

This chapter explains the meaning of all parameters used by the XSCALE program. 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 value must follow the parameter name on the same line. The parameter names cannot be abbreviated; they are case sensitive, too. Characters in a line to the right of an exclamation mark are comment.

The parameters may be given in arbitrary order - except for the parameters defining input and output refelction files (INPUT_FILE=, OUTPUT_FILE=). Here, an output file is defined first by the parameter OUTPUT_FILE= that will include the scaled and merged reflections from all following input files specified by the parameters INPUT_FILE= until the next occurence of OUTPUT_FILE= in XSCALE.INP. Several output files can be specified (together with their set of input files) in a single run of XSCALE. All output files are then on the same scale - a program feature recommended for MAD data sets.

Input parameters of XSCALE

MAXIMUM_NUMBER_OF_PROCESSORS=

This parameter defines the maximum number of cpu's that can be employed by the parallel version of XSCALE. Up to 32 cpu's can be used. The default of 1 cpu will be assumed in the single processor version of XSCALE.

Example: MAXIMUM_NUMBER_OF_PROCESSORS= 16 

RESOLUTION_SHELLS=

Resolution shell limits (Å). Only the high resolution limit of each shell is given. Up to 20 resolution shells will be accepted. The shell limits must be specified in decreasing order. The resolution shells are used to report statistical properties of the data sets as a function of resolution. Note also that the last resolution shell defines the high resolution limit of the data that are included in the scaled output data set(s).

Example:
RESOLUTION_SHELLS=20.0 10.0 6.0 3.0
Completeness will be reported for the resolution shells infinity-20.0, 20-10, 10-6, and 6-3 Å. The scaled output file(s) will include no reflections beyond 3 Å, even if the input files contain reflections to a higher resolution.

SPACE_GROUP_NUMBER=

Space-group number of the crystal. The numbers corresponding to each possible space group are defined in the "INTERNATIONAL TABLES I". All 230 space groups are implemented. From the space group number and the unit cell parameters XSCALE provides a standard set of symmetry operators. In case a reindexing transformation is specified, the space group symmetry refers to the new cell.

Example: SPACE_GROUP_NUMBER=77
This specifies the tetragonal space group P42

UNIT_CELL_CONSTANTS=

Unit cell parameters a, b, c (Å) and alpha, beta, gamma (degrees). The cell constants must meet the requirements implicated by the space group. First and second setting of monoclinic crystals must be distinguishable by the cell constants. In case a reindexing transformation is specified, the unit cell parameters refer to the new cell.

Example:
UNIT_CELL_CONSTANTS=125.9 125.9 144.7 90.0 90.0 90.0
SPACE_GROUP_NUMBER=77
This specifies the cell constants of a tetragonal crystal obeying P42 space group symmetry. Note that the a and b axes must have identical length and all angles must be exactly 90 degrees as required by the space group.

REIDX=

This optional transformation provides a possibility for reindexing the reflections of all input data files (except for an optional reference data set, see below). The meaning of the 12 integer numbers that make up the parameter value is defined as:
 h' = REIDX(1)*h + REIDX( 2)*k + REIDX( 3)*l + REIDX( 4)
 k' = REIDX(5)*h + REIDX( 6)*k + REIDX( 7)*l + REIDX( 8)
 l' = REIDX(9)*h + REIDX(10)*k + REIDX(11)*l + REIDX(12)
where h', k', l' are the new indices.
In case this transformation is omitted it is assumed that reindexing is not required, that is h'=h, k'=k, l'=l. XSCALE issues a warning message if the reindexing transformation implies a change of hand (negative determinant). In this case the sign of anomalous intensity differences will flip.

Example
REIDX= 0 -1 0 0  -1 0 0 0   0 0 -1 0
SPACE_GROUP_NUMBER=77
UNIT_CELL_CONSTANTS=125.9 125.9 144.7 90.0 90.0 90.0

The new reflection indices are related to the old h, k, l by the transformation h'=-k, k'=-h, l'=-l. Space group and cell constants refer to the new cell. Note, that the cell constants have to be "clean"; that means they have to satisfy the constraints of the symmetry group.

REFERENCE_DATA_SET=

File name of an optional reference data set and its type. Type can be XDS_ASCII or the old formats DIRECT ANOMAL NORMAL OLDHKL UNIQUE. If a reference data set is not specified explicitly, XSCALE will generate one from all input data sets. This reference data set is put to an approximate absolute scale (assuming a protein with 50% solvent fraction). The reference data set is used for:

  • definition of an overall scale and fall-off with respect to resolution that is imposed on the scaled output files obtained from the given input data sets;
  • comparison with all other input data sets. This comparison may be useful for the detection of inconsistent indexing of some of the input data sets. Note, that an explicitly specified reference data set is never reindexed (REIDX=).

Example:
REFERENCE_DATA_SET= ../XDS_ASCII_native.HKL XDS_ASCII
This specifies a native data set of type XDS_ASCII serving as a reference. Note, that the reflection indices of the reference data set are not affected by a reindexing of the input reflection files.

OUTPUT_FILE=
FRIEDEL'S_LAW=
MERGE=
STRICT_ABSORPTION_CORRECTION=

The value of the parameter OUTPUT_FILE= is the name of an output file to be generated by XSCALE. The file name is restricted to at most 50 characters with no intervening blanks or exclamation marks. The reflections included in the scaled output data set are taken from files whose names are specified by subsequent parameters INPUT_FILE= up to the next occurence of OUTPUT_FILE=.

The file name must be followed by the parameter FRIEDEL'S_LAW= whose value (either TRUE or FALSE) specifies whether Friedel's law holds true or not.

Symmetry related reflections will be merged by default - unless the parameter MERGE=FALSE has been specified. In case Friedel's law holds true, reflections h, k, l and -h,-k,-l are considered to be symmetry related.

The parameter STRICT_ABSORPTION_CORRECTION= controls the calculation of the absorption correction factors. The parameter value can be TRUE (default) or FALSE. If STRICT_ABSORPTION_CORRECTION=FALSE, Friedel-pairs are treated as symmetry-equivalent reflections in the calculation of the absorption correction factors. In the presence of anomalous scattering effects this could lead to an underestimate of the anomalous differences.
If STRICT_ABSORPTION_CORRECTION= TRUE and FRIEDEL'S_LAW=FALSE, Friedel-pairs are treated as different reflections in the calculation of the absorption correction factors, otherwise not.

Format of the output file is always XDS_ASCII. However, the number of data items in each reflection record and their meaning depend on whether Friedel's law holds true or not and whether symmetry related reflections are merged or not.

Standard items
ITEM_H=1; reflection index h.
ITEM_K=2; reflection index k.
ITEM_L=3; reflection index l.
ITEM_IOBS=4; intensity of the reflection.
ITEM_SIGMA(IOBS)=5; standard deviation of intensity.
FRIEDEL'S_LAW=TRUE MERGE=TRUE
Each reflection record contains the 5 standard items.
FRIEDEL'S_LAW=FALSE MERGE=TRUE
In addition to the 5 standard items, each reflection record contains
ITEM_IOBS'=6; intensity derived from Bijvoet pairs and
ITEM_SIGMA(IOBS')=7; standard deviation of intensity.
A Bijvoet reflection pair in the same data set is accepted only if the difference in their image numbers is less than the value of the input parameter DELFRM=. The idea is that radiation damage increases with the elapsed time between recording a Bijvoet pair which could obscure the weak anomalous signal. The drawback of this approach is that many measurements are ignored depending on the value of DELFRM=. This will lower the redundancy of the measurements and may even lead to incomplete data sets. For these reasons, ITEM_IOBS' and ITEM_SIGMA(IOBS') are not used in the further structure analysis.
MERGE=FALSE
In addition to the 5 standard items, each reflection record contains
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_ISET=9; identifying number of the input data set the reflection came from.

Example:
OUTPUT_FILE=myo.ahkl FRIEDEL'S_LAW=FALSE MERGE=TRUE
STRICT_ABSORPTION_CORRECTION=TRUE
The parameters state that the scaled output data set will be given the name myo.ahkl, anomalous intensity differences are expected to be present in the data, and symmetry related reflections should be merged. In the calculation of the absorption correction factors Friedel-pairs are treated as different reflections.

INPUT_FILE=

File name of the xds input file, its format, and a resolution window for accepting reflections. Up to a total of 50 input files are allowed.

File name
is restricted to at most 50 characters with no intervening blanks or exclamation marks. The file name may be preceeded by a '*' to indicate that all other data sets are put to the same fall-off with respect to resolution as the marked one. If none of the input data sets is marked, the very first one is marked by default. If an external reference data set has been specified by REFERENCE_DATA_SET=, the '*' in front of a file name will be ignored.
File format
must be specified by one of the keywords:
XDS_ASCII
this is the only reflection file format now being generated and used within the xds-package. All other formats listed below are outdated since August 2000. They are still accepted by XSCALE.
DIRECT
this outdated format refers to files XDS.HKL described in the manual xds.man included in the old xds package.
ANOMAL
the outdated format refers to files ANOMAL.HKL that were used by the old versions of the xds-package for representing anomalous scattering intensity data. This format is described in the old manual xds.man.
NORMAL, OLDHKL
these outdated formats refers to files NORMAL.HKL that were used by the old versions of the xds-package for representing unique intensities in the absence of anomalous scattering effects. OLDHKL and NORMAL are identical formats that are described in the old manual xds.man.
UNIQUE
the outdated format refers to files UNIQUE.HKL that were used by the old versions of the xds-package before November 1998. This format is described in the old manual xds.man.
Resolution window
for accepting reflections from this file consists of: low resolution limit, high resolution limit (Å)
WEIGHT=
Weight for this data set. The standard deviation of each reflection intensity will be multiplied by the parameter value. The parameter is optional, and WEIGHT=1.0 is assumed by default.
DELFRM=
This optional parameter controls the acceptance of Friedel-pairs. If the Friedel-pair of reflections were recorded on images whose running numbers differ by less than the parameter value, the reflections will be used for estimating anomalous intensity differences. If the parameter is omitted, XSCALE will not impose such an acceptance condition.
NBATCH=
Number of batches (optional). This parameter controls the number of correction factors applied to the input reflection data set. Typically, the parameter value is chosen as the total rotation range covered by the input data set divided by 2.5...5 degrees, but should not exceed a value of 36 to avoid overfitting. If the parameter is left unspecified by the user, XSCALE will determine a reasonable value. The parameter is meaningful only for input data sets of type XDS_ASCII (or DIRECT).
CRYSTAL_NAME=
This optional parameter specifies the name of the crystal from which the input data set was collected. The crystal name is restricted to at most 50 characters with no intervening blanks or exclamation marks.
Specification of this parameter implicates 0-dose extrapolation of individual reflection intensities to compensate for the effects of radiation damage (see Diederichs, McSweeney & Ravelli, 2003). Correction factors exp{b(h)*dose(h,i)} are applied to the intensity I(h,i), where h,i denotes the i-th observation with unique reflection indices h and dose(h,i) the X-ray dose (arbitrary units) accumulated by the crystal when the reflection was recorded. The decay-factor b(h) is determined from the assumption that symmetry-related reflections and their Friedel mates from the same crystal have the same decay-factor, independent of the wavelength of the incident X-ray beam.
STARTING_DOSE=
DOSE_RATE=
These two optional parameters are used to calculate the accumulated X-ray dose (arbitrary units) of the crystal at the time the j-th image in the data set was recorded, dose = starting_dose + dose_rate * (j-1). The parameters can be fixed by putting a '*' right after the parameter value; otherwise they are refined by XSCALE. Default is to omit the two parameters entirely and leave it to XSCALE to find the best values. Note, that this simple method for calculating the dose assumes a constant X-ray dose for each image in the data set.

Example
INPUT_FILE=*../XDS_ASCII.HKL XDS_ASCII 50 1.2 WEIGHT=1.0 DELFRM=500 NBATCH=36
This specifies an input file, named ../XDS_ASCII.HKL. As the name is preceeded by a '*', the file also serves as a reference to other input files which will inherit the intensity fall-off as a function of resolution. The input file is of type XDS_ASCII and the subset of reflections within the resolution range 50 ... 1.2 Å should be included in the scaled output data set. A weighting factor of one is applied to the standard deviation of each reflection intensity, which is the default and could have been omitted. The value of 500 for limiting inclusion of Friedel pairs is rather permissive. NBATCH=36 allocates the maximum number of correction factors allowed for a single input data set. As the input file contains many reflections, there is no risk of overfitting the data.

0-DOSE_SIGNIFICANCE_LEVEL=

This parameter (default value 0.1) defines the maximum probability the user is willing to risk that a 0-dose extrapolation is carried out when this correction should not have been done. A smaller value would reduce this risk on the expense that an increasing number of reflections are not corrected then - even when this should have been done.

 

Wolfgang Kabsch 
page last updated: November 27, 2003