CHAPTER 11

Reference

11.1 Precognition_E´.´.´_P´.´

precognition_E´.´.´_P´.´

Precognition

precognition

This is the command-driven version of Precognition. It prints the release number and credits, imports CPL, the supporting library, and prints CPL version number. If appropriate license is found, a main menu is printed, otherwise, the program terminates with an error message. The main functionalities of this program are indexing, geometric refinement, spot profile fitting, integration, and spatial overlap deconvolution. E´.´.´ indicates edition, version, release, and patch numbers. P´.´ is platform or operating system and its version.

Each menu begins with a colon-separated (:) path that indicates the level of the menu. The same path is printed again at the end of the menu, and serves as a prompt. All activated menu items are listed in the second column. Disabled items are not shown, but they may be activated when conditions are met. The full string of a menu item is the command to execute the item. An all-lower-case command is also valid. An abbreviated single letter listed in the third column functions the same way. The single letter is not case sensitive, and is in parentheses following each section title in this chapter. The fourth column includes some brief instruction on the usage of the menu item.

Precognition: Input I: File & keyboard input (image & parameters)

Quit Q: Exit DPR (default)

Precognition:

Listing 11.1.0.0.1 A menu.

At any level of the program, if the non-space leading character is an at sign (@) or a less than sign (<), the remaining command is considered as a filename of a preprogrammed command script. This script will be loaded in, if found. All commands in the script will be executed one after another. If the end-of-file is reached, the control will return to keyboard or previous control. If the program is told to terminate inside the script, the program will exit without execution of the rest of the commands. Any unknown command in the script will cause a fatal error and immediate termination of the program. A command script can be loaded and executed when the program is launched by giving the script filename as an argument to the program.

