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 for XSCALE.INP is included in the xds package that can easily be edited according to the actual case.

Each input parameter consists of a name and a value. The parameter name is always a string of characters without intervening blanks or exclamation marks and includes an equal sign as its last character. The parameter value must follow the parameter name on the same line. The parameter names cannot be abbreviated; they are case sensitive, too. More than one input parameter may be specified in the same line in XSCALE.INP except for parameters denoting file names or defining resolution shells (INPUT_FILE=, OUTPUT_FILE=, REFERENCE_DATA_SET=, and RESOLUTION_SHELLS=). Characters in a line to the right of an exclamation mark are comment.

The input parameters may be given in arbitrary order - except for the parameters defining input and output reflection 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.

This chapter explains all parameters used by the XSCALE program. These parameters are named


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 value is set to 4 cpu's. The parameter is ignored in the single processor version of XSCALE.

Example: MAXIMUM_NUMBER_OF_PROCESSORS= 16 


RESOLUTION_SHELLS=

This optional parameter is used for explicit definition of resolution shells for reporting statistical properties of the reflection data sets. Typically, this feature of XSCALE is used in a publication for reporting the quality of diffraction data in the Materials and Methods section. Only the high resolution limit (Å) of each shell is given. Up to 20 resolution shells can be specified and must be given in decreasing order. Also, no other parameter may occur on the same line in XSCALE.INP. Note that the last resolution shell defines the high resolution limit of the data that are included in the scaled output data set(s).
If this parameter is omitted, XSCALE determines reasonable resolution shells based on the input reflection files.

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


SPACE_GROUP_NUMBER=

Space-group number of the crystal (optional). The numbers corresponding to each of the 230 possible space groups are defined in the "INTERNATIONAL TABLES I ". In case a reindexing transformation is specified (REIDX=), the space-group number refers to the new cell. If no reindexing is requested, specification of the space-group number can be omitted. XSCALE will then use space-group number and cell constants (UNIT_CELL_CONSTANTS=) as provided in the header of the first input reflection file.

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


UNIT_CELL_CONSTANTS=

Unit cell parameters a, b, c (Å) and α, β, γ (°). 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 (REIDX=), the unit cell parameters refer to the new cell. If no reindexing is requested, specification of space-group number and cell constants can be omitted - in this case XSCALE will use space-group number and cell constants as provided in the header of the first input reflection file.

Example:
UNIT_CELL_CONSTANTS=14.8 7.8 14.3 90.0 112.7 90.0
SPACE_GROUP_NUMBER=9
This specifies the cell constants of a small molecule crystal belonging to monoclinic space group Cc. The second setting is used as recognized by angles α and γ being exactly 90°.


REIDX=

This optional parameter provides a possibility for reindexing the reflections of all input data files. 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 will issue a warning message if the reindexing transformation implies a change of hand (negative determinant) because this will flip the sign of anomalous intensity differences. If a reindexing transformation is specified the user must also provide explicit values for SPACE_GROUP_NUMBER= and UNIT_CELL_CONSTANTS=.

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"; this means that the a and b axes must have identical length and all angles must be exactly 90° as required by the space group symmetry.


REFERENCE_DATA_SET=

File name of an optional reference data set and its format. Note that no other parameter may occur on the same line in XSCALE.INP. File format can be XDS_ASCII (default) or the old formats DIRECT ANOMAL NORMAL OLDHKL UNIQUE. In contrast to the regular input data sets, reflections of the reference data set are not reindexed (REIDX=). The reference data set is used for:

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


MINIMUM_I/SIGMA=

This optional parameter defines sufficiently strong reflections that could be used for the determination of correction factors.

Example:
MINIMUM_I/SIGMA=3.0
Default value is 3.0. A larger value would reduce the number of useful reflections and lead to fewer correction factors that could be determined.


REFLECTIONS/CORRECTION_FACTOR=

Defines the minimum number of reflections needed for the determination of each correction factor applied to the reflection intensities. The choice of a value for this parameter is strongly influenced by the crystal symmetry and the quality of its diffraction pattern. These crystal properties - together with the total rotation of the crystal during data collecting - define the number of reflection that can be used for the determination of the correction factors. Proper choice of a value for the parameter REFLECTIONS/CORRECTION_FACTOR= is a compromise between two considerations: A large value for this parameter leads to a small number of correction factors with low statistical errors; on the other hand, a small number of correction factors cannot model abrupt changes in the correction surface. The default value chosen by XSCALE is to use approximately 50 reflections for the determination of each correction factor.

