Content-type: text/html Man page of X-GEN


Section: X-GEN Commands (1)
Updated: April 2005
Index Return to Main Contents


X-GEN - refine  


"refine" provides for a "Curses"-based interactive refinement of crystal and detector parameters. The current definitions of the run parameter file, the calibration mapping, and the border definition are invoked upon mapping. When you invoke "refine" a crowded curses menu appears. On it are a set of values for unit cell lengths and angles, pseudo-goniostat Euler angles, detector positional parameters, rocking-curve parameters, and some facts about the sample and the data run. There are also labels for these, Booleans that control whether a given parameter is currently subject to refinement, and values that record how much the parameter changed in the most recent cycle of refinement. There is also either a help menu or a statistical summary of the run, appearing at the bottom of the menu.
The user can navigate around the "refine" menu, changing parameter

values (see "Menu Parameters," below), and he or she can issue commands by putting an appropriate command character in the "COMMAND" slot near the center of the menu and hitting control-X or (P)F1.

Menu Parameters:

The specific parameters that appear on the menu are:
The unit cell lengths a, b, and c in Angstroms. In
space groups where cell lengths are tied to one another, the output will reflect those ties: thus in tetragonal spacegroups, even if the user enters values of a and b that are not equal, the program will force b to equal a.
alpha, beta, gamma: The unit cell angles alpha, beta, and gamma in degrees.
The software will force values of the cell angles appropriate to the crystal system: thus in hexagonal spacegroups it will force alpha = beta = 90, gamma = 120. In rhombohedral spacegroups gamma is taken to be the independent angle, so the software sets alpha to gamma and beta to gamma.
The pseudo-goniostat Euler angles omega, chi,
and phi in degrees. These angles specify the rotation from the goniostat's true (omega = 0, chi = 0, phi = 0) position to one at which a will lie along X and b mostly along Y, where X is the direction pointing from the crystal toward the source, Z is the rotation axis, and Y is forms a right-handed (X,Y,Z) system with the others.
the sample-to-detector distance in cm.
Xcen, Ycen:
the X and Y offset of the main-beam from the
detector center at two-theta=0, in centimeters.
the angle between the detector's nominal vertical
axis and the crystal goniostat's omega direction, in degrees. This value is typically close to zero, but with a detector turned on its side it could be +/- 90. A convenient way to flip the sign of the stepsize of a run is to change the tilt angle by 180 degrees.
the angle between the direct beam direction and the
normal to the detector face. The sign of this angle is typically opposite to that of the "two-theta" angle defined in the data acquisition software of on most goniostats.
gamma0, gamma1, gamma2:
Three parameters characterizing the
dependence of the rocking width of the reflections on their (X,Y) position. The first two parameters are specified in frames; the third in degrees. The definitions of these parameters are given in Harrison et al, Methods in Enzymology 114: 226-230 (1985), except that what they call gamma(y) is called gamma0 here; their gamma(z) is gamma1; and their gamma(1) is gamma2 here.
error limits:
These define the maximum errors allowed in
reflection index, detector X, detector Y, and scanning angle. Any reflection violating these criteria will be excluded from refinement. These errors are ignored for rocking-curve refinements and during auto-indexing. For linear refinements on index, the index errors are examined individually. For nonlinear refinements and linear refinements on scanning angle, all the error limits must be satisfied in order for a reflection to be included in the residual calculations.
resolution limits:
These define the minimum resolution (maximum D
spacing) and maximum resolution (minimum D spacing) for reflections used in refinement. The default values of these parameters will be taken somewhat /outside/ the lowest-resolution and largest-resolution reflections encountered in the CENTROIDS file, so that small changes in detector parameters will not cause any reflections to drop off the refinable list. Thus if the data extend from 24 to 1.8 Angstroms, the program will set the limits to about 29 and 1.6.
crystal system:
This defines the crystal system as an integer
between 1 and 7: 1 is triclinic, 2 is monoclinic, 3 is orthorhombic, 4 is tetragonal, 5 is cubic, 6 is hexagonal or trigonal, and 7 is rhombohedral, indexed rhombohedrally. Rhombohedral spacegroups may be specified as being in either a rhombohedral (7) or a hexagonal (6) system, depending on how you wish to index the crystal.
This defines the spacegroup as an integer between
1 and 230. The number is the International Tables numerical designation for the spacegroup; thus P2(1)2(1)2(1) is spacegroup 19, and P6(1) is spacegroup 169. Rhombohedral spacegroups may be specified either with rhombohedral or hexagonal crystal systems; the International Tables number given in this slot will be unaffected.
This is the stepsize between frames in degrees. The
sign convention is opposite to that found on most three- and four- axis goniostats, so if the data acquisition program is set up to step by +0.25 degrees per frame, the value specified here should be -0.25.
This defines the X-radiation wavelength in Angstroms
starting goniostat angle:
These define the position, in degrees,
of the goniostat as of frame zero of the current data run. Thus if frame 1 was collected at (omega, chi, phi) = (40.0, 45.0, 180.0) and the stepsize is -0.2 degrees, the start values should be (40.2, 45.0, 180.0).


Among the many commands available at the level of the control-X keystroke are:

