Input Parameters

This chapter explains the meaning of all parameters the user can specify to control the actions of the nXDS/nXSCALE program package. The specified parameters are collected in ASCII files nXDS.INP and nXSCALE.INP which must reside in the processing directory where the program will be invoked.

The parameters may be given in arbitrary order. Each parameter name consists of a string of characters without intervening blanks or exclamation marks and includes an equal sign as its last character. The value must follow the parameter name on the same line. The parameter names cannot be abbreviated; they are case sensitive, too. Characters in a line to the right of an exclamation mark are comment.


JOB=

The value of JOB= can be any combination of the keywords described below. Each keyword names a subroutine to be executed. If the parameter JOB= is omitted, all of the steps will be carried out in succession.

XYCORR
computes a table of spatial correction values for each pixel
FILTER
recognizes and removes bad images from further processing
INIT
determines an inital background for each detector pixel and finds the trusted region of the detector surface.
COLSPOT
collects strong diffraction spots from a specified set of data images
POWDER
computes a control image containing a powder pattern of the strong diffraction spots found in the data images
IDXREF
interprets observed spots occuring in a data image by a crystal lattice and refines all diffraction parameters
INTEGRATE
determines intensities by profile fitting for all reflections occuring in the data images
CORRECT
resolves possible indexing ambiguities by comparison with a given reference data set or by a genetic algorithm, determines scaling and correction factors by a post-refinement procedure for the recorded intensities in the data images, reports quality and completeness of the data, and saves the fully corrected integrated intensities on the file nXDS_ASCII.HKL - ready for use by subsequent program packages for structure determination.

Example: JOB=IDXREF INTEGRATE CORRECT
nXDS will execute the specified subroutines only and will skip the previous steps XYCORR, INIT, COLSPOT, POWDER. This saves time if you like to try indexing alternatives in cases the IDXREF step has failed in a previous run because of a misindexing problem.


MAXIMUM_NUMBER_OF_JOBS=

This parameter was introduced to make use of Unix/Linux-clusters to reduce the wall-clock time needed for data processing during the COLSPOT, IDXREF, and INTEGRATE steps of nXDS. The default is to let nXDS divide the computations into approximately equal portions that are each processed as an independent main program by the computer cluster (CLUSTER_NODES=). The results from each main program are saved as files that are subsequently joined for the final output. The parameter value specifies the maximum number of such independent jobs. Up to 99 jobs are allowed.

However, any parameter value given by the user will be ignored in case data collection overlaps with data processing which is indicated by a positive value of the parameter SECONDS=. In this case nXDS enforces MAXIMUM_NUMBER_OF_JOBS=1 and MAXIMUM_NUMBER_OF_PROCESSORS=1.

The present implementation of nXDS requires that all cpu nodes of the cluster use identical conventions for their binary files and number representations and are controlled by a Unix/Linux operating system. It is not necessary that the processors share the same address space since the jobs are independent processes that do not communicate at all.

Example: MAXIMUM_NUMBER_OF_JOBS= 4 
The set of collected data images is divided into approximately 4 equal portions that are simultaneously processed each as an independent job by the computer cluster during the COLSPOT, IDXREF, and INTEGRATE steps.

Parameter is used by COLSPOT, IDXREF, INTEGRATE.
 


MAXIMUM_NUMBER_OF_PROCESSORS=

This parameter defines the maximum number of processor cores that can be employed by the parallel version of nXDS (nxds_par, nxscale_par) for data processing. The parallel versions use OpenMP for execution by a team of up to 99 threads and require a shared memory multiprocessor platform. The parameter is ignored in the single processor version of nXDS.

Example
MAXIMUM_NUMBER_OF_PROCESSORS= 4 
MAXIMUM_NUMBER_OF_JOBS=16 
SECONDS= 0 
!JOB=
All steps of nXDS will be carried out by default because specific steps have not been requested. In the COLSPOT and INTEGRATE steps the set of data images is subdivided into 16 approximately equal portions and each portion is processed by a team of 4 cpu's. In the IDXREF and CORRECT step, 4 cpu's will be used for the refinements and for solving systems of equations.

Parameter is used by COLSPOT, IDXREF, INTEGRATE, CORRECT.
 


CLUSTER_NODES=

This parameter specifies the names of the nodes of the computer cluster you would like to run nXDS. These nodes name a subset of the remote hosts in the NFS networked environment of your computer cluster where each host may comprise a shared memory multiprocessor system. In case of less than two specified nodes nXDS will run on the peer node. At most 99 nodes may be specified.

The cluster nodes should use a network file system with common mountpoints, and allow command execution by ssh without asking for a password (see Installation on a computer cluster in downloading). The automatic distribution of the computations assumes cluster nodes of similar performance and identical number of cores.

Example:
CLUSTER_NODES=bragg01 bragg02 bragg03 bragg04
!MAXIMUM_NUMBER_OF_PROCESSORS= 4 
!MAXIMUM_NUMBER_OF_JOBS=16 
!SECONDS= 0 
!JOB=
nXDS will check the computer network and automatically distribute processing of your data set among the 4 specified nodes in an optimal way. Other nodes of the cluster - if they exist - are not used by nXDS (as a courtesy to other users of the cluster).

Parameter is used by COLSPOT, IDXREF, INTEGRATE.
 


IMAGE_DIRECTORY=

Path name of the directory containing the images for processing. The default directory name is ./ This is one of two ways nXDS can use for accessing data Images.

Example:
IMAGE_DIRECTORY=../images/
Starting from the processing directory the data images are found in directory ../images. Note that the trailing slash specifying the image directory name is optional and could have been omitted.

Parameter is used by INIT, COLSPOT, IDXREF, INTEGRATE.
 


IMAGE_LIST=

File name of a list containing the file names of the images residing in the directory specified by the input parameter IMAGE_DIRECTORY=. There must be exactly one file name in each line of the list.

To save space it is allowed to compress the images by using the UNIX compress, gzip, or bzip2 routines. On data processing nXDS will automatically recognize and expand the compressed files. The file name extensions (.Z, .z, .gz, .bz2) due to the compression routines should not be included in the file name list.

For most of the detectors presently used the image format is recognized automatically by nXDS (see section Images).

Example: IMAGE_DIRECTORY=../images/
IMAGE_LIST=Liste1
An image list of all files in the directory ../images can be generated by moving the current directory to ../images and issuing the command 'ls -1 * >Liste1' and subsequent moving Liste1 to the processing directory where nXDS will be invoked.

Parameter is used by INIT, COLSPOT.
 


NAME_TEMPLATE_OF_DATA_FRAMES=

File name template and format of the data images (see Example 1). This is one of two ways nXDS can use for accessing data Images.

For addressing a specific data image, nXDS will substitute the appropriate image number (including leading zeros) for the question marks in the file name template. File name extensions (.Z, .z, .gz, bz2) due to the use of UNIX routines to compress the images should not be included in the file name template.

The name template may be followed by a keyword specifying the format of the data image files. For a list of recognized format keywords, see Images. For most of the detectors presently used the image format is recognized automatically by nXDS and a format keyword like GENERIC in Example 1 below is not needed. However, if the format is explicitly named, nXDS will attempt to read the image in the specified way. The format keyword applies to all data images with the given file name template.

Example 1:
NAME_TEMPLATE_OF_DATA_FRAMES= ../data_images_??????.h5 GENERIC
DATA_RANGE=1 1234
EXCLUDE_DATA_RANGE=15 15
EXCLUDE_DATA_RANGE=1007 1015
LIB=name_of_external_library

This is the generic method used for accessing images. It relies on an external library LIB. The library in this example is provided by the manufacturer of the EIGER detector (DECTRIS AG, Basel). The image numbers are taken from the file SHOTNUMBERS in the execution directory that is generated by nXDS from the given data range; thus, data of the first and last image of the data range are specified by ../data_images_000001.h5 and ../data_images_001234.h5 where the six question marks are replaced by the image number (with leading zeros). Image 15 and images 1007 to 1015 are omitted from the file SHOTNUMBERS. The specified image data are retrieved by the external library routine named by the LIB= input parameter. The format specifier GENERIC may be omitted. Details of the method used by the library routine are irrelevant to XDS.
In the case of the EIGER detector, the external software constructs the name of a master file, ../data_images_master.h5, from the given name template by replacing the 6 question marks by the string master. This file contains a list of file names, each denoting a block of data comprising 100 detector images.

