Xscale

Simple and advanced usage

XSCALE is the scaling program of the XDS suite. At the XDS website, there is a short and a long commented example of XSCALE.INP

A minimal input file to combine two datasets into one file is:

OUTPUT_FILE=fae-native.ahkl 
INPUT_FILE= ../fae-native/xds_1/XDS_ASCII.HKL
INPUT_FILE= ../fae-native/xds_2/XDS_ASCII.HKL

Several output files can be specified (together with their set of input files) in a single run of XSCALE, simply by concatenation of sections like the above. All output files are then on the same scale - a program feature recommended for MAD data sets:

OUTPUT_FILE=fae-rh.ahkl 
INPUT_FILE= ../fae-rh/xds_1/XDS_ASCII.HKL
FRIEDEL'S_LAW=FALSE   
STRICT_ABSORPTION_CORRECTION=TRUE         ! see XDSwiki:Tips_and_Tricks
INPUT_FILE= ../fae-rh/xds_2/XDS_ASCII.HKL
FRIEDEL'S_LAW=FALSE
STRICT_ABSORPTION_CORRECTION=TRUE

OUTPUT_FILE=fae-ip.ahkl 
INPUT_FILE= ../fae-ip/xds_2/XDS_ASCII.HKL
FRIEDEL'S_LAW=FALSE
STRICT_ABSORPTION_CORRECTION=TRUE
INPUT_FILE= ../fae-ip/xds_2/XDS_ASCII.HKL
FRIEDEL'S_LAW=FALSE
STRICT_ABSORPTION_CORRECTION=TRUE

Further keywords

RESOLUTION_SHELLS= ! for the printout of R-factors, completeness, ...
SPACE_GROUP_NUMBER= ! if not given, picked up from first input reflection file
UNIT_CELL_CONSTANTS= ! if not given, picked up from first input reflection file

keywords with the same meaning as in CORRECT

REIDX=
REFERENCE_DATA_SET=
MINIMUM_I/SIGMA=
REFLECTIONS/CORRECTION_FACTOR=
FRIEDEL'S_LAW=
STRICT_ABSORPTION_CORRECTION=
INCLUDE_RESOLUTION_RANGE=
MAXIMUM_NUMBER_OF_PROCESSORS=
CORRECTIONS=
NBATCH=

keywords unique to XSCALE

MERGE= ! average intensities from all input files, applies to output file
WEIGHT= ! applies to input file
CRYSTAL_NAME= ! switch on radiation damage correction
STARTING_DOSE= ! (optional for radiation damage correction)
DOSE_RATE= ! (optional for radiation damage correction)
0-DOSE_SIGNIFICANCE_LEVEL= ! (optional for radiation damage correction)

Radiation damage correction

based on resolution shell and frame number

The usual (like in MOSFLM and other programs) correction based on resolution shell and frame number is performed in XDS as part of the CORRECT step - it can be switched off by omitting DECAY from the default CORRECTIONS= DECAY MODULATION ABSORP. DECAY correction is also the default in XSCALE.

It is instructive to inspect DECAY.cbf (using "XDS-Viewer DECAY.cbf"). This visualizes the scale factors employed by the CORRECT step (the equivalent files from XSCALE are called DECAY_*.cbf); the right sidebar gives the mapping between shades of gray, and numbers (1000 corresponds to a scalefactor of 1). Along the horizontal axis the frame number (or rather the batch number) is shown, along the vertical axis the resolution shell.

for individual reflections

To "switch on" radiation damage correction of individual reflections (K. Diederichs, S. McSweeney and R. B. G. Ravelli (2003) Zero-dose extrapolation as part of macromolecular synchrotron data reduction. Acta Cryst. D59, 903-909) it suffices to use the CRYSTAL_NAME keyword. The CRYSTAL_NAME parameters of different datasets do not have to be different. If they are different, this results in more degrees of freedom (namely, the slopes of the reflection intensity as a function of dose) for the program to fit the observed changes of intensities which are induced by radiation damage. However, if the datasets are based on the same crystal, or the datasets are based on crystals from the same drop, it is reasonable to assume that the slopes are the same. Example:

OUTPUT_FILE=fae-merge.ahkl 
  INPUT_FILE= ../fae-ip/xds_1/XDS_ASCII.HKL  !
  CRYSTAL_NAME=ip
  INPUT_FILE= ../fae-ip/xds_2/XDS_ASCII.HKL  ! same crystal, but translated along z
  CRYSTAL_NAME=ip

This is the recommended way as it reduces overfitting.

If, however, the crystals represent different heavy atom soaks, it is advisable to give a different CRYSTAL_NAME to each dataset. Example:

OUTPUT_FILE=hg.ahkl 
  INPUT_FILE= ../xds-hg/XDS_ASCII.HKL  ! a mercury soak
  CRYSTAL_NAME=Hg

OUTPUT_FILE=pt.ahkl
  INPUT_FILE= ../xds-pt/XDS_ASCII.HKL  ! a platinum soak
  CRYSTAL_NAME=Pt

A word of warning: even if the internal quality indicators (R-factors) are better when using this feature, there is no guarantee that the resulting intensities will actually be better suited for your purposes than those obtained without it. In particular, extrapolating to the ends of the dose interval (0 dose and full dose) decreases the precision of the intensities.

Optimal values of dose, for interpolation

The optimal points for interpolation are near 1/4 and near 3/4 of the total dose. Details are published in Diederichs, K., Junk, M. (2009) Post-processing intensity measurements at favourable dose values. J. Appl. Cryst. 42, 48-57.

To interpolate to 22% of the full dose, one has to give a STARTING_DOSE less than zero:

OUTPUT_FILE=hg.ahkl 
  INPUT_FILE= ../xds-hg/XDS_ASCII.HKL  ! a mercury soak
  CRYSTAL_NAME=Hg
  STARTING_DOSE=-22.*   ! assuming the dataset has 100 frames

Explanation: the interpolation is done towards 0, and by defining the start of the dataset to be at -22., one tells the program to calculate (by interpolation) those intensity values that would be obtained at dose 0 which in reality is near frame 22.

Another example: by defining STARTING_DOSE=-78.* one would tell the program to calculate, by interpolation, those intensity values that correspond to those that would be obtained near frame 78.

A hint for long-time XSCALE users

a) The latest versions do not require

SPACE_GROUP_NUMBER=
UNIT_CELL_PARAMETERS=

in XSCALE.INP because these parameters are picked up from the header of the first input reflection file.

b) The VIEW program was replaced with the XDS-Viewer program.