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 occurrence 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.
This parameter defines the maximum number of cpu's that can be employed by the parallel version of XSCALE. The default value is equal to the number of available cpu's. The parameter is ignored in the single processor version of XSCALE.
Example: MAXIMUM_NUMBER_OF_PROCESSORS= 16
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 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 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°.
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.
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.
This parameter defines the minimum required signal/noise of reflections used for determination of correction factors.
Example: SNRC=0.1
This is the default. A larger value would reduce the number of useful
reflections and lead to fewer correction factors that could be determined.
This defines the angular range of rotation (°) covered by a batch of consecutive images. It applies to all input data sets and is used to control the number of correction factors along image number.
Example: BATCHSIZE=5.0
A batch of consecutive images must cover 5.0° of spindle rotation.
This is the default.
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.
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 256 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 occurrence 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.
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.
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).
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).
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.
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.
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. The given value overrides the corresponding one in the file header 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 Å.
This parameter influences the classification of outlier reflections in a list of symmetry related reflection intensities. For decision making the given standard errors are multiplied by WFAC1. Thus, increasing values would result in fewer rejected reflections (MISFITS).
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.
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.
This optional parameter provides a possibility for reindexing
the reflections of the most recently defined
input file.
Other input files are not affected. The meaning
of the 12 integers that make up the parameter value is defined as:
h' = REIDX_ISET(1)*h + REIDX_ISET( 2)*k + REIDX_ISET( 3)*l + REIDX_ISET( 4)
k' = REIDX_ISET(5)*h + REIDX_ISET( 6)*k + REIDX_ISET( 7)*l + REIDX_ISET( 8)
l' = REIDX_ISET(9)*h + REIDX_ISET(10)*k + REIDX_ISET(11)*l + REIDX_ISET(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. The general parameter
REIDX= is applied to the indices h' k' l'.
The possibility for independent reindexing of individual input data sets
could be useful for generating a consistent indexing scheme in case the
lattice symmetry is higher than the symmetry of the point group.
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.
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.
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.
This parameter can be used to suppress printing of correlation factors. The parameter value is TRUE by default.
Example: PRINT_CORRELATIONS= FALSE
For a large number of data sets it may be desirable to avoid printing long
lists of correlation factors between the data set pairs.
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.
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.
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-2023, MPI for Medical Research, Heidelberg