Exampl 2:
NAME_TEMPLATE_OF_DATA_FRAMES=../images/ga1_???.mar345 MAR345
DATA_RANGE=100 180

This specifies 81 images recorded by the MAR345 imaging plate scanner (X-ray Research). The image format specifier MAR345 could have been omitted. nXDS has an intrinsic reading procedure and does not require an external library routine for this type of images.


DATA_RANGE=

Numbers of first and last snapshot image collected (must be >0). See section Images.

Example: DATA_RANGE= 2   456
The snapshot images 2, 3, ..., 456 will be processed by nXDS. For accessing the images the question marks in the generic file name template (NAME_TEMPLATE_OF_DATA_FRAMES=) are substituted by the image numbers in succession.

Parameter is used to generate the file SHOTNUMBERS in the processing directory
 


EXCLUDE_DATA_RANGE=

The two numbers of this parameter denote the first and last snapshot of a range of images that are to be excluded from processing. An arbitrary number of such parameters can be specified in nXDS.INP. This offers a simple way to specify corrupted images stored in a container format (like EIGER images). See section Images.

Example: EXCLUDE_DATA_RANGE= 7 9 EXCLUDE_DATA_RANGE=99 99
The data images 7,8,9 and 99 will not be processed by nXDS.

Parameter is used to generate the file SHOTNUMBERS in the processing directory
 


LIB=

This optional parameter specifies the name of an external, dynamically linked library routine for reading images. It uses the generic_data_plugin module provided at http://strucbio.biologie.uni-konstanz.de/xdswiki/index.php/LIB
This wrap up module abstracts the interface from http://cims.nyu.edu/~donev/Fortran/DLL/DLL.Forum.txt.
The possibility to link a dynamic library renders nXDS more independent of the technical details of future detector image formats. See section Images.

Parameter is used by INIT, COLSPOT and INTEGRATE.
 


BACKGROUND_RANGE=

Running numbers of first and last data image in the list specified by the input parameter IMAGE_LIST=. These images are used for determining the initial background. If this parameter is omitted, nXDS will use at most the first 100 images.

Example: BACKGROUND_RANGE= 2   6
The initial background table BKGINIT.cbf will be determined from the data images 2, 3, ..., 6.

Parameter is used by INIT
 


GFRACT=

Decision constant for recognizing snapshot images that cannot result from diffraction as their pixel contents does not obey Poisson statistics.

Example: GFRACT= 0.1
This is the default value that works well for excluding blank snapshots from further data processing.

Parameter is used by FILTER
 


SECONDS=

Maximum number of seconds for nXDS to wait until data image must appear (default is 0). If a positive parameter value is specified, nXDS will set MAXIMUM_NUMBER_OF_JOBS=1, replacing any user input for this value.

Example: SECONDS=60
This allows you to start data processing by nXDS while data collection is still going on, but nXDS cannot make use of all of the computing power of the cluster.

Parameter is used by XYCORR, INIT, COLSPOT, INTEGRATE.
 


VERBOSE=

Controls the amount of printed output.

Parameter is used by CORRECT, nXSCALE.
 


DETECTOR=

Specifies the detector used for data collection. The parameter is used in the XYCORR step to select the method for computing spatial corrections appropriate for the detector. The parameter value can be:

Example: DETECTOR=CCDCHESS
If the MAR CCD or the CCD detector at CHESS was used for data collection.

Parameter is used by XYCORR, INTEGRATE
 


NX=
NY=

Number of "fast" and "slow" pixels , respectively, in a data image. The "fast" direction runs along X and the "slow" direction along Y. A pixel at IX, IY in an image is found at address IADR= IX + NX*(IY-1). Consult Table of supported detectors for selection of the correct parameter values.

Parameters are used by XYCORR, INIT, COLSPOT, IDXREF, INTEGRATE
 


QX=
QY=

Size of "fast" and "slow" pixels (mm) along X and Y, respectively. The "fast" direction runs along X and the "slow" direction along Y. A pixel at IX,IY in an image is found at address IADR= IX + NX*(IY-1). Consult Table of supported detectors for selection of the correct parameter values.

Parameters are used by XYCORR, POWDER, IDXREF, INTEGRATE
 


OVERLOAD=

The contents of a detector pixel is an integer value proportional to the number of X-ray quanta reaching the pixel. The maximum value of this proportional range is specified by the mandatory input parameter OVERLOAD=. If a pixel contents exceeds this maximum value the pixel is overloaded; a reflection is overloaded if its integration region includes one or more overloaded pixels.

In the "INTEGRATE" step overloaded reflections are excluded from the determination of reference profiles. Otherwise they are treated like all other reflections and saved on the output file INTEGRATE.HKL.
In the "CORRECT" step of nXDS overloaded reflections are excluded from the final output because their integrated intensities are incorrect. However, the user always has the possibility to repeat the "CORRECT" step with a different value for OVERLOAD=. There is no default value. For selection of an appropriate parameter value for your detector consult Table of supported detectors.

Example: OVERLOAD=110000
If you had your data processed with a higher parameter value and are afraid that some overloaded reflections are contaminating your final data set, you could rerun just the CORRECT step (by specifying JOB=CORRECT) with a smaller value for OVERLOAD=.

Parameter is used by INTEGRATE, CORRECT, nXSCALE
 


MINIMUM_VALID_PIXEL_VALUE=

Smaller pixel values in a data image are considered as invalid. The default value is dependent on the detector used, which is 0 in most cases. NOTE, that a negative value is invalid and used by nXDS for specifying broken or excluded pixel regions of the detector.

Parameter is used by INIT, COLSPOT, INTEGRATE
 


MINIMUM_FRACTION_OF_BACKGROUND_REGION=

The background region of the detector surface consists of one or more islands surrounded by 'untrusted' pixels. The parameter sets a lower limit on the size of each island considered to be useful for data processing. This limit is specified as a fraction of the size of the largest background region.

Example: MINIMUM_FRACTION_OF_BACKGROUND_REGION=0.01
This is the default and rarely needs to be changed. Background islands covering less than 1% of pixels compared to the largest island are treated as unreliable and excluded from data processing.

Parameter is used by INIT
 


SILICON=

Fraction of intensity loss per mm due to absorption in silicon. The absorption of x-rays depends on the wavelength; nXDS will provide the appropriate value for silicon unless specified by the user. This parameter applies to the PILATUS pixel detector which uses a silicon sensor for conversion of x-rays. Unlike CCD- and other detectors the PILATUS detector uses a finite silicon thickness (SENSOR_THICKNESS=0.32 mm) which makes it necessary to correct the reflection intensities for variations in the detection probability of the scattered x-rays. These variations result from different path length in the silicon sensor due to the oblique incidence of the diffracted beam.

Example: !SILICON=3.9
nXDS will compute the correct value for the specified x-ray wavelength since no positive value was given by the user. This is the recommended procedure. Uncommenting this parameter (by removal of the exclamation mark) would enforce nXDS to use the value 3.9.

Parameter is used by XYCORR, INTEGRATE, CORRECT, nXSCALE
 


SENSOR_THICKNESS=

Thickness (mm) of the detector's sensor used for conversion of x-rays. Unlike CCD-detectors which have typically a negligable value of about 0.01 mm, the PILATUS detector uses a finite silicon thickness of 0.32 mm. In the CORRECT step of nXDS this parameter is used in conjunction with SILICON= to correct reflection intensities for variations resulting from different path length in the silicon sensor due to the oblique incidence of the diffracted beam. The default value of the parameter is 0.0 which should be used for all other detectors except for the PILATUS pixel detector.

