XSCALE 

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.


Example 1 for XSCALE.INP:
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

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

MINIMUM_I/SIGMA=4.0
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 second 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.


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