• puts one or more files obtained from data processing with xds on a common scale and reports completeness and quality of the data sets,
• offers a choice to either combine symmetry-equivalent observations into a single unique reflection (merge) or to save the scaled but unmerged observations on the output file,
• allows for several output files that are placed on the same scale - a feature that is recommended for MAD data sets taken from the same crystal at different wavelengths,
• determines correction factors that partially compensate for absorption effects, sensitivity variations in the detector plane, and radiation damage,
• can correct reflections individually for radiation damage (for reference on this subject, see the article by Diederichs, McSweeney & Ravelli).

The files used or generated by XSCALE are either ASCII files that can be inspected and modified by using a text editor, or binary, compressed image files in the CBF format, a byte-offset variant of the CBFlib format that can be looked at using the XDS-Viewer program. Such files are indicated by the file name extension ".cbf" and represent the correction factors determined by XSCALE as two-dimensional images.

All files have fixed names defined by XSCALE, which makes it mandatory to run the program in a newly created directory to avoid name clashes. Clearly, one should not run more than one XSCALE-job simultaneously in the same directory. Also, when rerunning XSCALE, files from a previous run should first be given another name if their original contents are meant to be saved.

The easiest way to run XSCALE is to copy a template input file named XSCALE.INP to the new directory and to replace the parameter values by the appropriate ones describing the actual scaling run (see Input Parameters). The resulting scaled data set is of XDS_ASCII format. It can be converted into a CCP4-style multi-record MTZ-file using the copy feature of pointless or converted in a subsequent step by xdsconv into a format required by various structure solution packages.

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 the user has to provide for scaling data sets collected in a three-wavelength anomalous scattering experiment, with two input data sets at each wavelength. Reflections of the 3 output files will be unmerged and Friedel pairs considered different if this holds for all of the input data sets. The '*' preceeding the name of one of the input files marks it as a reference that defines the fall-off with respect to resolution for all output data sets. This example demonstrates how XSCALE knows which input files should be scaled to which output file: the most recently defined output file will contain the scaled reflections from all following input files until the definition of another output file.

Example 2 for XSCALE.INP

MAXIMUM_NUMBER_OF_PROCESSORS=8

SAVE_CORRECTION_IMAGES= TRUE
PRINT_CORRELATIONS= TRUE
  
RESOLUTION_SHELLS= 10 6 5 4 3 2.5 2.0 1.9 1.85
SPACE_GROUP_NUMBER=19
UNIT_CELL_CONSTANTS=40.38 47.86 57.88   90 90 90

SNRC=0.1
REFLECTIONS/CORRECTION_FACTOR=100
0-DOSE_SIGNIFICANCE_LEVEL=0.05

OUTPUT_FILE=a_unmerged.ahkl
 FRIEDEL'S_LAW=FALSE MERGE=FALSE
 STRICT_ABSORPTION_CORRECTION=FALSE
 INPUT_FILE= 1_XDS_ASCII.HKL
  INCLUDE_RESOLUTION_RANGE=50 1.85
  CORRECTIONS= DECAY MODULATION ABSORPTION
  CRYSTAL_NAME=a
 INPUT_FILE= 2_XDS_ASCII.HKL
  INCLUDE_RESOLUTION_RANGE=50 1.85
  CORRECTIONS= DECAY MODULATION
  CRYSTAL_NAME=a
 INPUT_FILE= 3_XDS_ASCII.HKL
  INCLUDE_RESOLUTION_RANGE=50 2.30
  CORRECTIONS= DECAY MODULATION
  CRYSTAL_NAME=a
 INPUT_FILE= 4_XDS_ASCII.HKL
  INCLUDE_RESOLUTION_RANGE=50 1.85
  CORRECTIONS= DECAY MODULATION
  CRYSTAL_NAME=a
 INPUT_FILE= 5_XDS_ASCII.HKL
  INCLUDE_RESOLUTION_RANGE=50 2.30
! CORRECTIONS=DECAY MODULATION ABSORPTION
  CRYSTAL_NAME=a

This example uses many of XSCALE's possible input parameters for a more tight control of the scaling by the user.
The first line specifies that up to 8 cpu's may be employed by the parallel version of XSCALE which overrides the default. The next two lines specify the amount of control output which could be excessive for a large set of input data sets. The following line specifies the resolution shells for reporting scaling statistics rather than using the automatically determined ones. Also, space group number and unit cell constants are explicitly provided here instead of being automatically taken from the header of the first input file.
Compared with the defaults the next block of input parameters imposes more stringent conditions on the number of strong reflections to be used for the determination of correction factors. Also, the risk of overfitting the 0-dose radiation damage corrections has been reduced to 0.05.
The 5 input files comprise data sets from the same crystal, named a, that should be scaled but not merged to one output data set, named a_unmerged.ahkl. By specifying MERGE=FALSE information about X,Y-position, image number, psi-angle, input data set identifying number and individual decay constant of the original input reflections are retained in the output file. Also, the output data records are ordered so that symmetry-related reflections and their Friedel mates follow each other. Although anomalous intensity differences are expected to be present in the data (FRIEDEL'S_LAW=FALSE), Friedel-pairs are treated as symmetry-equivalent reflections in the calculation of the absorption correction factors according to the default value of the parameter STRICT_ABSORPTION_CORRECTION=FALSE.
Instead of using all reflections from the input files (default) only subsets are accepted as specified by the INCLUDE_RESOLUTION_RANGE= parameters. Moreover, different ways of corrections are requested here for each input data set as indicated by the different values for the parameter CORRECTIONS=. Note, that the first and last input file will be corrected for DECAY, MODULATION, and ABSORPTION -which is the default- while reflections in the other input files are only corrected for DECAY and MODULATION. By specifying CRYSTAL_NAME=, the user requests that the reflections should be corrected individually for radiation damage (for reference on this subject, see the article by Diederichs, McSweeney & Ravelli). The maximum probability for applying the individual correction when this should not have been done (probability for overfitting) is limited to 0.05 as mentioned above.

Example 3 for XSCALE.INP

RESOLUTION_SHELLS= 100 10 6 4 3 2 1.9
SPACE_GROUP_NUMBER=78
UNIT_CELL_CONSTANTS=57.39 57.39 106.9   90 90 90
OUTPUT_FILE=scaf8_all_merged.hkl
MERGE=TRUE FRIEDEL'S_LAW=FALSE
STRICT_ABSORPTION_CORRECTION=TRUE
 INPUT_FILE= ../xds-1_2/XDS_ASCII.HKL
   REIDX_ISET= -1  0  0  0  0  1  0  0  0  0 -1  0
 INPUT_FILE= ../xds-2_1/XDS_ASCII.HKL
 INPUT_FILE= ../xds-3_1/XDS_ASCII.HKL
 INPUT_FILE= ../xds-1_4/XDS_ASCII.HKL
 INPUT_FILE=*../xds-5_1/XDS_ASCII.HKL

The crystal has P4_3 space group symmetry (SPACE_GROUP_NUMBER=78) which is lower than the 422 symmetry of its lattice. This implicates two equally valid, but different sets of unit cell basis vectors. From a comparison of the results of an initial scaling of the 5 input data sets it became obvious that the first one is incompatible with the others. Indeed, much better agreement was obtained when choosing the other alternative for the basis vectors (REIDX_ISET=). The last specified data set serves as a reference as indicated by the * preceding its name.
Because of the high multiplicity of observed reflections (not shown) it was decided to treat Friedel-pairs as different reflections in the calculation of the absorption correction factors, hence STRICT_ABSORPTION_CORRECTION=TRUE.