Example: !SENSOR_THICKNESS=0.32
nXDS will use the default value of 0.0 since this parameter was not specified. This is recommended for all but the PILATUS pixel detector. Uncommenting this parameter (by removal of the exclamation mark) would enforce nXDS to use the value 0.32 which is correct for the PILATUS.

Parameter is used by XYCORR, INTEGRATE, CORRECT, nXSCALE
 


ROFF=
TOFF=

Radial and tangential offset correction for spiral read-out scanners like MAR or MAC. At present nXDS cannot determine these values and only computes a look-up table of spatial corrections from the given values (coming from somewhere else). Usually, both values are zero.

Parameters are used by XYCORR
 


STOE_CALIBRATION_PARAMETERS=

This parameter is optional and has a meaning only for the STOE imaging plate spiral read-out detector (Stoe & Cie GmbH, Darmstadt, Germany). If specified, the parameter consists of 8 numbers, separated by at least one blank, from which the spatial correction tables X-CORRECTIONS.cbf and Y-CORRECTIONS.cbf are calculated in the XYCORR-step of nXDS. The numbers must be given in the order as they appear in the crystal file produced by the manufacturer's software: DEL_R DEL_H DEL_X DEL_Y DEL_D EPS_X EPS_Y EPS_Z.

Example: STOE_CALIBRATION_PARAMETERS=-0.031 0.149 0.056 -0.278 -0.120 0.046 -0.375 0.491
The first 5 values are off-sets specified in mm while the last 3 values refer to misalignment angles of the imaging plate given in degrees.

Parameter is used by XYCORR
 


BRASS_PLATE_IMAGE=

File name and format of brass-plate image used in step XYCORR to calculate the spatial correction tables X-CORRECTIONS.cbf and Y-CORRECTIONS.cbf. This is mandatory for the SIEMENS detector. For the SIEMENS detector a brass grid plate is mounted on the detector face and the detector is moved to exactly the distance used later for data collection. An iron x-ray source is placed exactly at the place later occupied by the crystal (the origin of the laboratory coordinate system) and the detector response is collected for about 60 min (depends on the source) and saved on a file whose name is the input value of BRASS_PLATE_IMAGE=. Note, that a misplaced x-ray source will result into wrong correction values computed by XYCORR which might prevent a proper indexing of the diffraction spots.

Example: BRASS_PLATE_IMAGE= ../images/brs13cm HARVARD

Parameter is used by XYCORR
 


HOLE_DISTANCE=

Grid distance (mm) between brass-plate holes. If specified, the given value overrides the default settings for the SIEMENS detector. For other detectors no defaults are available. They usually do not require a brass-plate image correction and the parameter HOLE_DISTANCE= will be ignored.

Parameter is used by XYCORR
 


MXHOLE=

Number of calibration holes of the brass-plate. If specified, the given value overrides the default settings for the SIEMENS detector. MXHOLE must always be <=1369. For other detectors no defaults are available. They usually do not require a brass-plate image correction and MXHOLE= is omitted from nXDS.INP.

Parameter is used by XYCORR
 


MNHOLE=

Minimum number of calibration spots from the brass-plate that must be observed on the calibration image. If specified, the given value overrides the default settings for the SIEMENS detector. MNHOLE should be slightly larger than half of the number of calibration holes of the brass-plate. For other detectors no defaults are available. They usually do not require a brass-plate image correction and MNHOLE= is omitted from nXDS.INP.

Parameter is used by XYCORR
 


X-GEO_CORR=
Y-GEO_CORR=

File name and format of two correction tables used to compensate the misorientations of the modules with respect to the X- and Y-axes of the PILATUS pixel detector. Although these are specific for each instrument of this type, they are independent of the detector's position and orientation. Moreover, the corrections need to be determined only once (by the manufacturer) as the modules do not change their place within the assembled detector. The geometrically corrected coordinates of a pixel at IX,IY are found by adding the table_value(IX,IY)/100.0 for the X- and Y-tables, respectively.
If both parameters are absent from nXDS.INP the geometrical corrections are assumed negligible.

Example:
X-GEO_CORR= GD_6M_X06SA_SLS_27022007_X.pck CCP4
Y-GEO_CORR= GD_6M_X06SA_SLS_27022007_Y.pck CCP4
The two geometrical correction files are located in the current directory and given in CCP4 format layout.

Parameter is used by XYCORR
 


DARK_CURRENT_IMAGE=

File name, access, and format of a dark-current (non-Xray background) image. This image will be used by "INIT" to generate a look-up table of the non-xray background at each pixel position. The table is saved in file "BLANK.cbf". The parameter is optional. If a dark-current image is not available, the table "BLANK.cbf" is generated either from the value of the parameter OFFSET=. For the SIEMENS detector, which has no dark current, the parameters OFFSET=, and DARK_CURRENT_IMAGE= are ignored.

Example: DARK_CURRENT_IMAGE= ../brown17_dark/dark_rc3_001 ESRF DIRECT

Parameter is used by INIT
 


OFFSET=

This parameter value specifies the dark-current (non-Xray background) contents in each data image pixel. The default value is 0. As the SIEMENS detector has no dark current, this parameter will be ignored. If a dark-current image (see DARK_CURRENT_IMAGE=) is not available, the table "BLANK.cbf" is generated by "INIT" from the value of the parameter OFFSET=.

Parameter is used by INIT
 


GAIN=

The gain parameter value g relates the contents of a detector pixel p to the equivalent number of X-ray quanta c seen by the pixel; i.e. p = g × c + o where o is the dark current offset (see OFFSET=). This optional parameter can be used to specify a single fixed conversion factor for all detector pixels. This may be useful for a 'true' counter detector (like PILATUS).
Usually the gain value is allowed to vary for each pixel and for this reason XDS does not provide a default value for GAIN=. Instead a look-up table GAIN.cbf is determined in the INIT step that contains the ratio between variance and mean of the pixel contents in the neighbourhood of each image pixel.

Example: GAIN=1.0
For a true counter detector (like PILATUS) one could define GAIN=1.0.

Parameter is used by INIT
 


TRUSTED_REGION=

Inner (RMIN) and outer (RMAX) relative radii limiting the trusted region on the detector. The relative radius of a pixel at IX, IY is defined as R = sqrt{((IX-NX/2)/(NX/2))^2 + ((IY-NY/2)/(NY/2))^2}. The pixel at IX, IY is within the trusted region if RMIN < R < RMAX. Default is RMIN=0 and RMAX=1.0. This parameter provides a simple way of defining the acceptable detector surface in the INIT step. During the IDXREF step of nXDS this parameter is checked again and only those spots are accepted that fall within the trusted region. Thus, in case IDXREF failed because of too many alien spots near the center of the image, the user could exclude these spots by an appropriate increase of RMIN and repeating IDXREF.

Example: TRUSTED_REGION=0.0 1.35
This includes the corners of the rectangular detector for data collection.

Parameter is used by INIT, IDXREF
 


UNTRUSTED_RECTANGLE=

This allows you to remove a rectangle from the trusted detector plane. The rectangle is specified by 4 numbers, namely the coordinates X1,X2 defining the X-interval and the coordinates Y1,Y2 defining the Y-interval (pixel). A pixel at IX,IY will be classified as 'untrusted' if X1 < IX < X2 and Y1 < IY < Y2. An arbitrary number (default 0) of these parameters may be specified.
This parameter provides a simple way of defining the acceptable detector surface by exclusion of bad rectangles which could have been caused by malfunctioning hardware. The pixel coordinates of the points defining the bad rectangle can be found by looking with the XDS-Viewer program at the background BKGINIT.cbf obtained from a preliminary run of INIT.

Example: UNTRUSTED_RECTANGLE=570 1469 1920 2048
The rectangle with a "fast" (X-) pixel coordinate between 570 1469 and a "slow" (Y-) coordinate between 1920 and 2048 is to be excluded from data processing.

Parameter is used by INIT
 


UNTRUSTED_ELLIPSE=

