2,652
edits
Xscale: Difference between revisions
Jump to navigation
Jump to search
m
fix links
m (fix links) |
|||
| (22 intermediate revisions by 2 users not shown) | |||
| Line 1: | Line 1: | ||
== Simple and advanced usage == | == Simple and advanced usage == | ||
[http:// | [http://xds.mpimf-heidelberg.mpg.de/~kabsch/xds/html_doc/xscale_parameters.html XSCALE] is the stand-alone scaling program of the XDS suite. It scales reflection files (typically called XDS_ASCII.HKL) produced by XDS. Since the CORRECT step of XDS ''already scales'' an individual dataset, XSCALE is only ''needed'' if several datasets should be scaled relative to another. However, it does not deterioriate (over-fit) a dataset if it is "scaled again" in XSCALE, since the supporting points of the scalefactors are at the same positions in detector and batch space. | ||
One advantage of using XSCALE for a single dataset is that the user can specify the number and limits of the resolution shells. Another is that zero-dose extrapolation can be done. | |||
At the XDS website, there is a short and a long commented example of [http://xds.mpimf-heidelberg.mpg.de/html_doc/INPUT_templates/XSCALE.INP XSCALE.INP] | |||
---- | ---- | ||
| Line 16: | Line 20: | ||
FRIEDEL'S_LAW=FALSE | FRIEDEL'S_LAW=FALSE | ||
STRICT_ABSORPTION_CORRECTION=TRUE ! see XDSwiki:Tips_and_Tricks | STRICT_ABSORPTION_CORRECTION=TRUE ! see XDSwiki:Tips_and_Tricks | ||
INPUT_FILE= ../fae-rh/xds_2/XDS_ASCII.HKL | ! the star in front of the file name indicates that it is the reference wrt falloff | ||
INPUT_FILE= *../fae-rh/xds_2/XDS_ASCII.HKL | |||
FRIEDEL'S_LAW=FALSE | FRIEDEL'S_LAW=FALSE | ||
STRICT_ABSORPTION_CORRECTION=TRUE | STRICT_ABSORPTION_CORRECTION=TRUE | ||
OUTPUT_FILE=fae-ip.ahkl | OUTPUT_FILE=fae-ip.ahkl | ||
INPUT_FILE= ../fae-ip/ | INPUT_FILE= ../fae-ip/xds_1/XDS_ASCII.HKL | ||
FRIEDEL'S_LAW=FALSE | FRIEDEL'S_LAW=FALSE | ||
STRICT_ABSORPTION_CORRECTION=TRUE | STRICT_ABSORPTION_CORRECTION=TRUE | ||
| Line 30: | Line 35: | ||
== Further keywords == | == Further keywords == | ||
* RESOLUTION_SHELLS= ! for the printout of R-factors, completeness, ... | * [http://xds.mpimf-heidelberg.mpg.de/html_doc/xscale_parameters.html#RESOLUTION_SHELLS= RESOLUTION_SHELLS=] ! for the printout of R-factors, completeness, ... | ||
* SPACE_GROUP_NUMBER= ! if not given, picked up from first input reflection file | * 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 | * UNIT_CELL_CONSTANTS= ! if not given, picked up from first input reflection file | ||
=== keywords with the same meaning as in CORRECT === | === keywords with the same meaning as in CORRECT === | ||
* REIDX= | * REIDX= | ||
* REFERENCE_DATA_SET= | * REFERENCE_DATA_SET= ! see also [[REFERENCE_DATA_SET]] | ||
* MINIMUM_I/SIGMA= | * MINIMUM_I/SIGMA= | ||
* REFLECTIONS/CORRECTION_FACTOR= | * REFLECTIONS/CORRECTION_FACTOR= | ||
| Line 43: | Line 48: | ||
* MAXIMUM_NUMBER_OF_PROCESSORS= | * MAXIMUM_NUMBER_OF_PROCESSORS= | ||
* CORRECTIONS= | * CORRECTIONS= | ||
* NBATCH= | * NBATCH= | ||
=== keywords unique to XSCALE === | === keywords unique to XSCALE === | ||
* MERGE= ! average intensities from all input files, applies to output file | * MERGE= ! average intensities from all input files, applies to output file | ||
* WEIGHT= ! applies to input file | * WEIGHT= ! applies to input file | ||
* CRYSTAL_NAME= ! switch on radiation damage correction | * CRYSTAL_NAME= ! switch on radiation damage correction for individual reflections (f.i.r.) | ||
* STARTING_DOSE= ! (optional for radiation damage correction) | * STARTING_DOSE= ! (optional for radiation damage correction f.i.r.) | ||
* DOSE_RATE= ! (optional for radiation damage correction) | * DOSE_RATE= ! (optional for radiation damage correction f.i.r.) | ||
* 0-DOSE_SIGNIFICANCE_LEVEL= ! (optional for radiation damage correction) | * 0-DOSE_SIGNIFICANCE_LEVEL= ! (optional for radiation damage correction f.i.r.) | ||
* SAVE_CORRECTION_IMAGES= ! Default is TRUE. If FALSE, don't write DECAY*.cbf MODPIX*.cbf ABSORP*.cbf | |||
== Radiation damage correction == | == Radiation damage correction == | ||
| Line 56: | Line 63: | ||
=== based on resolution shell and frame number === | === based on resolution shell and frame number === | ||
The usual (like in | The usual correction (like in AIMLESS and SCALEPACK) 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. | 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 === | === for individual reflections: zero-dose extrapolation === | ||
To "switch on" radiation damage correction of individual reflections ([http://dx.doi.org/10.1107/S0907444903006516 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. | To "switch on" radiation damage correction of individual reflections ([http://dx.doi.org/10.1107/S0907444903006516 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. | ||
| Line 91: | Line 98: | ||
CRYSTAL_NAME=Hg | CRYSTAL_NAME=Hg | ||
STARTING_DOSE=-22.* ! assuming the dataset has 100 frames | 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) | 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) 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. | 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. | ||
== Scaling many datasets == | |||
When scaling e.g. hundreds of partial datasets, XSCALE may finish with an error message !!! ERROR !!! INSUFFICIENT NUMBER OF COMMON STRONG REFLECTIONS . This usually indicates that one or more datasets have too few reflections. Please inspect the table | |||
<nowiki> | |||
DATA MEAN REFLECTIONS INPUT FILE NAME | |||
SET# INTENSITY ACCEPTED REJECTED | |||
</nowiki> | |||
and check the column "ACCEPTED REFLECTIONS". Then remove the dataset(s) with fewest accepted reflections, and re-run the program. Repeat if necessary. | |||
The latest XSCALE (March 1, 2015) makes it explicit which dataset(s) it cannot scale; it prints out e.g. "no common reflections with data set 197". If you get this message for many datasets, I suggest to have a line | |||
MINIMUM_I/SIGMA=2 ! reduce to 1, or 0.5, or 0.25, or 0.125, or ... to lower the cutoff | |||
after each INPUT_FILE= line, to increase the number of reflections available for scaling. However, MINIMUM_I/SIGMA= should not be decreased needlessly below its default of 3. | |||
Old versions of XSCALE may also finish with the error message !!! ERROR !!! INACCURATE SCALING FACTORS. This usually indicates that one or more datasets are linearly depending on others (this happens if the ''same'' data are included more than once as INPUT_FILE), or are pure noise. The latest version of XSCALE (March 1, 2015) copes much better with this situation; I have not seen this error message any more. | |||