Example:
REFLECTIONS/CORRECTION_FACTOR=100
If your crystal has high symmetry and is well diffracting you may want to use at least 100 reflections for each correction factor to reduce the statistical error of the correction.


OUTPUT_FILE=

The value of the parameter 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. Also, no other parameter may occur on the same line in XSCALE.INP. 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= or end of file XSCALE.INP. Unless explicitly defined by the parameters MERGE= and FRIEDEL'S_LAW=, reflections on the output file will be unmerged and Friedel pairs considered different if this holds for all of the input data sets being scaled.

Format of the output file is always XDS_ASCII. However, the number of data items in each reflection record can vary depending on whether symmetry related reflections are merged and whether 0-dose corrections have been carried out or not.

MERGE=TRUE
Each reflection record contains the 5 standard items.
ITEM_H=1; first data item is reflection index h.
ITEM_K=2; second data item is reflection index k.
ITEM_L=3; third data item is reflection index l.
ITEM_IOBS=4; fourth data item is intensity of the reflection.
ITEM_SIGMA(IOBS)=5; fifth data item is standard deviation of intensity.
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_PSI=9; Schwarzenbach and Flack's psi-angle (°) which completely specifies diffraction geometry with respect to the crystal axes.
ITEM_ISET=10; identifying number of the input data set the reflection came from.
ITEM_DCY=11; decay-factor b(h) for this reflection used for 0-dose correction (this item will only be present if a value has been specified for CRYSTAL_NAME=).

Example:
OUTPUT_FILE=fae-ip.ahkl
INPUT_FILE= ../fae-ip/xds_1/XDS_ASCII.HKL
INPUT_FILE= ../fae-ip/xds_2/XDS_ASCII.HKL
OUTPUT_FILE=fae-pk.ahkl
INPUT_FILE= ../fae-pk/xds_1/XDS_ASCII.HKL
INPUT_FILE= ../fae-pk/xds_2/XDS_ASCII.HKL
OUTPUT_FILE=fae-rm.ahkl
INPUT_FILE=*../fae-rm/xds_1/XDS_ASCII.HKL
INPUT_FILE= ../fae-rm/xds_2/XDS_ASCII.HKL
This example shows the minimum necessary information for scaling data sets collected in a three-wavelength anomalous scattering experiment, with two input data sets at each wavelength. Reflections on the 3 output files will be unmerged and Friedel pairs considered different if this holds for all of the input data sets.


FRIEDEL'S_LAW=

This optional parameter can be either TRUE or FALSE. If Friedel's law holds true, reflections h, k, l and -h,-k,-l are considered to be symmetry related. The parameter refers to all reflections that will be scaled to the most recently specified output file. If this parameter is omitted, Friedel pairs are considered different reflections on the output file only if they are considered different on all input files (as stated in their file headers).


MERGE=

This optional parameter can be either TRUE or FALSE specifying whether symmetry related reflections will be merged in the scaled output data set or not. The parameter applies to all reflections that will be scaled to the most recently specified output file. If this parameter is omitted, reflections on the output file will be unmerged only if all of the input data sets are unmerged (as stated in their file headers).


STRICT_ABSORPTION_CORRECTION=

This parameter controls the calculation of the absorption correction factors and refers to all reflections that will be scaled to the most recently specified output file. The parameter value can be TRUE or FALSE (default). 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.

Example:
OUTPUT_FILE=myo.ahkl
FRIEDEL'S_LAW=FALSE
MERGE=TRUE
STRICT_ABSORPTION_CORRECTION=FALSE
INPUT_FILE=*../myo/xds_1/XDS_ASCII.HKL
INPUT_FILE= ../myo/xds_2/XDS_ASCII.HKL
Two input files are to be scaled to an output data set named myo.ahkl. Symmetry related reflections will be merged in the output file keeping Friedel pairs separate as anomalous intensity differences are expected to be present in the data. Only in the calculation of the absorption correction factors Friedel pairs are considered symmetry-equivalent which prevents overestimating the anomalous intensity differences.


INPUT_FILE=