The 4 numbers X1,X2, Y1,Y2 of this parameter specify a rectangle of detector pixels (X1,X2 define the X-interval and Y1,Y2 define the Y-interval). Pixels covered by the largest ellipse that fits into this rectangle are considered as 'untrusted'. An arbitrary number (default 0) of these parameters may be specified.
This parameter provides a simple way of excluding pixel regions shaded by the beam stop. The X- and Y-intervals can be found easily by looking with the XDS-Viewer program at the background BKGINIT.cbf obtained from a preliminary run of the INIT step of nXDS. To exclude this bad region rerun INIT with the appropriate parameter values.

Example: UNTRUSTED_ELLIPSE=570 1469 1920 2048
The largest ellipse that fits into the rectangle with a "fast" (X-) coordinate between 570 1469 and a "slow" (Y-) coordinate between 1920 and 2048 will be excluded from data processing.

Parameter is used by INIT
 


UNTRUSTED_QUADRILATERAL=

This parameter defines a convex quadrilateral by 4 corners where each corner is specified by its X,Y pixel coordinates. Thus 8 numbers must be provided, separated by at least one blank character. An interior point of the quadrilateral will always be seen on the same side (either left or right) by a person walking along the lines connecting the 4 corners in succession and coming back to the starting point. Pixels that are interior points of the quadrilateral are considered as 'untrusted'. An arbitrary number (default 0) of these parameters may be specified.
This parameter provides a simple way of excluding shaded pixel regions that cannot be enclosed by border lines parallel to the detector's X and Y directions. The X,Y pixel coordinates of the 4 corners an be found easily by looking with the XDS-Viewer program at the background BKGINIT.cbf obtained from a preliminary run of the INIT step of nXDS. To exclude this bad region rerun INIT with the appropriate parameter values.

Example: UNTRUSTED_QUADRILATERAL=565 1574 159 1552 1508 1533 566 1536
Pixels in the interior of the quadrilateral will be excluded from data processing.

Parameter is used by INIT
 


INCLUDE_RESOLUTION_RANGE=

An accepted reflection h, k, l must have a resolution d(h,k,l)=λ/{2sinθ} within the specified Å range. Detector pixels outside the specified resolution range are classified as untrusted and will not be used in the INTEGRATE and CORRECT steps of nXDS.

The parameter is also used by the CORRECT step of nXDS. This may be useful if you want to exclude high resolution reflections beyond the diffraction limit of your crystal from the final output file nXDS_ASCII.HKL. In this case you chose the appropriate resolution range and just repeat the CORRECT step of nXDS (JOB=CORRECT).

Example: INCLUDE_RESOLUTION_RANGE= 20.0 0.0
This is the default range. The low resolution limit is 20.0 Å, while the high resolution limit of 0.0 Å means that all recorded reflections will be accepted.

Parameter is used by IDXREF, INTEGRATE, CORRECT, nXSCALE
 


EXCLUDE_RESOLUTION_RANGE=

Resolution range (Å) for excluding reflections. This feature allows to remove ice-rings from the trusted region of the detector n the INTEGRATE step. Unfortunately, also good reflections in the specified resolution ranges are lost. From 0, which is the default, up to an arbitray number of such ranges may be specified.
Reflections of hexagonal ice are at 3.897, 3.669, 3.441, 2.671, 2.249 Å (Thomas Schneider and Elspeth Garman, J.Appl.Cryst. 30, 211-237, 1997)

Example:
EXCLUDE_RESOLUTION_RANGE= 3.93 3.87 ! ice-ring at 3.897 Å
EXCLUDE_RESOLUTION_RANGE= 3.70 3.64 ! ice-ring at 3.669 Å
EXCLUDE_RESOLUTION_RANGE= 3.47 3.41 ! ice-ring at 3.441 Å
EXCLUDE_RESOLUTION_RANGE= 2.70 2.64 ! ice-ring at 2.671 Å
EXCLUDE_RESOLUTION_RANGE= 2.28 2.22 ! ice-ring at 2.249 Å
All reflections with a resolution within any of the specified five ice-rings are excluded in the INTEGRATE step.

Parameter is used by IDXREF, INTEGRATE
 


MINIMUM_ZETA=

A reciprocal lattice point crosses the Ewald sphere by the shortest route if the crystal rotates about a (virtual) axis perpendicular to both the diffracted and incident beam wave vectors. Thus, rotation around a fixed axis as enforced by the rotation method leads to an increase of the path length through the Ewald sphere by a factor 1/ZETA. ZETA is the cosine of the angle between virtual and actual rotation axes and is closely related to the reciprocal Lorentz factor. For reflections near the 'blind region' close to the actual rotation axis, ZETA will become very small. This leads to excessively large and thereby inaccurate correction factors for the integrated intensity of such a reflection. The user can exclude these reflections by selecting a suitable lower bound for ZETA; the default is MINIMUM_ZETA=0.10 allowing reflections quite close to the spindle axis. The parameter is ignored For still snapshots.

Example:
MINIMUM_ZETA= 0.15
The possibility to increase (modify) this parameter value might be useful for repeating the CORRECT step. Compared to the default value this choice will lead to a less complete data set by omitting more unreliable reflections close to the 'blind region'.

Parameter is used by INTEGRATE, CORRECT (or nXSCALE)
 


DIRECTION_OF_DETECTOR_X-AXIS=
DIRECTION_OF_DETECTOR_Y-AXIS=
ORGX=
ORGY=
DETECTOR_DISTANCE=

These parameters are used to specify origin and orientation of the detector system with respect to the laboratory coordinate system.
Orientation of the detector is defined by the first two parameters: two orthogonal vectors that - together with their cross product - define a rotation matrix ED.
DIRECTION_OF_DETECTOR_X-AXIS=ED(1,1) ED(2,1) ED(3,1)
DIRECTION_OF_DETECTOR_Y-AXIS=ED(1,2) ED(2,2) ED(3,2)
ED(:,3)=ED(:,1) X ED(:,2)
These 3 vectors, {ED(:,1), ED(:,2), ED(:,3)}, form the right-handed orthonormal detector system. It serves as a reference frame for the specification of the arrangement of the detector components (segments) which makes the description invariant to movements of the instrument.

Origin of the detector system, fixed at 0 0 0 in the instrument, is specified (mm) in the laboratory system by the vector
-ORGX*QX*ED(:,1)-ORGY*QY*ED(:,2)+F*ED(:,3)
using conversion factors QX QY. This parametrization is used for reasons of compatibility with older versions of XDS (before March 30, 2013).
NOTE, that the parameter value DETECTOR_DISTANCE=F will be negative if ED(:,3) points towards the crystal. Also, F=0 is well possible as for the PILATUS-12M detector with its 120 x-ray recording segments arranged in a cylindrical way.

The origin vector is a refinable parameter if requested by the keywords POSITION in the parameters REFINE(IDXREF)= or POSTREFINE=. This type of refinement treats the detector as a rigid body.

Default values for the above parameters are provided by the nXDS.INP templates for most of the detectors. For the SIEMENS detector, or other detectors that can be rotated out, the situation requires a more detailed discussion (see COORDINATE SYSTEMS).

Example:
NX=1200 NY=1200 QX=0.15 QY=0.15
DIRECTION_OF_DETECTOR_X-AXIS= 1.0 0.0 0.0
DIRECTION_OF_DETECTOR_Y-AXIS= 0.0 1.0 0.0
ORGX= 605.0 ORGY= 592.0 DETECTOR_DISTANCE= 330.1
This is a typical description for an old MAR-scanner consisting of a single segment of NX=1200 "fast" and NY=1200 "slow" pixels with a pixel size of QX= QY=0.15 mm. By default, the single segment coincides with the detector plane at the same origin with the "fast" pixel direction along the detector x-axis. The scanner is aligned with the detector coordinate system coinciding with the laboratory system. The incident beam runs approximately along the laboratory z-axis intersecting the detector plane at its center at a distance of F=+330.1 mm. Note the positive sign because the detector normal points away from the crystal. A pixel at IX,IY on the detector (found at address IX+NX*(IY-1) in the data image file) has the laboratory coordinates
x=QX*(IX-ORGX)*ED(1,1)+QY*(IY-ORGY)*ED(1,2)+F*ED(1,3)
y=QX*(IX-ORGX)*ED(2,1)+QY*(IY-ORGY)*ED(2,2)+F*ED(2,3)
z=QX*(IX-ORGX)*ED(3,1)+QY*(IY-ORGY)*ED(3,2)+F*ED(3,3)

