Increments batch numbers by a constant to every batch from this point on until another ADD command is read. Useful to make unique batch numbers from two or more files which have the same batch numbers inside. For example, DENZO_york1 FORMAT embeds the batch number in the .x file.
| format | ADD value |
| default | nothing added |
| example | ADD 1000 This will add 1000 to each batch number. |
Tells the program to add partially recorded reflections among consecutive batches, even if the batches do not have consecutive numbering. Essentially obligatory in today's crystallography with image plates.
| modifier | all | .(Partials are added over all consecutive batches.) |
| format | ADD PARTIALS start1 to end1 start2 to end2 ... etc. |
| default | do not ADD PARTIALS |
| example | ADD PARTIALS 0 to 49 51 to 99 100 to 149 |
Flag for keeping Bijvoets (I+ and I-) separate in OUTPUT FILE. If the ANOMALOUS flag is on, anomalous pairs are considered equivalent when calculating scale and B factors and when computing statistics, but are merged separately and output as I+ and I- for each reflection.
| format | ANOMALOUS |
| default | not turned on (I+ and I- are combined) |
| example | ANOMALOUS |
Can be used to restrain B factor differences from consecutive films or batches. The value which follows the flag represents the amount in Å2 you will allow the B's to differ from consecutive frames or batches. The earlier edition of this manual stated that this was an obsolete option. This is no longer the case. It has been resurrected. See also the keyword SCALE RESTRAIN.
| format | B RESTRAIN value |
| default | not turned on |
| example | B RESTRAIN 0.5 |
The BACKGROUND CORRECTION command specifies amount per frame to increase background. Corrects for errors in Hamlin data integration in the software distributed in the late 1980's and early 1990's. The value given after the keyword increases the background by #counts/frame. Valid only for ARCHIVE file format only.
| format | BACKGROUND CORRECTION value |
| default | not turned on |
| example | BACKGROUND CORRECTION 15 |
Overall B used only in the absence of an INITIAL B FACTOR. You can apply a higher value to lower your r-merge. Does not affect the quality of the data.
| format | DEFAULT B FACTOR value_(#counts/frame) |
| default | 0 |
| example | DEFAULT B FACTOR 5 |
Overall scale factor used in the absence of an INITIAL SCALE factor. This is useful if the data are too strong, which is sometimes the case with small molecules. It will reduce the output intensities by the factor entered.
| format | DEFAULT SCALE value |
| default | 1 |
| example | DEFAULT SCALE 10 |
Turns off the reject outliers flag.
| format | DO NOT REJECT OUTLIERS |
| default | this is the default (outliers not rejected automatically, but see REJECT OUTLIERS for more discussion.) |
| example |
Provides a logical end for the FIT command. At the moment this has no effect, but may be implemented in future versions of the program.
This is a single multiplicative factor which is applied to the input sigma(I)'s. This should be adjusted so the normal [[chi]]2 (goodness of fit) value that is printed in the final table of the output comes close to 1. By default the input errors are used (ERROR SCALE FACTOR = 1.) It applies to the data which are read after this keyword, so you can apply different ERROR SCALE FACTOR to subsequent batches by repeating this input with different values.
| format | ERROR SCALE FACTOR value |
| default | ERROR SCALE FACTOR 1 |
| example | ERROR SCALE FACTOR 1.3 (good starting value for FORMAT DENZO_ip) |
Estimate of the systematic error for each of the resolution shells. There must be exactly the same number of error estimates here as there are NUMBER OF ZONES. So if you have 10 zones, you need 10 numbers following the keyword estimated error: one for each zone. Note that the error estimates to do not all have to be the same.
The estimated error applies to the data which are read after this keyword, so you can apply different ERROR SCALE FACTOR to subsequent batches by repeating this input with different values. This is an important point if you enter data from a previous SCALEPACK output that does not need its sigmas to be increased.
The error estimates should be approximately equal to the R-factor in the table at the end of the output for resolution shells where statistical errors are small, namely the earlier resolution shells where the data is strong. This is a crude estimate of the systematic error, to be multiplied by I, and is usually invariant with resolution. Default = 0.06 (i.e. 6%) for all zones.
| format | ESTIMATED ERROR value1 value2 value3 value4 ...etc |
| default | each value set to 0.06 |
| example | ESTIMATED ERROR 0.02 0.03 0.03 0.03 0.04 0.04 (6 zones) |
Some partially recorded reflections may be predicted by DENZO or SCALEPACK to start or end their Bragg condition in between consecutive frames due to small variations in crystal orientation from frame to frame. For these reflections only, there are two choices of defining where the reflection started (or ended): including the extra frame, or not. The keyword EXTEND PARTIALS tells SCALEPACK to include this extra frame. This is not a significant keyword because it only affects a very small fraction of the reflections. Opposite of do not extend partials.
| format | EXTEND PARTIALS |
| default | this is the default |
| example |
This specifies the files read by SCALEPACK. The input has two components. The first is a number. The second is a file name, which usually contains wildcard characters (###) that are incremented by the SECTOR command. The number which follows the FILE keyword specifies the starting batch number. A batch, previously called a "film," can be as small as a single .x file (or the equivalent). It can be a group of .x files, even an entire data set. The most frequent content of a batch is a single .x file.
This conversion of files into batches is particularly useful if you want to scale more than one data set together. For example, let's say you want to scale 10 lysozyme oscillation frames (numbered 1 through 10) with 37 ribonuclease oscillation frames (numbered 1 through 37). The FILE statement will take each of the individual .x files and assign them a batch number. Thus, you would enter something like this: FILE 1 'lysoz###.x' for the lysozyme, and FILE 101 'ribo###.x' for the ribonuclease. Thus, the lysozyme .x files would have batch numbers 1 - 10 corresponding to files lysoz001.x, lysoz002.x, etc. (assuming you used the SECTOR 1 to 10 command above the file statement so that the wildcards would be substituted with numbers). The ribonuclease .x files would have batch numbers 101 - 137, corresponding to files ribo001.x, ribo002.x, etc. Note that the ### is replaced by the SECTOR argument, not by the batch number.
| format | FILE value 'filename' |
| default | both the number and the file name must be specified but read the note below. |
| example | FILE 101 '/frames/scale/lysoz###.x' |
Note that the file statement must come after FORMAT because the syntax depends on which input FORMAT is being read. The only exception to this is in the case of ARCHIVE, DENZO_york, and DENZO_york1, files, where the number after the word file is not given because the batch numbers are already stored in the file. If you want to change the batch numbers in these file formats, see the ADD command described above.
Tells the program what parameters to fit in postrefinement, and specifies the group of files over which the fitting is to be performed. Postrefinement fit can be applied to an entire set of batches (one batch being the entire set of frames, for example) using the modifier crystal, or to each individual input file using the modifier film or batch.
| modifiers | crystal | Specifies that the fit operation is over the entire set of frames specified by a range and restrains the fit parameter to have exactly the same value over this range. |
| film | Specifies that the fit operation is performed on each member of the set of frames specified by a range. | |
| batch | Alias for film. |
| parameters | a*, b*, c* | Unit cell lengths. Values returned are real space. |
| alpha*,beta*,gamma* | Unit cell angles. Values returned are real space. | |
|
rotx roty rotz |
crystal orientation parameters deduced in Denzo | |
| wavelength | Incident wavelength. Untested. | |
| mosaicity | Mosaicity as defined in DENZO, in degrees. | |
| formats | fit modifier parameter1 filmnumber to filmnumber | |
| default | the default is that nothing is fit unless specified | |
| examples | FIT crystal roty 1 to 137 | |
| FIT crystal mosaicity 1 to 5 7 to 10 102 to 104 to 137 | ||
| FIT film rotx 1 to 137 | ||
Most mistakes in SCALEPACK can be attributed to errors in these commands because the program is very sensitive to mistakes in the batch numbers you input. If you input non-existent batch numbers or define overlapping ranges (e.g. 1 to 10 5 to 20), the program is likely to fail in a strange way. Also, do not fit unit cell parameters restrained by space group symmetry. For example, if you have space group P3, you must not FIT B*. If you specify a range of numbers, the program will only use the batch numbers that exist within the range. For example, if your batch numbers go from 1 to 40 and 70 to 90, you can get away with saying, say, FIT batch (parameter) 1 to 90, which is the same as FIT batch (parameter) 1 to 40 70 to 90. For FIT crystal, these two inputs are not equivalent. In the case of FIT crystal (parameter) 1 to 90, one value will be FIT for all batches. In the case of FIT crystal (parameter) 1 to 40 70 to 90, two values will be fit, one for each range. Note that different parameters may be fit over different ranges and either over batch or crystal. You can also mix batch and crystal for the same parameters.
Do not FIT batch rotz because this parameter is very poorly defined by the intensities of observed partial reflections. This is another very common mistake. Also, unless you know what you are doing, do not FIT crystal rotx roty rotz, because if the spindle is even slightly misaligned, the assumption that there is only one crystal orientation parameter for a large sweep of data will force incorrect restraints on the crystal orientation refinement.
Note about fitting rotations: Changes in rotations, like crystal rotx roty and rotz, are expressed as small rotations, call them [[Delta]]'s, about the laboratory frame of reference. These [[Delta]]'s: [[Delta]]x, [[Delta]]y, and [[Delta]]z, are used because to a first approximation they commute with one another (commute means that the order in which they are applied is irrelevant). This in turn is because these [[Delta]]'s are small, typically less than one degree. The crystal or cassette rotations, Rx, Ry, and Rz, on the other hand, do not commute with one another because their values tend to be large (much greater than one degree). So when you ask SCALEPACK postrefinement or DENZO to "fit" these rotations, what is actually happening is that the [[Delta]]'s are being refined. After each refinement cycle, the [[Delta]]'s are converted into changes in Rx, Ry, and Rz by a (complicated) algebraic relation. Those of you with sharp eyes will have noticed in DENZO that the "shifts" reported by the program when fitting the crystal rotations do not correspond to the changes in the rot values. This is because the shifts reported are the [[Delta]]'s, not the changes in rotx, roty, and rotz. The other reason for fitting delta rotations the way they are defined in DENZO is to make them have a more intuitive correlation with the other parameters. Otherwise, changes in crystal rotz would not correlate with cassette rotz. This is of more importance in SCALEPACK, where only rotx and roty, and not rotz, are refined.
Note about fitting unit cell parameters: In both DENZO and SCALEPACK the unit cell is fit in reciprocal space, not real space. This means that for a non-orthogonal space group, refining the value of a* may end up changing the values of b and c, even though b* and c* remain the same. The same is true for the angles: fitting [[alpha]]* may end up changing [[beta]] and [[gamma]], even though [[beta]]* and [[gamma]]* remain the same. So what you may notice sometime if you are not careful is that when you ask the program to FIT crystal a*, but not b*, c*, and the angles, then a will not be a constant. a* will be constant, but when converted back to a when the other unit cell parameters have not been changes, a will not. The moral: when fitting unit cells, FIT ALL the relevant parameters.
This flag tells the program to fit B factors to every batch or film from the very first cycles of refinement. This is in contrast to the default procedure, where the B factors are fit only after the convergence of the scaling. In the default procedure, if scaling does not converge in 20 (default) cycles of refinement, B factors will be not be fit. The FIT B command can override this. Not to be confused with the postrefine FIT B* command described above. You cannot "postrefine" B (temperature) factors.
| format | FIT B |
| default | this flag is turned off |
| example | FIT B |
This flag tells the program not to fit b factors at all. Usually it is combined with the input of the b factors you want to apply but do not wish to refine anymore or it is used for frozen crystals where you do not expect significant decay.
| format | FIX B |
| default | turned off; B factors are fit after the scale factor refinement converges. |
| example | FIX B |
For Hamlin archive files a fixed window of 3, 5, 7, or 9 frames or the original Hamlin-determined window of frames may be used for summing a reflection. Valid only for ARCHIVE file FORMAT only.
| format | FIXED WINDOW value |
| default | uses the Hamlin definition of the window |
| example | FIXED WINDOW 7 |
This keyword specifies the type format of the input hkl and intensity data. Input data can come from any of nine types of files. This program requires this keyword to properly read the files.
| modifiers | DENZO_ip | from frames processed with DENZO |
| DENZO_york1 | output created with DENZO option york | |
| SCALEPACK | from SCALEPACK output file | |
| rigaku raxis | binary R-Axis software output | |
| xds profit.hkl | binary output from XDS output file | |
| madnes procor intout | binary madness output | |
| madnes procor ascii | ASCII madness output | |
| xengen urf | binary output from xengen. Also have to supply program with info about FRAME WIDTH, in degrees, using FRAME WIDTH keyword. | |
| Archive | binary output from Hamlin software | |
| formats | FORMAT modifier | |
| default | DENZO_ip | |
| examples | FORMAT DENZO_ip | |
Note that if you use one of the binary formats that the data must be scaled on the same type of computer that created the binary files due to incompatibilities in number representations between computers.
Only for URF files created by Xengen. Other formats do not need this specification because SCALEPACK can read this information off the file header. The oscillation range for each frame.
| format | FRAME WIDTH value |
| default | here is no default, this input is required for this format |
| example | FRAME WIDTH 0.2 |
Matrix for re-indexing. Default = unit matrix. This matrix is applied to the hkl's as they are read in.
h' = (1)*h + (2)*k + (3)*l
k' = (4)*h + (5)*k + (6)*l
l' = (7)*h + (8)*k + (9)*l
Input is in the order (1....9). HKL MATRIX works with postrefinement.
| format | HKL MATRIX value11 value12 value13 value21 value22 value23 ...etc |
| default | the default is the unit matrix |
| example | HKL MATRIX 0 1 0 1 0 0 0 0 -1
transforms hkl into k h -l, has the effect of switching a and b. -1 is to keep the determinant positive. Note, the program will not accept a matrix which has a negative determinant. |
Divides each h, k, and l by the input values. Useful for reducing the unit cell volume, particularly after HKL MATRIX transformation. Very rarely needed. Example, index data originally in C222 and want you data in, say, P3, you would apply HKL SCALE of 2 2 1, and HKL MATRIX of 1 1 0 1 -1 0 0 0 -1 so that the new indices would have values of h +k/2, h-k/2, and -l.
| format | HKL SCALE value1 value2 value3 |
| default | 1 1 1 |
| example | HKL SCALE 2 2 1 |
Used to make a quick test of mixindexing. Adds the specified integer vector to each original h, k, and l. If you are successful in using this, congratulations, you now have to reprocess your data in DENZO with the correct indexing.
| format | HKL SHIFT integer integer integer |
| default | 0 0 0 |
| example | HKL SHIFT 0 1 0 (we'll assume you weren't too far off) |
Opposite of INCLUDE OVERLOADS. This is not the default. Useful if you collect data at low and high exposures and is useful to ignore the saturated reflections at the high exposures. Applies to data read in after this command.
INCLUDE OVERLOAD is flag for whether fitted profiles with some pixels missing (typically due to overload) should be included in the scaling. Affects only DENZO image plate output files (formats DENZO_ip, DENZO_york1). Note that for summed profiles this does not apply because only profile fitting can estimate the value of the overloaded pixels.
| format | INCLUDE OVERLOADS |
| default | this is the default |
| example |
Table of starting B factors, one per batch, beginning on the record after the title. After running the program once, the output table of B factors can be cut out and pasted in here, for example, when you have set the FIX B flag and are not refining b values anymore.
| format | INITIAL B FACTOR batch no. b value batch no. b value ... |
| default | default value of the DEFAULT B FACTOR, which is defaulted to 0 |
| example | INITIAL B FACTOR 1 0.0 2 0.1 3 0.1 4 0.1 5 -0.2 ...etc |
Table of starting scale factors, one per batch, beginning on the record after the title. After one run of the program, the output table of scale factors can be cut out and pasted in here. This table is not required. If it is not included in the control input, then the DEFAULT SCALE is used (this is 1 unless otherwise specified). Note that if the initial scale factor is set to zero, that frame is ignored in the scaling and refinement.
| format | batch no. scale value batch no. scale value ... |
| default | default value of the DEFAULT SCALE factor, which is defaulted to 1 |
| example | INITIAL SCALE FACTOR 1 1.0 2 0.9 3 0.0 4 0.85 5 1.1 ...etc. |
Redirection. Tells the program to read the file which follows the keyword. Same as in DENZO.
| format | @ filename |
| default | no redirection |
| example | @ reject |
Flag that tells the program to merge (combine, average) reflections with the same unique index. This is the SCALEPACK default.
| format | MERGE |
| default | this is the default and need not be specified |
| example |
Allows you to input the value of the mosaicity of the data set. This is normally read from the header of the .x file.
| format | MOSAICITY value |
| default | read from the header of the .x file |
| example | MOSAICITY 0.5 |
Opposite of the keyword ANOMALOUS. Causes I+ and I- to be merged. This is the default.
| format | NO ANOMALOUS |
| default | this is the default |
| example |
Flag for the output of unmerged (reflections with the same unique hkl are not combined) data. Opposite of the keyword MERGE. This is a very handy for specialized work. This flag has subsidiary modifiers include partials, original index or as default include no partials.
| modifiers | include partials | .all observations, both fully and partially recorded, are included in the output. The output will consist of the unique hkl, batch number, asymmetric unit, I, [[sigma]], and fractionality of the reflection. There is no information about I+ and I-, although it may be possible to get this in subsequent versions of the program. |
| include no partials | only fully recorded reflections and those fully recorded reflections created by the summation of partials are included in the output. Partials which cannot be summed to a fully recorded reflection are lost. The output will consist of the unique hkl, batch number, asymmetric unit, I, and [[sigma]]. This is the default for NO MERGE. There is no information about I+ and I-. | |
| original index | the output will also contain the original (not unique) hkl for each reflection. This is designed for MAD/Anomalous/local scaling work. The original index modifier only works with the default INCLUDE NO PARTIALS. The output will consist of the following: original hkl, unique hkl, batch (film) number, a flag (0 = centric, 1 = I+, 2 = I-), another flag (0 = hkl reflecting above the spindle, 1 = hkl reflecting below the spindle), the asymmetric unit of the reflection, I (scaled, Lorentz and Polarization corrected), and the sigma of I. The format is (6i4, i6, 2i2, i3, 2f8.1). |
| format | NO MERGE modifier |
| default | |
| example | NO MERGE original index |
Notes: This command is also useful if you just want to combine all of the information contained in multiple .x files into a single file. Simply read in all of the .x files, don't do any scale or b factor refinement, and output no merge include partials.
This is a flag which operates only on ARCHIVE FORMAT files. Tells SCALEPACK that reflections with weird profiles should not be rejected. Opposite of the keyword PROFILE TEST.
| format | NO PROFILE TEST |
| default | this is not the default |
| example |
Number of cycles for refinement of scale and B-factors. Default value is 20 cycles. If it is set to 0, the program computes statistics, merges reflections with the same unique hkl, and writes the OUTPUT FILE based on the INITIAL SCALE and B factors. Normally you do not have to specify this unless you want to avoid scaling.
| format | NUMBER OF ITERATIONS integer |
| default | 20 (iterations) |
| example | NUMBER OF ITERATIONS 0 |
Number of resolution shells the data is divided into for the basis of calculating statistics. This input is required and must match the number of zones specified under the ESTIMATED ERROR keyword. Handy tip: it's nice to set up the NUMBER OF ZONES to equal the number of zones used by X-plor for the output of refinement statistics by shell, for when you get around to publishing your data and refinement statistics together in a paper.
| format | NUMBER OF ZONES integer |
| default | this input is required |
| example | NUMBER OF ZONES 10 |
Three integer vector which describes the orientation of the VERTICAL AXIS of the crystal. Equivalent to DENZO and SCALEPACK keywords VERTICAL AXIS. This information is usually not input by the user but subsequent versions will read it from the header of the .x files. This command does not affect scaling or postrefinement, however it does affect the values of the misorientation angles reported in the SCALEPACK log file.
| format | ORIENTATION AXIS 1 integer integer integer |
| default | default 1 0 0 |
| example | ORIENTATION AXIS 1 0 1 0 |
Same as ORIENTATION AXIS 1 except describes the spindle axis of the crystal. Equivalent to DENZO and SCALEPACK keywords SPINDLE AXIS. Otherwise the same as above.
| format | ORIENTATION AXIS 2 integer integer integer |
| default | 0 0 1 |
| example | ORIENTATION AXIS 2 1 0 0 |
Refers to the window size of ARCHIVE FORMAT files. Opposite of FIXED WINDOW .
alias for the keyword ANOMALOUS.
Name of file for output of scaled measurements. A new file will be created if none exists, but a pre-existing file will be overwritten. Maximum of 80 characters allowed in the file name. Depending on whether ANOMALOUS flag is set, there are one or two sets of I and sigma(I) per reflection. Output is h, k, l, I, sigma(I) (NO ANOMALOUS flag) or h, k, l, I+, sigma(I+), I-, sigma(I-) (ANOMALOUS flag) in format (3I4, 4F8.1). If the NO MERGE flag has been set, unmerged data are output as h, k, l, asymmetric unit #, I, sigma(I) in format (4I4,2F8.1) and the ANOMALOUS flag has no effect. For NO MERGE original index the output format is: original hkl, unique hkl, batch (film) number, a flag (0 = centric, 1 = I+, 2 = I-), another flag (0 = hkl reflecting above the spindle, 1 = hkl reflecting below the spindle), the asymmetric unit of the reflection, I (scaled, Lorentz and Polarization corrected), and the sigma of I. The format is (6i4, i6, 2i2, i3, 2f8.1).
| format | OUTPUT FILE name (use single quotes for safety) |
| default | you must specify the output file name |
| example | OUTPUT FILE '/people/myname/LYSOZ.sca' |
This command allows you to correct a mistaken polarization/monochromator value entered when you ran DENZO. It saves you from the chore of reprocessing all of your original images once you have learned of a mistake. This is mainly for synchrotron users who collect very high resolution data.
| format | POLARIZATION DENZO value corrected value |
| default | the polarization is read off the header of the .x file |
| example | POLARIZATION DENZO 0.0 corrected 0.9 |
Number of cycles of postrefinement do be done. Works in conjunction with the FIT commands described above. If you set the number of postrefinement cycles to zero, then postrefinement will be skipped even if you have fit commands in your control file.
| format | POSTREFINE integer |
| default | postrefinement is not done unless you specify it |
| example | POSTREFINE 10 |
This flag tells the program to print the results of the specified calculation after every refinement cycle. Useful in the case where one scales non-isomorphous data and wants to make the outlier list short by using the statement PRINT total chi2 200 PRINT single chi2 100.
| modifiers | total chi2 | cutoff for printing poor reflections. Total [[chi]]2 for all measurements of a reflection. Default =52 |
| single chi2 | cutoff for printing poor reflections. [[chi]]2 for any single measurement of a reflection. Default =3.52. | |
| correlation | prints correlation matrix | |
| no correlation | default | |
| solution | prints new scale and B factors | |
| no solution | default | |
| shifts | prints changes to scale and B factors | |
| no shifts | default | |
| formats | PRINT modifier | |
| defaults | PRINT total chi2 | |
| PRINT no correlation | ||
| PRINT no solution | ||
| PRINT no shifts | ||
New scale and B factors will always be printed if the number of fitted parameters exceeds 300.
Profile test is a flag that can be turned on and off as desired. This is the default. Bad profiles can be used to reject a DCREDUCE summed hkl. Valid only for ARCHIVE file FORMAT only. Opposite of NO PROFILE TEST .
This flag tells SCALEPACK how the profiles were treated by the indexing program (e.g. DENZO). The two choices for profiles are fitted and summed. Valid for DENZO_ip, DENZO_york1, and xengen urf FORMATS. Most of the time people fit profiles, so this is the default and need not be specified in the command file.
| format | PROFILES FITTED |
| default | this is the default |
| example |
The other choice from PROFILES FITTED. This is not the default and must be specified if true.
Metric tensor description of the reciprocal space unit cell. Why would you ever use this when you can specify the real space constants?
| format | RECSQ value1 value2 ... value6 |
| default | same as UNIT CELL |
| example | RECSQ 0.0001 0 0 0.0004 0 0.0009 [to describe unit cell 100 50 33 90 90 90] |
REFERENCE BATCH ( OR BATCHES )
Specifies which batch or film or set of batches or films will be the reference for the scaling and B refinement. The scale and B factor for these are not refined. More than one film or batch may be used as the reference. This is important only for crystals which decay during data collection. If the crystal is frozen and does not decay, then the default may be used, which is to let the eigenvalue filter define the overall scale and B factor. With a large number of batches, reliance on the eigenvalue filter is a little bit dangerous, so you should consider using a reference batch number in those cases.
This keyword is entirely equivalent to the keywords: REFERENCE BATCHES, REFERENCE FILM, REFERENCE FILMS. The others exist because some people have a grammatical hang up about using the singular to describe more than one object.
| format | REFERENCE BATCH integer integer integer ... etc. |
| default | no reference batch. Eigenvalue filter defines overall scale and B |
| example | REFERENCE BATCH 1 3 4 5 |
Same as REFERENCE BATCH.
Flag which tells the program to reject a list of individual hkl's which FOLLOW. This is useful for iterative rejection cycles, since the file containing the rejected reflections can be reread. Each record after the title contains one reflection with the variables h, k, l (original index) and film number in free format. This information is most easily edited from the printed output of a previous run, can contain the whole line. One can read it from a reject file with command @reject.
| format | REJECT HKL |
| default | this is not the default |
| example |
Automatic rejection of outliers. Not yet reliably implemented. This is supposed to replace multiple rounds of running SCALEPACK. The idea is that when this keyword is set, SCALEPACK runs once, makes a reject.dat file, then runs again, reads the reject.dat file and scales the data based on the reduced set of observations.
Applies Bayesian rejection of outliers. Rejected observations are written to the reject.dat file (see WRITE REJECTION FILE). The whole hkl (all original hkls with the same unique hkl) with at least one observation with a probability of being an outlier greater than or equal to the value specified after the WRITE REJECTION FILE keyword (default 0.9) are written to the log file. This is an estimation on your part of how frequently you expect any observation to be an outlier. In principle, the rejection probability should be about equal to the number of outliers divided by the number of observations. A good value to use is 1/10,000, i.e. 0.0001, for normal good data. If you have a non-random signal in your background (e.g. satellite crystals, malfunctioning detector, ice rings) then you will probably have to increase the rejection probability. If you do not want to generate a reject list in the log file then omit the keyword. A comparison of R-linear and R-squared is often helpful for deciding whether to increase the rejection probability. See the discussion following Scenario1 for more on this.
The rejection algorithm used in SCALEPACK is the most sensible and statistically sound outlier rejection algorithm. Unlike some other programs, the SCALEPACK outlier rejection is based on comparing differences to sigmas. So it will typically reject, say 4 or 5 sigma outliers. Some reflections with a large discrepancy from the average value of I may simply represent a lack of adequate statistics in measurement and not a "mistake" (non-random error) in measurement. If a reflection has a large discrepancy from the average and a large sigma, its contribution to the average will be very small anyway.
Here's an example of how the outlier rejection algorithm works:
| Input data (after scaling) | ||
| Obs# | I | sigma |
| 1 | 10.0 | 0.1 |
| 2 | 10.1 | 0.1 |
| 3 | 9.9 | 0.1 |
| 5 | 11.0 | 0.1 |
| 2 | 20.0 | 10.0 |
Although you may think that {5} is the outlier, in fact the consistent set of observations will be {1, 2, 3, 5}, and {4} will be the outlier. Why is this? A consistent average will be 10.0 (or more exactly 10.000003), because observation 5 has a 1/1000000 lower statistical weight than the other observations, due to its large sigma. Observation 4, on the other hand, which was measured more accurately, will be 8.7 sigma deviations from the average of the remaining observations because the expected error of the difference 4 - <{1,2,3,5}> is 0.115, and 8.7 = (11.0 - 10.000003) / 0.115.
So the observation with the largest deviation from the average is not necessarily a statistical outlier. Note also that R-merge (after outlier rejection) will be very bad, 25%, even if the average is measured extremely well, with a sigma of 0.057%! This has to do with R-merge being an unweighted statistic, and I/[[sigma]] being a weighted statistic. If some other program rejected observation 5 (for no good reason) and observation 4 (for good reason), R-merge would be 0.067%. Practice shows that most programs would reject observation 5 because many users want a good R-merge. And sometimes these program would not even flag the true outlier - observation 4!
| format | REJECTION PROBABILITY value |
| default | 0.0001 |
| example | REJECTION PROBABILITY 0.0001 |
Minimum d-spacing for this run. Default is the maximum resolution found in the input data. One can supply two numbers in any order and they will be minimum and maximum d-spacings.
| format | RESOLUTION value [value] |
| default | the highest resolution detected in .x file |
| example | RESOLUTION 10 2.2 |
Has the effect of changing the number of reflections per shell for the purposes of printing out statistics. Formally, it represents the exponent of the zone volume calculation. Normally, this is 3, because the volume of a sphere goes as radius cubed, so all the statistics shells will have the same number of reflections. Changing the resolution step could be useful to prepare a table of statistics to compare with other programs which may print out the statistics differently.
| format | RESOLUTION STEP value |
| default | RESOLUTION STEP 3 |
| example | RESOLUTION STEP 2.5 |
This is the flag for keeping Bijvoets (I+ and I-) separate both in scaling and in the OUTPUT FILE. If the SCALE ANOMALOUS flag is on, anomalous pairs are considered non-equivalent when calculating scale and B factors and when computing statistics, and are merged separately and output as I+ and I- for each reflection. The old bug in the program, where I+ and I- were merged, has now been fixed. Note that this is a dangerous option because scaling may be unstable due to the reduced number of intersections between images. The danger is much larger in low symmetry space groups. Scale anomalous will always reduce R-merge, even in the absence of an anomalous signal, because of the reduced redundancy. However, [[chi]]2's will not be affected in the absence of an anomalous signal.
| format | SCALE ANOMALOUS |
| default | definitely not the default |
| example |
Can be used to restrain scale factor differences from consecutive films or batches. The value which follows the flag represents the amount you will allow the scale factors to differ from consecutive films or batches. It adds a factor of (scale1 - scale2)2/(scale restrain)2 to the target function minimized in scaling. The earlier edition of this manual stated that this was an obsolete option. This is no longer the case. It has been resurected in a different form now.
This only applies to batches between which you ADD PARTIALS. For very thin frames, this is almost obligatory. The value should roughly represent the expected relative change in scale factors between adjacent frames.
| format | SCALE RESTRAIN value |
| default | not turned on |
| example | SCALE RESTRAIN 0.01 (expect 1% change between adjacent frames) |
Substitutes for the ### wildcard to specify a group of files to be read. See the FILE keyword above.
| format | SECTOR integer to integer |
| default | no default |
| example | SECTOR 1 to 40 |
Sector width can be specified in degrees. A pseudofilm is a sector width's worth of data from one detector. Valid for area detector data only, default value 5 degrees.
| format | SECTOR WIDTH value |
| default | 5 degrees |
| example | SECTOR WIDTH 3.0 |
Cutoff for rejecting measurements on input. Default = -3.0. Be very careful if you increase this.
What is the rationale for using sigma cutoff -3.0 in SCALEPACK? Wouldn't you want to reject all negative intensities? Why shouldn't you use a sigma cutoff 1.0 or zero? The answer to these questions is as follows: The best estimate of I may be negative, due to background subtraction and background fluctuation. Negative measurements typically represent random fluctuations in the detector's response to an X-ray signal. If a measurement is highly negative (<= -3[[sigma]]) than it may be more likely the result of a mistake, rather than just random fluctuation.
If one eliminates negative fluctuations, but not the positive ones before averaging, the result will be highly biased. In SCALEPACK, sigma cutoff is applied before averaging. If one rejects all negative intensities before averaging a number of things would happen:
- The averaged intensity would always be positive;
- For totally random data with redundancy 8, in a shell where there was no signal, , there would be on average 4 positive measurements, with average intensity one sigma. This is because the negative measurements had been thrown out. So the average of the four remaining measurements would be about 2 sigma! This would look like a resolution shell with a meaningful signal;
- R-merge would be always less than the R-merge with negative measurements included;
- A SIGMA CUTOFF of 1 would improve R-merge even more, by excluding even more valid measurements.
Why should this worry you? Exclusion of valid measurements will deteriorate the final data set. One may notice an inverse relationship between R-merge and data quality as a function of "sigma cutoff". So much for using R-merge as any criterion of success.
Even the best (averaged) estimate of intensity may be negative. How to use negative I estimates in subsequent phasing and refinement steps is a separate story. The author of SCALEPACK suggests the following:
- You should never convert I into F.
- You should square Fcalc and compare it to I. Most, but not all of the crystallography programs do not do this. That is life. In the absence of the proper treatment one can do approximations. One of them is provided by French and also by French and Wilson. An implementation of their ideas is in the CCP4 program TRUNCATE. A very simplified and somewhat imprecise implementation of TRUNCATE is this:
if I > [[sigma]](I), F=sqrt(I)
if I < [[sigma]](I), F=sqrt([[sigma]](I))
| format | SIGMA CUTOFF value |
| default | -3 |
| example | SIGMA CUTOFF -2.5 |
Space group symbol from the list below. This input is required! The space group may be entered as a name (e.g. P212121) or as a number (e.g. 19, for the same space group). Most of the numbers correspond to those of the International Tables. The numbers above 230 are non-standard definitions of space groups.
|
1 P1 3 P2 4 P21 5 C2 16 P222 17 P2221 18 P21212 19 P212121 20 C2221 21 C222 22 F222 23 I222 24 I212121 75 P4 76 P41 77 P42 78 P43 79 I4 80 I41 |
89 P422 90 P4212 91 P4122 92 P41212 93 P4222 94 P42212 95 P4322 96 P43212 97 I422 98 I4122 143 P3 144 P31 145 P32 146 R3 149 P312 150 P321 151 P3112 152 P3121 153 P3212 |
154 P3221 155 R32 168 P6 169 P61 170 P65 171 P62 172 P64 173 P63 177 P622 178 P6122 179 P6522 180 P6222 181 P6422 182 P6322 195 P23 196 F23 197 I23 198 P213 199 I213 |
207 P432 208 P4232 209 F432 210 F4132 211 I432 212 P4332 213 P4132 214 I4132 303 P2C 305 B2 318 P21221 401 C1 403 P21C 446 H3 455 H32 501 I1 503 I2 505 C21 |
Notes to particular space groups:
| 146 R3 | R3 in hexagonal setting | |
| 446 H3 | R3 in primitive setting | |
| 155 R32 | R32 in hexagonal setting | |
| 455 H32 | R32 in primitive setting | |
| 401 C1 | Non-standard, but useful to make angles close to 90. | |
| 501 I1 | Non-standard, but useful to make angles close to 90. | |
| 303 P2C | P2, C axis unique | |
| 403 P21C | P21, C axis unique | |
| 305 B2 | like C2, B face centered, c axis unique | |
| 503 I2 | Non-standard, but useful to make beta angle close to 90. | |
| 172 P64 | Only number (172) works, name does not (v. 1.2.3) |
Alias for ORIENTATION AXIS 2.
Real cell specified as a, b, c, alpha, beta, gamma. UNIT CELL is included in the header of DENZO_IP, DENZO_york1, ARCHIVE and SCALEPACK files, otherwise it must be included.
| format | UNIT CELL value value value angle angle angle |
| default | the value from the first header encountered |
| example | UNIT CELL 50 62 100.3 90 90 90 |
Note that the post refined value of the unit cell constants is not used nor is it output in the SCALEPACK OUTPUT FILE. You must get this information from the log file if you are interested in it.
Same as ORIENTATION AXIS 1.
Writes *.xrej files so that reflections from the reject file may be displayed by XDISPLAYF. Not fully implemented. Will terminate the program and prevent scaling and postrefinement. Note that the command @reject must precede the input of the .x files.
Creates a file with hkl's to be rejected. UNIX file name: reject, VMS file name: REJECT.DAT. Reject file is created if it does not exist. If the file exists it is overwritten. Note that this is different behavior from previous versions of SCALEPACK prior to version 1.2, which used to append the reject file. The current version continues to include the rejected reflections from the @reject command in the subsequent reject files, but they will now be in order.
Note also that you can specify the threshold for what you consider to be a rejectable probability. The default is 0.9, which is fairly safe, but you may want to decrease this to, say, 0.5 on later rounds of rejection.
| format | WRITE REJECTION FILE value |
| default | does not write the rejection file, but if it does, the default value is 0.9 |
| example | WRITE REJECTION FILE 0.5 |