This performs a nonlinear (Simplex) refinement of all the crystal and orientational parameters that are currently active. It minimizes a residual Z of the form Z = wp * SUM dphi(i) + wh * SUM dhi + wx * SUM(dxi + dyi ) where dphi(i) = (phi(obs) - phi(calc))^2 for the ith observation,
dhi = ([h]-h)^2 + ([k]-k)^2 + ([l]-l)^2 for the ith observation, dXi = (X_obs - X_calc )^2 for the ith observation, dYi = (Y_obs - Y_calc )^2 for the ith observation,
and [u] is the integer closest to u. For this particular refinement milieu, wp = 0.6, wh = 0.3, and wx = 0.1.
This examines the current unit cell lengths and angles, computes a residual associated with each of the sixteen distinct lattice characters and prints out all sixteen in increasing order of residual. The residual associated with triclinic is by definition 0. Values below 0.01 are usually correct. The user can choose which of the lattice characters is correct, and then choose whether to impose the symmetry that that lattice character implies. After doing so, the program reverts to the normal menu.
This writes the current parameters to the environment variable UPARAMS and then exits.
This reads the current parameters in from the file UPARAMS. This is done automatically when you invoke "refine", but one occasionally needs to re-read the parameters in the midst of refinement.
This does a detector remapping based on a polynomial fit of the errors in detector (X,Y) positions of the form
dX = u0 + u1*X + u2*Y + u3*X*X + u4*X*Y + u5*Y*Y,
dY = v0 + v1*X + v2*Y + v3*X*X + v4*X*Y + v5*Y*Y,
These twelve parameters (u0-u5 and v0-v5) are determined by least-squares fit to the dX and dY values. This algorithm is somewhat different from the one used in the "M" refinement (below).
This performs an automated indexing of the data in the CENTROIDS file. It computes difference vectors between pairs of spots that fall within the specified resolution range and attempts to obtain a self-consistent indexing of the crystal such that the cell lengths and angles fall within the specified percentage limits around the input values. The auto-indexing is done in triclinic, so it is up to the user to re-impose crystal symmetries afterward.
This performs a linear least-squares refinement of the spots contained in the CENTROIDS file. The parameters refined thereby are those whose values were specified to be refinable in the menu.
This modifies the pixel-to-centimeter and centimeter-to-pixel mapping of the detector face by minimizing differences between observed and calculated (X,Y) centroids for real diffraction spots in the neighborhood of some reference positions on the detector face.
This dumps out the results of refinement for the individual reflections on which the refinement is based. The dump goes to the file with environment variable name XLOG. Each line of the dump contains the (non-integer) reflection indices h,k,l; the observed and calculated X and Y values; the observed, modified observed, and calculated phi values; and a flag. The "modified" phi value is the one obtained when the rocking-curve model is applied to the raw observed phi value. The flag value is zero for well-behaved reflections that match the current matrix and various non-zero values for problem reflections.
Alter the management of reflections in ice-rings. By default ice-ring reflections are treated the same as any other reflections. "P" toggles that behavior, i.e. if ice-ring reflections are currently treated as normal, then invoking "P" will cause ice-ring reflections to be excluded. If ice-ring reflections are currently being excluded, then invoking "P" will cause them to be treated normally. The list of resolution ranges associated with ice-rings is read from the file with environment variable name ICERING. If that file is absent, the excluded ranges are set to be (3.97 to 3.60 Å), (3.48 to 3.40Å), (2.70 to 2.63Å), and (2.28 to 2.21Å). There are prominent ice-rings at even higher resolution than 2.21 Ångstroms; if those prove to be a problem during refinement, we recommend setting up your own file.
This quits the refinement without writing out the parameters. Don't do this if you want to save your results!.
This performs a rocking-curve parameter refinement. The parameters that get refined are gamma0, gamma1, and gamma2, as described above. The gamma2 refinement tends to be unstable; skip it (by turning off gamma2) or at least use it with care.
This provides the user with a list of ways to re-index the unit cell. The available re-indexing types are:
Tricl triclinic type I or II, a <= b <= c
PermuteF permute forward, (a,b,c)->(b,c,a)
PermuteB permute backward, (a,b,c)->(c,a,b)
SwapAforB swap a for b
SwapAforC swap a for c
SwapBforC swap b for c
SupplAB supplements: α'=π- α, β' = π - β
SupplAG supplements: α'=π- α, γ' = π - γ
SupplBG supplements: β'=π- β, γ' = π - γ
Extern External matrix supplied in REINDEX file
This updates the statistics display without doing a new cycle of refinement. This is needed after an auto-indexing or when the display has been messed up.
0 - 9
These perform a nonlinear simplex refinement of the
spots contained in the CENTROIDS file. The parameters refined thereby are those specified to be refinable in the menu. The weight with which the index residual enters into the total residual is specified by the "index weight" parameter; the weight associated with the omega error residual is 1 - (index weight). Thus in the formula given for the "A" refinement, if we use a command value u, 0 <= 9 <= u, then wx = 0, wh = 0.11 * u, wx = 1 - wh .


Report bugs to Andy Howard at or 312-567-5881.  


Copyright © 2002, Illinois Institute of Technology. See the file 'LICENSE' for information on usage and redistribution of this file, and for a DISCLAIMER OF ALL WARRANTIES




This document was created by man2html, using the manual pages.
Time: 02:08:09 GMT, October 03, 2005