Parameters are used by XYCORR, IDXREF
 


SEGMENT=
REFINE_SEGMENT=
DIRECTION_OF_SEGMENT_X-AXIS=
DIRECTION_OF_SEGMENT_Y-AXIS=
SEGMENT_ORGX=
SEGMENT_ORGY=
SEGMENT_DISTANCE=

A detector is considered to consist of one or several rectangular segments at some arbitrary but fixed arrangement with respect to the detector system. Each segment is specified by the above set of seven parameters.

The above parameters are sufficient to find the coordinates (mm) of a segment pixel at IX,IY in the detector system.
x=QX*(IX-ORGXS)*EDS(1,1)+QY*(IY-ORGYS)*EDS(1,2)+FS*EDS(1,3)
y=QX*(IX-ORGXS)*EDS(2,1)+QY*(IY-ORGYS)*EDS(2,2)+FS*EDS(2,3)
z=QX*(IX-ORGXS)*EDS(3,1)+QY*(IY-ORGYS)*EDS(3,2)+FS*EDS(3,3)

Each segment of the detector is specified by its own set of 7 parameters. This way quite sophisticated instruments, like the cylindrical detector at the long-wavelength beam line at DIAMOND, can be handled by nXDS.
For single-segment detectors, all of the above 7 segment parameters can be omitted from nXDS.INP because the segment coordinate system is identical with the detector system by default.

Example:
NX=1200 NY=1200 QX=0.15 QY=0.15
DIRECTION_OF_DETECTOR_X-AXIS= 1.0 0.0 0.0
DIRECTION_OF_DETECTOR_Y-AXIS= 0.0 1.0 0.0
ORGX= 605.0 ORGY= 592.0 DETECTOR_DISTANCE= 330.1
SEGMENT=1 1200 1 1200
REFINE_SEGMENT=
DIRECTION_OF_SEGMENT_X-AXIS= 1.0 0.0 0.0
DIRECTION_OF_SEGMENT_Y-AXIS= 0.0 1.0 0.0
SEGMENT_ORGX=0.0
SEGMENT_ORGY=0.0
SEGMENT_DISTANCE=0.0
This is a typical description for an old MAR-scanner consisting of a single segment of NX=1200 "fast" and NY=1200 "slow" pixels with a pixel size of QX= QY=0.15 mm. Note that the segment coordinate system is identical with the detector system so that the "fast" pixels run along the detector x-axis and the "slow" pixels along the detector y-axis. The parameters specifying segment values are default and could have been omitted from nXDS.INP.

Parameters are used by XYCORR, POWDER, IDXREF, nXSCALE
 


ROTATION_AXIS=

Direction cosines of the rotation axis with respect to the laboratory system. The length of this vector will be normalized by nXDS. The direction of the axis is chosen to describe a right-handed rotation. A parameter value is provided by the nXDS.INP template for a typical beam-line setup for the detector used.
For 'still' images the direction cosines are all set to zero indicating that the concept of a rotation axis has no meaning in this case.

Rotation axis and oscillation range must be the same for all images in the data set. Thus, images collected with different rotation axes or oscillation ranges ('stills') must be processed separately. The results obtained after the INTEGRATE step can be combined by nXSCALE.

Example:ROTATION_AXIS= 0.0 1.0 0.0
The rotation axis points along the laboratory y-axis. When looking along the axis, the crystal would rotate clockwise when proceeding to the next data image.

Parameter is used by IDXREF, INTEGRATE
 


OSCILLATION_RANGE=

Oscillation range of each data image in degrees (≥0). nXDS assumes a right handed rotation of the crystal about the rotation axis when proceeding to the next data image. No sensible default value can be provided and the user must insert the correct value. For 'still' images this value is zero.
For detectors with no read-out noise like the PILATUS an optimal choice for the oscillation range would match half of the crystal's mosaicity (defined as the standard deviation of the reflecting range). A further reduction of the oscillation range could lead to problems in the accurate determination of extremely low background and unreliably processed data.

Rotation axis and oscillation range must be the same for all images in the data set. Thus, images collected with different rotation axes or oscillation ranges ('stills') must be processed separately. The results obtained after the INTEGRATE step can be combined by nXSCALE.

Example: OSCILLATION_RANGE=0.1
This describes a "fine-sliced" data set with each image covering an oscillation range of 0.1 °.

Example: OSCILLATION_RANGE=0.0
All data are 'still' images.

Parameter is used by IDXREF
 


X-RAY_WAVELENGTH=

X-ray wavelength of the incident beam (Å). There is no default value and the user must insert the correct value. All images of the data set should have been collected at approximately the same wavelength.

Example: X-RAY_WAVELENGTH=0.92
A synchrotron data set collected at wavelength 0.92 Å.

Parameter is used by IDXREF
 


INCIDENT_BEAM_DIRECTION=
POWDER_CENTER_CORRECTION=

The first parameter specifies the incident beam direction S0(:) by its x, y, z components with respect to the laboratory coordinate system. The incident beam direction points from the source towards the crystal and is normalized by nXDS. The incident beam should approximately point in the same direction for all exposures of the data set.

The second (optional) parameter specifies a correction to the center of concentric powder circles displayed in the control image POWDER.cbf generated by the POWDER step. Deviations of the powder center from the image center are interpreted as an error in the specification for the origin of the detector coordinate system (ORGX=, ORGY=). From the three numbers dx, dy, q (default 0.0 0.0 0.001) for this parameter (POWDER_CENTER_CORRECTION=dx dy q) a vector pointing to the center of the powder rings is constructed as S0'(:) = S0(:) + dx·q d1'(:) + dy·q d2'(:). The right-handed orthonormal system {d1'(:), d2'(:), S0(:)} is constructed from the incident beam wave vector S0(:) by some well-defined procedure.

In the POWDER step of nXDS a control image POWDER.cbf is generated spanning the d1', d2' plane perpendicular to the beam vector S0(:). The image consists of 1024 × 1024 square pixels of side length q (radians). The image center is marked by crosshairs (mouse coordinates 511, 511). The observed scattering vectors from all data images are marked in POWDER.cbf, where they form a set of concentric rings - the powder pattern - in the ideal case. The center of the pattern can be determined by the user (with the xds-viewer graphics program). Often this center is found offset from its ideal place at the image center marked by crosshairs (511, 511). This offset can be interpreted to result from an incorrect value for the origin of the detector coordinate system (ORGX=, ORGY=). The corrected origin is printed by POWDER.LP. For further processing with nXDS you should then specify in nXDS.INP the new values for ORGX=, ORGY= and turn off the parameter or set POWDER_CENTER_CORRECTION= 0 0 0.001

Example:
INCIDENT_BEAM_DIRECTION=0.0 0.0 1.0
POWDER_CENTER_CORRECTION=-5.0 0.6 0.001
The incident beam direction points along the laboratory z-axis. The center of the concentric set of circles was found with the interactive graphics program xds-viewer at cursor position x=506.0, y=511.6 in the plane of the powder image POWDER.cbf. The image was calculated with a square pixel raster of q=0.001. This leads to the above correction value.

Parameters are used by POWDER, IDXREF
 


FRACTION_OF_POLARIZATION=

Fraction of polarization of direct beam in a plane specified by its normal. (0 < FRACTION_OF_POLARIZATION < 1). The same polarization will be applied to all exposures of the data set.

Example: FRACTION_OF_POLARIZATION=0.9
A typical parameter value for data collection at a synchrotron. In case you want to try out different values, all you have to do is to repeat the CORRECT step of nXDS (JOB=CORRECT) with the chosen parameter values.