The value of the parameter is the name of an input file and its format. No other parameter may occur on the same line in XSCALE.INP. The file will be scaled and included in the most recently defined output file. The parameter INPUT_FILE= can be repeated as often as needed to specify all input files that should be included in the same output file. There is no limit on the total number of input files or the number of reflections.

File name
is restricted to at most 120 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
if specified it must be one of the keywords:
XDS_ASCII
this is the default used within the xds-package and assumed here if no file format is specified. 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.

INCLUDE_RESOLUTION_RANGE=

This parameter value consists of two numbers, a low resolution limit (Å) and a high resolution limit (Å). A reflection h, k, l from the most recently defined input file is accepted only if its resolution d(h,k,l)=λ/{2sinθ} is within the specified range. If omitted all reflections are accepted.

Example:
OUTPUT_FILE=myo.ahkl
INPUT_FILE= ../myo/xds_1/XDS_ASCII.HKL
INCLUDE_RESOLUTION_RANGE= 20.0 3.5
INPUT_FILE=*../myo/xds_2/XDS_ASCII.HKL
INCLUDE_RESOLUTION_RANGE= 10.0 2.0
The output file, myo.ahkl, is obtained from scaling two input data sets, the second one serving as a reference as indicated by the '*' preceding its file name. Reflections with a resolution between the low resolution limit (20 Å) and the high resolution limit (3.5 Å) are accepted from the first input file while the second file has useful reflections within the resolution range 10 ... 2 Å.


WFAC1=

This parameter is used for recognizing MISFITS (reflections that are incompatible with the observed intensities of symmetry related ones).

Example:  WFAC1=1.5
Default value is 1.5 and hardly needs to be changed. A larger value would reduce the number of MISFITS so that more reflections are available for determination of correction factors. This could be important in the case of scaling many data snippets into a combined output data set.


WEIGHT=

This parameter defines a weight for the most recently defined input file. 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.


NBATCH=

Number of batches, controlling the number of correction factors (NBATCH X 13) applied to the reflection intensities of the most recently defined input file. To prevent overfitting, the parameter value should be chosen small enough (1...36) so that there are enough symmetry-related reflections. However, it is recommended to leave the parameter unspecified. In this case, XSCALE will determine a reasonable value.


CORRECTIONS=

This optional parameter allows the user to select the corrections to be applied to the reflection intensities of the most recently defined input file. Possible values are a combination of the keywords DECAY MODULATION ABSORPTION or ALL if all three corrections should be carried out. Default value is CORRECTIONS= ALL.
DECAY indicates that correction factors should be determined and applied to the intensities as function of image number and resolution.
MODULATION indicates that correction factors should be determined and applied to the intensities as function of X and Y in the detector plane.
ABSORP indicates that correction factors should be determined and applied to the intensities as function of image number and 13 reference positions in the detector plane.

Example
INPUT_FILE=*../XDS_ASCII.HKL
INCLUDE_RESOLUTION_RANGE=50 1.2 WEIGHT=1.0 NBATCH=36
CORRECTIONS=DECAY MODULATION ABSORPTION
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 default 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. 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 in overfitting the data. Finally, the parameter value for CORRECTIONS= indicates that the input data set should be corrected for radiation damage, absorption effects, and variations in sensitivity of the detector surface. Specification of this parameter could have been omitted as these corrections would have been carried out by default.


SAVE_CORRECTION_IMAGES=

This parameter specifies whether control images of the corrections determined and applied to the data should be saved for inspection or not. The default is SAVE_CORRECTION_IMAGES= TRUE which is fine for the usual case of less than 10 input data sets. However, when scaling hundreds of data sets, storage of these images would consume a substantial amount of disk space - usually nobody would look at them. In this case the user could specify SAVE_CORRECTION_IMAGES=FALSE for reasons of efficiency.


CRYSTAL_NAME=

This parameter specifies the name of the crystal used to collect data of the most recently defined input file. 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. b(h) is saved on the scaled output data file as ITEM_DCY if MERGE=FALSE has been specified.


STARTING_DOSE=
DOSE_RATE=

These two parameters refer to the most recently defined input file. Their values 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.


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.


© 2009-2015, MPI for Medical Research, Heidelberg Imprint.
Wolfgang.Kabsch@mpimf-heidelberg.mpg.de
page last updated: January 10, 2015