At any level of the program, if the non-space leading character is a left (() or right ()) parenthesis, an exclamation mark (!), a number sign (#), or a semicolon (;), this line is considered as a comment, and will cause no action.

At any level of the program, if the non-space leading character is a dollar sign ($), a percent sign (%), or a greater than sign (>), the rest of the command will be passed to the shell where the program is launched. This feature is system-dependent.

11.1.1 Precognition:Input (I|i)

Enters Input submenu. This submenu is responsible for taking many data and control parameters.

11.1.1.1 Precognition:Input:Format (F|f)

Accepts a literal string that identifies image file format and detector type. The string is case sensitive. Unrecognized string or mismatching the string with an image file will cause error while loading an image, but not always a warning or error message. The current version supports a number of formats listed in Table 11.1.1.1.1. Additional formats can be implemented upon request.

Format code	Detector
Bas2000, FujiImagingPlate	Fuji imaging plate Bass2000 scanner 100 mm
ESRF, ESRFImageIntensifiedCCD	ESRF image-intensified CCD
Mar345, MAR3450Packed	Mar345 packed 100 mm
MarCCD, MARCCD165	Mar CCD 165 80 mm
Quantum4	ADSC Quantum-4

Table 11.1.1.1.1. Supported detector formats.

If no string is given, this command enters a submenu for format selection.

Precognition:Input:Format:Bas2000 (B|b)

Precognition:Input:Format:ESRF (E|e)

Precognition:Input:Format:Mar345 (M|m)

Precognition:Input:Format:MarCCD (C|c)

Precognition:Input:Format:Quantum4 (4)

Selects the corresponding format.

11.1.1.2 Precognition:Input:Image (I|i)

Loads an image file. This command expects a string as a filename of the image to be loaded. The filename may include a relative or absolute path. This command must be executed after a detector/file format has been specified by command Format, or an error message of unknown format will be printed. The image to be loaded must be consistent with the format. If no string follows the command, the program enters file selection menu. An optional numerical argument of choices 0 or 1 can be given. If 0 is given, the image will not be loaded except that the filename will be added to a list. 1 is the default. If a string argument of reset, Reset, or RESET is given, the list of previously loaded images or filenames is cleared. This feature is used to merge a subset of data.

This command may also load a file of goniometer settings or l-curve, if the filename has an extension of .gon or .lam, respectively. See goniometer file and .lam file for details. This feature and goniometer file are being deprecated.

11.1.1.3 Precognition:Input:Crystal (X|x)

Loads crystal information such as unit cell constants and space group. If a filename of crystal information follows this command, cell constants and space group can be loaded from the file. See crystal information file for detail. If no argument to this command, it enters the file selection menu for crystal information file. If one numerical argument follows, it is considered as a space group number. Valid numbers are integers 1 through 230. Invalid values will cause a fatal error. If six numerical arguments are given, they are taken as cell constants a, b, c in Å and a, b, g in degree. If seven numerical arguments are given, they are cell constants and space group number. If the string argument is free, Free, FREE, freed, Freed, or FREED, six numerical arguments must also be given. They are considered as uncertainties of cell constants. If no or fewer than six numerical arguments, the string argument is considered as a filename of crystal information. If the string argument is fix, Fix, FIX, fixed, Fixed, or FIXED, all uncertainties of cell constants will be set to 0. If six or seven numerical arguments are also given, they are cell constants and space group number. If one numerical argument is given, it is space group number.

11.1.1.4 Precognition:Input:Omega (O|o)

Takes two numerical arguments as polar angles Y and F in degree. See Box 3.2.0.0.1 for definition of polar angles. These polar angles define the orientation of w-axis of the simulated goniometer ccl::goniometer. See 3.2 for more information. If no or fewer than two arguments is given, the program prompts for polar angles.

11.1.1.5 Precognition:Input:Goniometer (G|g)

Takes three numerical arguments as w, c, and f settings in degree. See 3.2 for details on the simulated goniometer. If no argument is given, the program prompts for goniometer settings. If fewer than three arguments are given, the missing values are assumed to be 0.

11.1.1.6 Precognition:Input:Matrix (M|m)

Takes nine numerical arguments as missetting matrix by row. The matrix must be orthogonal. If not, the matrix will be rejected with an error message. If fewer than nine numerical arguments are given, this command is ignored. Missetting matrix defines the rotation from an aligned crystal orientation to any other orientation. The aligned crystal orientation is defined as the following: a-b plane is normal to X-ray beam, that is, a ´ b or c* is along X-ray beam or Z-axis. a is horizontal to the right when looking along the X-ray beam, that is, X-axis.

Figure 11.1.1.6.1 Aligned crystal orientation. a || x and a ´ b ^ z.

11.1.1.7 Precognition:Input:Spot (L|l)

Specifies overall spot size and signal-to-noise ratio. If no argument is given, the program prompts for overall spot length, width and s-cut. If one numerical argument is given, it is the s-cut. If two are given, they are spot length and width in pixel. If three are given, they are spot length, width, and s-cut, respectively. Spot size and s-cut are used to assist spot recognition and many other procedures where an estimate of error level is required. One shall use the typical spot size on an image or a set of images, where ‘typical’ means the greatest population.

The program default length and width are 10 pixels. The program default s-cut is 3.

11.1.1.8 Precognition:Input:Distance (D|d)

Takes one numerical argument as the crystal-to-detector distance in mm. In case if abnormal detector setting, this value is the normal distance. In case of normal detector in back reflection position, this value is still positive. It leaves the definition to 2q angle. In case of cylindrical detector, this value is the radius. In case if off-centered cylindrical detector, this value is the distance from the crystal to the direct-beam center on the cylindrical detector.

If no argument is given, the program prompts for distance. If two numerical arguments are given, the first is distance and the second is its uncertainty in mm. If a string argument of free, Free, FREE, freed, Freed, or FREED is given, a numerical argument must also be available to specify an uncertainty of distance in mm. String argument free without a number is ignored. An uncertainty value must be non-negative, or it will be ignored. If a string argument of fix, Fix, FIX, fixed, Fixed, or FIXED is given, the uncertainty of distance is reset to 0. A numerical argument with a string fix is considered a distance value rather than uncertainty.

11.1.1.9 Precognition:Input:Center (C|c)

Takes two numerical arguments as the coordinates of direct-beam center in pixel unit. If no argument is given, the program will prompt for direct-beam center. If three numbers are given, the first two are the coordinates, and the third one is the uncertainty for both coordinates. If four number are given, they are coordinates and their uncertainties.

If a string argument of free, Free, FREE, freed, Freed, or FREED is given, at least one numerical argument is needed to specify the uncertainty for both coordinates. If two numerical arguments are given with the string free, they are the uncertainties for the coordinates, respectively. If no numerical argument is given with the string free, the command is ignored. An uncertainty value must be non-negative, or it will be ignored.

If a string argument of fix, Fix, FIX, fixed, Fixed, or FIXED is given, the uncertainties of direct-beam center are reset to 0. If there are two numerical arguments given with the string fix, they are considered as direct-beam center in pixel.

11.1.1.10 Precognition:Input:Pixel (P|p)

Takes one numerical argument as the size of a pixel in mm, or two numbers as the size at horizontal and vertical directions. If no argument is given, the program prompts for pixel size. If three numbers are given, the first two are pixel sizes, and the third is the uncertainty of horizontal pixel size in mm. If four number are given, they are pixel sizes and their uncertainties.

If a string argument of free, Free, FREE, freed, Freed, or FREED is given, at least one numerical argument is needed to specify the uncertainty of horizontal pixel size. If two numbers are given with the string free, they are uncertainties of horizontal and vertical pixel sizes, respectively. If no number is given with the string free, this command is ignored. Any negative uncertainty value will be ignored.

Please note that the behavior of this command is slightly different from Center. The default uncertainty of vertical pixel size is 0. Although explicitly changing it to a positive value is legal, this shall virtually never be done, except that one knows what is going on.

11.1.1.11 Precognition:Input:Swing (S|s)

Takes two numerical arguments as the swing angles of a flat detector in degree. The first swing angle is around X-axis (horizontal), and the second is around Y-axis (vertical). The rotation center is the crystal. Therefore, one of them or both can be used as 2q angle of a flat detector depending on specific setup.

If less than two numbers are given, the program prompts for swing angles. If three numbers are given, the third value is the uncertainty for both swing angles. If four numbers are given, they are swing angles and their uncertainties, respectively.

11.1.1.12 Precognition:Input:Tilt (T|t)

Same as the command Swing, except that the rotation center of tilt angles is the direct-beam center on detector. Tilt angles are used to correct prediction errors.

If a string argument of free, Free, FREE, freed, Freed, or FREED is given, at least one numerical argument is needed to specify the uncertainty of both angles. If two numerical arguments are given with the string free, they are uncertainties of the tilt angles, respectively. If no number is given with the string free, this command is ignored.

If a string argument of fix, Fix, FIX, fixed, Fixed, or FIXED is given, the uncertainty of tilt angles is reset to 0. Numerical arguments given with the string fix are considered tilt angles rather than uncertainties.

11.1.1.13 Precognition:Input:Bulge (B|b)

Takes two numerical arguments as bulge correction coefficients, linear and quadratic, of a flat detector. These corrections are largely inherited from film and off-line imaging plate work from the past. ESRF image-intensified CCD detector also requires such correction. They are very much fudge factors for other detectors.

If no argument is given, the program prompts for bulge correction coefficients. If one number is given, it is the linear coefficient. If two are given, they are linear and quadratic coefficients. If three are given, the third one is the uncertainty of the linear coefficient. If four are given, they are bulge coefficients and their uncertainties.

If a string argument of free, Free, FREE, freed, Freed, or FREED is given along with a numerical argument, this value is the uncertainty of the linear coefficient. If two numbers are given with the string free, they are uncertainties of linear and quadratic coefficients, respectively. If no numerical argument is given, this command is ignored.

If a string argument of fix, Fix, FIX, fixed, Fixed, or FIXED is given, the uncertainties are reset to 0. Numerical arguments given with the string fix is considered as bulge coefficients in stead of uncertainties.

11.1.1.14 Precognition:Input:Resolution (R|r)

Specifies a resolution range. If no numerical argument is given, the program prompts for resolution range. If one number is given, it is taken as the highest resolution d_min in Å. The default of lowest resolution d_max is 1000 Å. If two numbers are given, they defines a resolution range. No specific order is expected. Only positive values are legal. Resolution range is used by many procedures throughout the system.

11.1.1.15 Precognition:Input:Wavelength (W|w)

Specifies a wavelength range. If two numerical arguments are given, they defines a wavelength range. No specific order is expected. If three numbers are given, the third one is a reference wavelength. If fewer than two numerical arguments is given, the program prompts for wavelength range. Only positive values are legal. If a value is greater than 1000, it is considered as X-ray energy in eV, otherwise, wavelength in Å. If X-ray energy is used, all three values should be energy in eV. Wavelength range is used in many procedures throughout the system.

11.1.1.16 Precognition:Input:Chebyshev (V|v)

Specifies the order of Chebyshev approximation to l-curves. All frame-specific l-curves must have the same order as that of overall l-curve. However, some Chebyshev polynomials of low degrees may have their coefficients fixed, while those of high degrees have their coefficients free to refine.

If no numerical argument is given to this command, the program prompts for Chebyshev approximation order for overall spectrum and the free order at higher degrees of frame-specific spectra. If one number is given, it is taken as the order of the overall spectrum, and no free order for frame-specific l-curves, that is, all frames share a single l-curve. If two numbers are given, the second one specifies the number of free order at higher degrees of frame-specific l-curves. Obviously, both numbers must be integers, and the second must not be greater than the first. Or, error message will be printed.

If a string argument of unimodal, Unimodal, UNIMODAL, bimodal, Bimodal, or BIMODAL is given, it hints the program to restrain the l-curves to be unimodal or bimodal. If a string argument of arbitrary, Arbitrary, or ARBITRARY is given, l-curves will be left as they are obtained without restrain or spike removal. If a string argument of fix, Fix, FIX, fixed, Fixed, or FIXED is given, l-curves will not be refined. String argument of free, Free, FREE, freed, Freed, or FREED reverses it. By default, if no string argument is given, a spike removal procedure will try to remove sharp spikes might present at both ends of the l-curves.

11.1.1.17 Precognition:Input:Ellipse (E|e)

Loads ellipses from a file as specified by a string argument following this command. If no argument is given, this command is ignored without prompt. Loaded ellipses may be used in indexing. See ellipse file for details on its file format. This is mostly a diagnostic feature that general users shall ignore.

11.1.1.18 Precognition:Input:Nodal (N|n)

Loads nodal spots from a file as specified by a string argument following this command. If no argument is given, this command is ignored without prompt. Loaded nodal spots may be used in indexing. See spot file for details on its file format.

11.1.1.19 Precognition:Input:Anomalous (A|a)

Sets or negates the flag of anomalous scattering. If a string argument of on, On, or ON is given, the flag is set to true. If a string argument of off, Off, or OFF is given, the flag is reset to false. If no argument or no recognizable argument is given, the flag is negated. Anomalous scattering flag affects the performance of the program when anomalous scattering signal should or should not be considered.

11.1.1.20 Precognition:Input:Quit (Q|q)

Exits from this menu.

11.1.2 Precognition:Spot (S|s)

This command is only activated when an image is loaded. This command has the same numerical arguments as the command Input:Spot (11.1.1.7), overall spot length, width in pixel and s-cut. This command uses these values to recognize spots in the loaded image. If some or all numerical arguments are missing, the program uses the previous values given by Input:Spot (11.1.1.7). If no previous values are given, the program defaults take effect.

If a string argument is given, the recognized spots will be saved into a file with the string as its filename. See spot file for its format. If the command is obtained from a keyboard input, existing file will not be overwritten until confirmed. If the command is from a preprogrammed script, existing file will be overwritten without warning, but a message of overwriting is printed.

11.1.3 Precognition:Profile (F|f)

This command is activated when spot recognition is successful. This command executes a procedure that learns a mean spot profile across the loaded image, and sets the overall spot length and width automatically. The learned profile parameters will be printed.

Diagnostic feature is available to save and display the learned profiles.

11.1.4 Precognition:Ellipse (E|e)

This command is activated when spot recognition is successful. This command executes a procedure that recognizes Laue ellipses on flat detector. An optional numerical argument from integers 1 through 10 specifies the resolution of image processing involved in the procedure. 1 is the default.

Diagnostic feature is available to save and display the recognized ellipses.

11.1.5 Precognition:Nodal (N|n)

This command is activated when ellipses are recognized or loaded. This command recognizes nodal spots and sorts them according to their significance. This command also refines direct-beam center. If a string argument is given, the recognized nodal spots will be saved into a spot file with the string as its filename. If this command is issued from a keyboard input, an existing file will not be overwritten until confirmed. If this command is obtained from a preprogrammed script, an existing file will be overwritten without warning, but a message of overwriting will be printed. The saved file of nodal spots can be edited and loaded in by Input:Nodal for indexing. See spot file for its format.

11.1.6 Precognition:Pattern (P|p)

This command is activated when some nodal spots are recognized or loaded. This command executes a procedure of indexing and refinement. A string argument of filename of a spot file is virtually always necessary, although it is legal to omit the filename. Predicted spots will be saved into this file in order to validate the indexing. See spot file for its format. A geometric parameter file will also be saved if a string argument is given. Its filename is chosen as the spot filename suffixed by .inp. This parameter file is a legal command script that can be loaded back into the program so that all parameters will be restored. See the beginning of 11.1 for loading a command script.

This command may take two integer arguments m and n. If the first integer m is positive, the indexing procedure will keep searching until m solutions are found or until its natural end. If m is 0 or negative, the procedure will search all possible solutions until its natural end. The default is 1. If m > 1, more spot files of prediction and parameter files, but no more than 9, will be saved. The extra filenames are prefixed by 1_, 2_, …, m-1_.

The second integer n has its legal values from 8 through 16. The default is 8. The first n nodal spots will be used in indexing procedure. Nodal spots recognized by the command Nodal are sorted by significance. User supplied nodal spots shall be sorted by the user before loading. No sorting will be done by the program.

11.1.7 Precognition:Limits (L|l)

This command is activated when spot recognition is successful. This command detects a number of soft limits at very early stage of the data processing, such as resolution limit, reliable resolution for geometric refinement, Bragg angle limit, maximum spot density, best s-cut, and an estimate of l-curve. These quantities are called soft limits, since they often do not have definite values. At early stages of the data processing, they are even more uncertain. This command provides early estimates to these limits as accurate as they can, so that users do not have to rely on their experience to much. Good estimates to these soft limits well guide the data processing away from possible troubles.

If this command is executed before an image is indexed. Any information related to l-curve is arbitrary. Information of l-curve becomes valid only when an image is indexed or its parameter file from previous indexing is loaded. This command may accept a string argument as a filename of the estimated l-curve from 0.25 to 2 Å if no numerical argument is given. If one or two numerical arguments are given with a string argument, they specify a wavelength range for the estimated l-curve. If one number is given, it is l_max. If two are given, they are l_min and l_max with no specific order.

11.1.8 Precognition:Dataset (D|d)

This command enters a submenu for choice of several control options. When exiting from the submenu, a procedure loops through a set of images and processes them. The methods of processing fall in two categories, geometric refinement or spot integration. The dataset is defined by a user supplied parameter file and a goniometer setting file or a series of repetition of Input:Goniometer. It may also defined by loading a series of parameter files.

Diagnostic options are available.

11.1.8.1 Mode of processing

This command accepts an optional string argument that specifies a method of processing, called mode. These modes are listed below:

normal, Normal, or NORMAL

This is a mode of geometric refinement. The is the default when no string argument is given. Also when a non-recognizable string is given, this mode will take effect with a warning message. A set of images will go through geometric refinement. The initial geometric parameters of each pattern are taken from the first pattern via a user supplied parameter file. This mode does not tolerate any failure of refinement, not even a drop in quality of refinement. The procedure will be terminated if it happens. A message will report the point of quit. A set of parameter file will be generated or overwritten without confirmation. The filenames are automatically chosen as the image filename suffixed by .inp. This mode is capable of processing well behaved images.

progressive, Progressive, or PROGRESSIVE

This is a refinement mode that is the same as normal mode except that the initial parameters are taken from the last refined pattern. Under this mode, some parameters may drift away, when the refinement goes on from frame to frame. If the procedure detects losing crystal orientation, or for whatever reason, a pattern is not refined as well as the previous ones. A random-walk algorithm will be launched to trace back the orientation. If this is not successful, the pattern will be re-indexed using spots close to the known nodal positions. It assumes that although the orientation is lost, it is not very far away. If this second attempt is not success, the pattern recognition procedure is desperately restarted from the very beginning. Ellipse and nodal recognition will be executed automatically followed by indexing and refinement. If any of the attempts succeed, the processing will go on, otherwise, it will be terminated. This mode is capable of processing images from decaying protein crystals and occasional slipping crystals.

drunk, Drunk, or DRUNK

This is a refinement mode that is the same as progressive mode except that the random-walk algorithm is invoked before each refinement. The step size and the total steps of the random-walk are automatically determined according to the success of better fits or lack of them. The parameters from the best fit will serve as the initials of the geometric refinement. This mode is more suitable to process images from frequently jumping crystals in time-resolved studies.

calibration, Calibration, or CALIBRATION

This is a special refinement mode that can be used to calibrate crystal-to-detector distance and cell constants. No other parameter can be calibrated. Any parameter to be calibrated must be fixed first, that is, its uncertainty is reset to 0. Known values of these variables can be assigned. This mode of refinement will adjust the parameters to be calibrated from their initial values to the assigned values and fix them at the assigned values. In the mean time, any error caused by the calibration will be redistributed to other free parameters. This mode is useful when a parameter is changed too much beyond its trusted range by previous refinement, and one would like to trace it back to a known value.

final, Final, or FINAL

This is a refinement mode. The initial values of each pattern under this mode come from its own parameters. This behavior differs from that under normal and progressive modes, but is the same as that of calibration mode. This mode is used at a final stage of geometric refinement as its name suggests, but this stage may not always necessary. One may choose to use a higher resolution limit and a wider wavelength range for this mode to finalize the refinement.

integration, Integration, or INTEGRATION

This is a generic mode of spot integration. This mode is not defined yet in the latest release.

box, Box, or BOX