Parameter is used by INTEGRATE, CORRECT, nXSCALE
 


POLARIZATION_PLANE_NORMAL=

x, y, z components of the polarization plane normal with respect to the laboratory coordinate system.

For an unpolarized beam hitting the crystal:
FRACTION_OF_POLARIZATION=0.5
POLARIZATION_PLANE_NORMAL= 0 0 0 ! any arbitrary vector

For a monochromator with incident unpolarized beam:
FRACTION_OF_POLARIZATION=[cos(2*thetaM)]**2/[1+(cos(2*thetaM))**2]
POLARIZATION_PLANE_NORMAL= components of the monochromator diffraction plane normal.

Example:
POLARIZATION_PLANE_NORMAL= 0.0 1.0 0.0
FRACTION_OF_POLARIZATION=0.9
The electrical field vector of the incident beam is found in the x,z-plane of the laboratory coordinate system with a probability of 0.9.

Parameter is used by INTEGRATE, CORRECT, nXSCALE
 


SPACE_GROUP_NUMBER=

Space-group number of the crystal. The numbers corresponding to each possible space group are defined in the "INTERNATIONAL TABLES I". All 230 space groups are implemented. From the space group number and the unit cell parameters nXDS provides a standard set of symmetry operators.

Omission of the parameter or a value of zero indicates that space group and cell parameters are unknown. nXDS will try to find a reduced cell (step "IDXREF") from the given spot list and continue in the triclinic space group P1.

Example: SPACE_GROUP_NUMBER=77
This specifies the tetragonal space group P42

Parameter is used by IDXREF, INTEGRATE, CORRECT, nXSCALE
 


UNIT_CELL_CONSTANTS=

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. The cell parameters will be ignored for an unknown space group.

Example:
UNIT_CELL_CONSTANTS=125.9 125.9 144.7 90.0 90 90
SPACE_GROUP_NUMBER=77
This specifies the cell constants of a tetragonal crystal obeying P42 space group symmetry. Note that the a and b axes must have identical length and all angles must be exactly 90 ° as required by the space group.

Parameter is used by IDXREF, CORRECT, nXSCALE
 


MAX_CELL_AXIS_ERROR=
MAX_CELL_ANGLE_ERROR=

These two decision constants are used for detection of lattice symmetry. They set an upper limit on the deviations between the unconstraint unit cell parameters and their closest approximation satisfying a proposed lattice symmetry. If the deviations exceed one or both limits nXDS assumes that the crystal does not possess the tested lattice symmetry. The angle error is specified in degrees.

Example: MAX_CELL_AXIS_ERROR=0.03 MAX_CELL_ANGLE_ERROR=2.0
These are the default values for the parameters. Thus, for an observed set of cell parameters like a=65.3 b=66.0 c=180.4 α=90.1 β=89.5 γ=119.3, we cannot reject the hypothesis that the lattice could be hexagonal because max{|a-(a+b)/2|,|b-(a+b)/2}<0.03*(a+b)/2 and max{|α-90|,|β-90|,|γ-120|}<2.

Parameters are used by IDXREF, CORRECT, nXSCALE

 


NBX=
NBY=

The box of size (2*NBX+1)*(2*NBY+1) is centered in succession at each pixel of the images specified for background determination and the pixel variation within the box is determined. The results are used to estimate the expected variation in a data image in the absence of any spot and saved in the look-up table GAIN.cbf. The comparison between the observed and expected pixel variation serves to distinguish "strong" from background pixels.
The parameters NBX=, NBY= are also used in the COLSPOT step for identification of strong pixels in each data image.

Example: NBX=3 NBY=3
These are the default values for the parameters.

Parameters are used by FILTER, INIT, COLSPOT

 


BACKGROUND_PIXEL=

An image pixel belongs to the background region if the variation in the pixel contents of neighbouring pixels (region defined by NBX= and NBY=) does not exceed the specified number of standard deviations. Background pixels are not included in the localization of strong spots by COLSPOT and are not used for calculating Bragg-peak centroids in the INTEGRATE step.

Example: BACKGROUND_PIXEL=6.0
This is the default value for the parameter. The pixel at IX, IY is in the background region, if the variation in contents of pixels within the region IX-NBX,IX+NBX; IY-NBY,IY+NBY does not exceed the expected variation by more than a factor of 6.

Parameter is used by INTEGRATE
 


STRONG_PIXEL=

This parameter value is used to identify STRONG pixels in a data image. Mean and e.s.d. of the background area (defined by the parameters NBX= and NBY=) around the central pixel are used to compute a standardized random variable from the pixel value. The central pixel is STRONG if this random variable exceeds the specified value of STRONG_PIXEL=.

Example: STRONG_PIXEL=5.0
The default value is 5.0 for the parameter. If c is the value of the central pixel and b,e are mean and standard error of the background, the pixel is STRONG if (c-b)/e > 5.0

Parameter is used by COLSPOT
 


MINIMUM_NUMBER_OF_PIXELS_IN_A_SPOT=

This allows to suppress spurious, isolated 'strong' pixels from entering the spot list generated by "COLSPOT". The default value is 1 which is fine for sharp spots. However, it is recommended to look at a typical data image for finding a suitable value.

Example: MINIMUM_NUMBER_OF_PIXELS_IN_A_SPOT=6
This accepts broader spots only.

Parameter is used by COLSPOT, INTEGRATE
 


SPOT_MAXIMUM-CENTROID=

This parameter serves to eliminate spots whose location of the maximum deviates by more than the specified parameter value from the centroid of the spot (pixel units).

Example: SPOT_MAXIMUM-CENTROID=2.0
This is the default value for the parameter.

Parameter is used by COLSPOT
 


SIGNAL_PIXEL=

The pixel contents must exceed the background by more than the specified value of standard deviations to be included in the calculation of the Bragg-peak centroid.

Example: SIGNAL_PIXEL=3.0
This is the default value for the parameter.

Parameter is used by INTEGRATE
 


MINIMUM_NUMBER_OF_SPOTS=

This parameter serves to ignore images containing an insufficient number of strong spots.

Example: MINIMUM_NUMBER_OF_SPOTS=30
This is the default value for the parameter. Images containing less than 30 spots are excluded from further processing.

Parameter is used by COLSPOT
 


MAXIMUM_NUMBER_OF_SPOTS=

This parameter sets an upper limit for the number of accepted strong spots.

Example: MAXIMUM_NUMBER_OF_SPOTS=1000
This is the default value for the parameter. Up to 1000 of the strongest spots located in an image are accepted and used in subsequent processing steps.

Parameter is used by COLSPOT
 


INDEX_ERROR=

Maximum allowed deviation from 'integerness' of computed indices of a reflection. This parameter corresponds to ε in reference Kabsch, 1993.

Example: INDEX_ERROR=0.10
This is the default value for the parameter. The default value works fine and hardly needs to be changed.

Parameter is used by IDXREF
 


INDEX_MAGNITUDE=

Maximum magnitude of index differences between reflections. This parameter corresponds to δ in Kabsch, 1993.

Example: INDEX_MAGNITUDE=8
This is the default value for the parameter. Larger values could increase the risk of misindexing.

Parameter is used by IDXREF
 


INDEX_QUALITY=

Minimum quality of indices required for a reflection to be included in the shortest tree.

The 3 parameters INDEX_ERROR=, INDEX_MAGNITUDE=, and INDEX_QUALITY= are used to control the local indexing of reflections by the shortest tree algorithm (Kabsch, 1988b). Computed reflection indices deviating from integers by more than INDEX_ERROR= or indices of an absolute value larger than INDEX_MAGNITUDE= are given a penalty which lowers their index quality. Reflections are connected by a shortest tree. This tree is split into subtrees by removing unreliable connections with a value less than INDEX_QUALITY= (a number between 0 ... 1).

Example: INDEX_QUALITY=0.7
This is the default value for the parameter. The default value works fine and hardly needs to be changed.

Parameter is used by IDXREF
 


RGRID=
SEPMIN=
CLUSTER_RADIUS=
MAXIMUM_NUMBER_OF_DIFFERENCE_VECTOR_CLUSTERS=
INTEGER_ERROR=
MERGE_TREE=

Parameters are used by IDXREF
 


NUMBER_OF_TESTED_BASIS_ORIENTATIONS=

Number of uniformly distributed orientations of the basis that are to be tested to explain the observed diffraction spots. This implies that the cell constants are specified in nXDS.INP.

Example: NUMBER_OF_TESTED_BASIS_ORIENTATIONS=1000000
This is the default value for the parameter. A larger value could be used to prevent missing the correct unit cell orientation in the search.

Parameter is used by IDXREF
 


MAXIMUM_ERROR_OF_SPOT_POSITION=

Maximum acceptable deviation (pixel units) between observed and calculated location of a diffraction peak. Reflections that do not satisfy this condition are excluded from the refinements.

Example: MAXIMUM_ERROR_OF_SPOT_POSITION=3.0
This is the default value for the parameter. The default value works fine and hardly needs to be changed.

Parameter is used by IDXREF, INTEGRATE
 


MINIMUM_FRACTION_OF_INDEXED_SPOTS=

This parameter is a lower limit for the fraction of indexed spots compared to the total number of observed spots. The IDXREF step is considered successfully completed if more than the required minimum of spots are assigned indices.

Example: MINIMUM_FRACTION_OF_INDEXED_SPOTS=0.40
At least 40% of the given spots must be indexed (explained) by IDXREF. This is the default value for the parameter. The default value works fine and hardly needs to be changed.

Parameter is used by IDXREF
 


REFINE(IDXREF)=

The parameter value can be ALL (default) or any combination of the following KEYWORDS in arbitrary order.

If ALL is specified or the parameter is commented out, detector origin, beam direction, unit cell orientation and cell constants will be refined in the IDXREF step of nXDS. The direction of the rotation axis is not refined, however, because the diffraction spots given to IDXREF all come from a single rotation or 'still' image.

The refined diffraction parameters are saved in file XPARM.nXDS.

Example: REFINE(IDXREF)=BEAM ORIENTATION CELL
This means that incident beam direction, unit cell orientation and cell constants, but not the detector distance, will be refined during the IDXREF step.

Parameter is used by IDXREF, INTEGRATE
 


REFLECTING_RANGE_E.S.D.=

denotes the standard deviation (1/Å) of a Gaussian modeling the rocking curve. This curve describes the intensity decline of a spot as a function of its distance (1/Å) from the Ewald sphere. The standard deviation depends on the resolution of the reciprocal lattice point (corresponding to the observed spot) and is described by two parameters as a linear function of the length (1/Å) of the reciprocal lattice point. The finite width of the rocking curve results from imperfections in the crystal which is built up from mosaic blocks and their angular spread (Nave, 1998).

If the parameter REFLECTING_RANGE_E.S.D.= is left unspecified by the user, the value will be determined automatically from the data images. This assumes that the observed spots in the data image sample the full range of the rocking curve with each spot deviating by not more than two e.s.d. from its closest position on the Ewald sphere (Sauter et al., 2014).

Example: REFLECTING_RANGE_E.S.D.=3.0E-04 1.5E-04
For a reflection at 3Å resolution the standard deviation of its rocking curve through the Ewald sphere would thus be (3+1.5/3)*0.0001=0.00035/Å.

Parameter is determined by INTEGRATE and refined by CORRECT, nXSCALE
 


BEAM_DIVERGENCE=

This value is approximately arctan(spot diameter/DETECTOR_DISTANCE) and must be specified in degrees. A slightly larger value should be given to include some background pixels around each spot. To compute the spot diameter you need the pixel lengths (QX=, QY=) in mm which are listed in the Table of supported detectors. The parameter value defines the raster size along alpha/beta of the reflection profiles.

If any of the parameters BEAM_DIVERGENCE= or BEAM_DIVERGENCE_E.S.D.= is left unspecified by the user, these values will be determined automatically from the data images.

Example: BEAM_DIVERGENCE=0.10
The value defines the solid angle of a diffraction spot in degrees.

Parameter is used by INTEGRATE
 


BEAM_DIVERGENCE_E.S.D.=

Defines the standard deviation of BEAM_DIVERGENCE=.

Example: BEAM_DIVERGENCE_E.S.D.=0.025

Parameter is used by INTEGRATE
 


MINIMUM_EWALD_OFFSET_CORRECTION=

Lowest allowed relative intensity loss compared with the ideal case that the Bragg peak of the reflection would occur at the center of the oscillation range.

Example: MINIMUM_EWALD_OFFSET_CORRECTION=0.2
This is the default value. Reflections from INTEGRATE.HKL are accepted by the CORRECT step of nXDS or by nXSCALE only if their intensities are at least 20% of the expected value if they were recorded at the center of the oscillation range.

Parameter is used by CORRECT, nXSCALE
 


NUMBER_OF_PROFILE_GRID_POINTS_ALONG_ALPHA/BETA=

This parameter value defines the number of sampling points used for representing reflection profiles in a plane tangential to the Ewald sphere centered at the diffracted beam wave vector. It must be an odd value <22 (for details see Kabsch, 1988b).

Example: NUMBER_OF_PROFILE_GRID_POINTS_ALONG_ALPHA/BETA=9
This is the default value. Each reflection when mapped to the surface of the Ewald sphere is sampled by 9 x 9 raster points in the plane tangential to the sphere.

Parameter is used by INTEGRATE
 


CUT=

Cut-off value defining the integration region in the learned reflection profiles. The size of the integration region is critical: Background noise will be added to the reflection intensities if this region is too large (decreasing CUT=); incomplete integration if the integration region is chosen too small (increasing CUT=).

Example:  CUT=2.0
This is the default value. Grid points in the reflection profile less than 2% of the maximum are not used for integration.

Parameter is used by INTEGRATE
 


MINPK=

Defines the minimum required percentage of observed reflection intensity. The missing intensity is estimated from the learned profiles. If less than MINPK % is observed, the reflection will be discarded.

Example:  MINPK=75.0
The default value of 75% works fine and hardly needs to be changed.

Parameter is used by INTEGRATE
 


PROFILE_FITTING=

This parameter selects the integration method for reflection intensity. The default value is FALSE. This means that integration is carried out by straight summation from pixels (after background subtraction) contributing to the expected peak region. The expected shape is obtained by superposition of strong spots.
Alternatively, integration can be carried out by profile fitting (TRUE) of the background subtracted pixel counts with the expected profile shape. This method is not recommended because it could lead to systematic differences compared to straight summation.

Example:  PROFILE_FITTING=FALSE
This is the default and avoids a possible bias from the details of the learned profile.

Parameter is used by INTEGRATE
 


FRIEDEL'S_LAW=

This parameter is IGNORED since VERSION Feb 14, 2019.
nXDS/nXSCALE save Friedel pairs as separate reflections on their output reflection files. In contrast, the item COMPLETE as printed in the summary table in CORRECT and nXSCALE considers Friedel pairs as equivalent.  


LONG_OUTPUT_FILE=

Name of an optional reflection output file which contains the result of data processing by nXDS in detail, namely the corrected intensities of all reflections recorded in the data images. The file could become potentially very large and is generated only if explicitly requested by the user specifying a non-blank file name for the input parameter, like LONG_OUTPUT_FILE=nXDS_long.HKL. The name was chosen in the example to avoid name clashes with other files generated by this processing. For a detailed description of the file format, see nXDS_long.HKL

Parameter is used by CORRECT, nXSCALE
 


REFERENCE_DATA_SET=

You may specify here the file name of previously measured data from the same crystal form. The reference data set should be of type XDS_ASCII with indices in harmony with the input parameters SPACE_GROUP_NUMBER=, UNIT_CELL_CONSTANTS=. If the data cannot be read successfully, it is assumed that a reference is unavailable.
The reference is used by CORRECT and nXSCALE for local scaling and comparison with the current data set. In case of setting ambiguities the reference data are often used for selecting the best fitting one.
Upon request (USE_REFERENCE_IN_POSTREFINEMENT=) the external reference data set could also serve as a refinement target in the post-refinement in the CORRECT step or in nXSCALE.

Example: REFERENCE_DATA_SET= ../nXDS_ASCII_native.HKL
The file name of a reference data set.

Parameter is used by CORRECT, nXSCALE
 


POSTREFINE=

The parameter value can be empty or any combination of the following KEYWORDS in arbitrary order.

If the parameter POSTREFINE= is specified without any of the keywords above (empty), no post refinements will be carried out. If the parameter POSTREFINE= is omitted, a default POSTREFINE= SKALA is assumed.

Unfortunately there is no stable method available for simultaneous refinement of all parameters in general. For this reason post refinements can be carried out sequentially under control of the user by specification of several POSTREFINE= parameter values that are tailored to the collected data. The parameters are chosen that yield convergence of the procedure.

Example
POSTREFINE= SKALA BEAM CELL
POSTREFINE= SKALA POSITION
POSTREFINE= SKALA ORIENTATION
POSTREFINE= SKALA MOSAICITY
The specified parameters are refined in four rounds. Information about convergence of the refinements is provided by the values of the convergence indicator MAXGRAD printed in CORRECT.LP or nXSCALE.LP. Refinement is considered successful if MAXGRAD ≤ 0.001. The appropriate combination of keywords can be found by repeating just the CORRECT or nXSCALE step.

Parameter is used by CORRECT, nXSCALE
 


USE_REFERENCE_IN_POSTREFINEMENT=

The parameter value can be TRUE or FALSE. The default is FALSE. The name of the external data set is specified by the input parameter REFERENCE_DATA_SET=. The external data should be nearly complete as they serve as a refinement target for the reflection intensities obtained from the snapshot images being processed here.
If a suitable external reference data set is unavailable or not wanted nXDS generates it from the processed snapshots in a cyclic way.

Example: USE_REFERENCE_IN_POSTREFINEMENT= TRUE
An external data set is available from the same type of crystals.

Parameter is used by CORRECT, nXSCALE
 


DEFAULT_REFINE_SEGMENT=

This parameter defines the default value of the parameter REFINE_SEGMENT=. Possible values can be DEFAULT_REFINE_SEGMENT= POSITION | ORIENTATION
If omitted, DEFAULT_REFINE_SEGMENT=! is assumed and segment refinements will not be carried out unless explicitly requested by REFINE_SEGMENT=.

Example:
The example below shows the specification of 3 detector segments and how their exact assembly with respect to the detector system can be refined - assuming there are at least 300 observed spots recorded by each segment.
segment 1 : refined parameter POSITION ORIENTATION, from default
segment 2 : refined parameter POSITION, explicitly requested
segment 3 : no parameter will be refined

MINIMUM_NUMBER_OF_REFLECTIONS/SEGMENT=300
DEFAULT_REFINE_SEGMENT=POSITION ORIENTATION

 SEGMENT= 1483 1969 4453 4647
 SEGMENT_ORGX= 1231.5
 SEGMENT_ORGY= 4549.5
 SEGMENT_DISTANCE= 250.0
 DIRECTION_OF_SEGMENT_X-AXIS= 1.0000000 0.0000000 0.0000000
 DIRECTION_OF_SEGMENT_Y-AXIS= 0.0000000 0.2246721 -0.9744344

 SEGMENT= 1977 2463 4453 4647
 REFINE_SEGMENT=POSITION!ORIENTATION
 SEGMENT_ORGX= 1231.5
 SEGMENT_ORGY= 4549.5
 SEGMENT_DISTANCE= 250.0
 DIRECTION_OF_SEGMENT_X-AXIS= 1.0000000 0.0000000 0.0000000
 DIRECTION_OF_SEGMENT_Y-AXIS= 0.0000000 0.2246721 -0.9744344

 SEGMENT= 1 487 4665 4859
 REFINE_SEGMENT=!POSITION!ORIENTATION
 SEGMENT_ORGX= 1231.5
 SEGMENT_ORGY= 4761.5
 SEGMENT_DISTANCE= 250.0
 DIRECTION_OF_SEGMENT_X-AXIS= 1.0000000 0.0000000 0.0000000
 DIRECTION_OF_SEGMENT_Y-AXIS= 0.0000000 0.0808889 -0.9967231

Parameter is used by CORRECT, nXSCALE
 


MINIMUM_NUMBER_OF_REFLECTIONS/SEGMENT=

The parameter specifies the minimum number of strong reflections recorded by a segment required for refinement of its position and orientation with respect to the detector instrument. Default value is 200.

Example: MINIMUM_NUMBER_OF_REFLECTIONS/SEGMENT=50
Segments containing less than 50 reflections are excluded from refinements of their assembly parameters.

Parameter is used by CORRECT, nXSCALE
 


MERGE= (obsolete!)

This parameter is IGNORED since VERSION Feb 14, 2019.  


REJECT_ALIEN=

This parameter is used to mark extraordinarily strong reflections (by a negative standard deviation of its intensity) in the output file nXDS_ASCII.HKL. Such "alien" reflections do not obey Wilson's statistic and often arise from ice rings in the data images. They are listed near the end in the file CORRECT.LP. "Aliens" with a Z-score above the parameter value are excluded from further processing.

Example:  REJECT_ALIEN=20.0
"Aliens" with a Z-score above 20.0 are marked by a negative Sigma(I) and are thus excluded from further processing (by XSCALE and XDSCONV). This is the default value.

Parameter is used by CORRECT, nXSCALE
 


AIR=

Fraction of intensity loss per mm due to air absorption. Each reflection intensity is multiplied by exp(|AIR*F*(1/cos(oblique angle)-1)|). The oblique angle is between the diffracted beam and the detector normal and assumes values 0...<90 degrees.

The absorption of x-rays by air depends on the wavelength; nXDS will provide the appropriate value unless specified by the user. A negative value given by the user is ignored and the parameter is treated as unspecified.

Example: !AIR=0.001
nXDS will compute the correct value for the specified x-ray wavelength since no value was given by the user. This is the recommended procedure. Uncommenting this parameter (by removal of the exclamation mark in this example) would enforce nXDS to use the value 0.001.

Parameter is used by INTEGRATE, CORRECT, nXSCALE
 


OUTPUT_FILE=

Mandatory name of the output file containing the fully corrected integrated intensities after scaling/postrefinement several input streams of snapshots (type INTEGRATE.HKL) with nXSCALE. The case of a single input stream is handled by the CORRECT step of nXDS resulting in an output file with the predefined name XDS_ASCII.HKL.

Example: OUTPUT_FILE=Lys1-2_XDS_ASCII.HKL
A possible file name of the output file of type XDS_ASCII.HKL obtained from 2 input streams of snapshots (type INTEGRATE.HKL) after scaling/postrefinement with nXSCALE.

Parameter is used by nXSCALE
 


INPUT_FILE=

In case of several streams of snapshot images to be scaled/corrected by nXSCALE the stream names are specified by repeated use of the INPUT_FILE= parameter. The case of a single input stream is handled by nXDS and has a fixed predefined name which is always INTEGRATE.HKL.

Example:
OUTPUT_FILE=Lys1-2_XDS_ASCII.HKL
INPUT_FILE=../Lys1/INTEGRATE.HKL
INPUT_FILE=../Lys2/INTEGRATE.HKL
Two input streams of snapshots, namely ../Lys1/INTEGRATE.HKL and ../Lys2/INTEGRATE.HKL, are to be scaled and corrected by nXSCALE resulting in the output file, called Lys1-2_XDS_ASCII.HKL, containing fully corrected integrated intensities.

Parameter is used by nXSCALE
 


.

© 2017-2022, MPI for Medical Research, Heidelberg      Imprint Datenschutzhinweis.
Wolfgang.Kabsch@mpimf-heidelberg.mpg.de
page last updated: Sep 5, 2023