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

X-GEN

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

NAME

X-GEN - integrate  

SYNOPSIS

integrate [-dghjklnpqsuvxz] [-a<val>...] [minfm] [maxfm] [resmi] [resma]  

DESCRIPTION

"integrate" is the backbone of X-GEN in that it is responsible for actually determining the integrated intensities of Bragg reflections appearing in a contiguous string of images. It is always run after having determined the size of the unit cell and its orientation with respect to the laboratory axes through the "refine", "refine1", or "refall" functionality. It reads in a series of detector images and does a three-dimensional integration of the intensities of the Bragg reflections contained in them. The integrations are performed in four ways:
(1) 3-D profile fitting in local diffraction vector coordinates;
(2) 3-D profile fitting in native (X,Y,omega) coordinates;
(3) simple summation in local diffraction vector coordinates;
(4) simple summation in native (X,Y,omega) coordinates.

As the integration proceeds, the three-dimensional model profiles, the background estimate under each pixel, and the unit cell and orientational parameters are adjusted or refined periodically. After integration is complete, "integrate" will go back through the integrated reflections and determine the distribution of <I/sigma> values within the data set, as is done in the "anal_u" application (q.v.). The results of this analysis will be printed to the log file.

In keeping with the current X-GEN approach of "smart defaults," the default behavior of the code will in some cases depend on the type of detector employed in data collection.  

OPTIONS

-d If this Boolean is on, each data frame will be gzipped after
the program is finished processing it. Note that this option has changed since X-GEN V.4.0, where it specified that the image would be deleted after the program was finished with it.
-g If this Boolean is on, the program will NOT re-scale the
intensities based on the exposure time as stated in the image headers. This is sometimes necessary if those exposure times are bogus or if the data are being collected in constant-dose mode. Note that -g followed by a number has a different meaning, as specified below.
-h Causes the output to exclude reflections in specified
resolution ranges. Typically this would be used to eliminate reflections in ice-rings. The file containing the resolution ranges to be eliminated is specified with the environment variable ICERING. Each line contains a lower and an upper resolution value in Angstroms, e.g.
3.67 3.63
2.24 2.20
1.93 1.89
1.48 1.44
This would cause "integrate" to refuse to do intensity calculations for reflections with D spacings between 3.67 and 3.63 Angstroms, between 2.24 and 2.20 Angstroms, etc.
-j Invokes jagged mode, in which the initial background image
is not smoothed before use. Otherwise, the initial background image is smoothed before use. This flag is irrelevant if an old background image is read in. Note that -j with a numeric argument has a different meaning: see below.
-k If this Boolean is on, we keep the original model
profiles, i.e. we do not update them during integration.
-l If this Boolean is on, the program will NOT perform a
deadtime-loss correction based on proportional-counter- style deadtime loss statistics. Thus it should be on for instruments like CCD's, SIT tube systems, and image plates that do not have global deadtime problems; it should be off for proportional-counter systems.
-n If this Boolean is on, the program will compute a new
initial background image before beginning integration, even if a "BGIMAGE" file already exists. If this flag is off, the old background image, if one is present, will be used as the starting point for the new integration. This flag is on by default for image-plate and CCD data; it is off by default for Xentronics, FAST, and SDMS data.
-p This specifies that the background values will be computed by
fitting least-squares planes to the data within the (X,Y) neighborhood around, but not contained in, this reflection. The calculation excludes pixels that "belong" to other reflections as well. This flag is on by default for image-plate and CCD data; it is off by default for Xentronics, FAST, and SDMS data.
-q If this flag is on, the integrations will be carried out
using the polarization formula appropriate to a system with fully polarized input radiation and the rotation axis parallel to the normal to the polarization plane, i.e. the rotation axis perpendicular to the plane of polarization. This corresponds to a polarization fraction of 1 and a psi angle of 0. The default behavior of the program with respect to polarization is described below.
-s If this Boolean is on, a modest amount of additional
diagnostics beyond the default will be written to the XLOG log file and stdout.
-u If this flag is on, the integrations will be carried out
using the polarization formula appropriate to a completely unpolarized input, as from a nickel-filtered or Franks-mirror system. The default behavior of the program with respect to polarization is described below.
-v If this Boolean is on, an enormous amount of additional
diagnostics beyond the default will be written to the XLOG log file and stdout.
-x If this flag is on, the integrations will be carried out
using the polarization formula appropriate to a system with fully polarized input radiation and the rotation axis perpendicular to the normal to the polarization plane, i.e. the rotation axis IN the plane of polarization This corresponds to a psi angle of 90 and a polarization fraction of 1. The default behavior of the program with respect to polarization is described below.
-z This specifies that the background values will be highly
correlated along a vertical direction. This has some influence on how background values are estimated. This flag should be specified for data from Siemens detectors; it should probably be left off for other detector types. Note that -z followed by a number has a different meaning, as specified below.

Switches: a,b,c,e,f,g,i,m,o,r,t,w,y,z

-a<val> This specifies the angle psi, in degrees, between the
normal to the polarization plane and the rotation axis. On a storage ring, this plane is horizontal and the normal to it is vertical, so this angle is zero if the rotation axis is vertical and 90 degrees if the rotation axis is horizontal. Default value: 0. The default behavior of the program with respect to polarization is described below.
-b<val> This specifies the number of frames over which the initial
background image will be computed. Default value: 16 (for Xentronics, SDMS, or FAST data); 8 (for IP and CCD data), or the number of images in the FRAMES file--whichever is smaller.
-c<val> This specifies the minimum value of I/sigma used in
the on-the-fly refinements performed during integration. The default value for this parameter is 11 for IPs and CCDs, and 8 for most other types of detectors.
-e<val> If this value is provided, it specifies the number
of analog-to-digital units per photon (adu/photon, or "counts per photon") used in calculating the standard deviations. If no value is provided, a standard value appropriate to the instrument type is used: For FAST detectors, post-1992 Argonne CCDs, Mar IPs, and Siemens CCDs, this value is 4. For R-Axis and MacScience IPs, it's 5. For APS1 and APS2 CCDs, it's 4.5. For Mar CCDs (all sizes), and for ADSC Quantum 210's and 315's, it's 1.8. For Bruker CCD's, it's 3.8. For all other detectors, it's 1.
-f<val> This specifies the fraction of intensity allowed to be
found outside the frames integrated. Thus a value of 0.01 here causes at most 5 frames to be integrated if the widest model profile has less than 0.01 of its total intensity outside the center-most 5 frames. Default value: 0.015
-g<val> This turns ON the values of various Boolean flags. Since
there are more than 26 options to the "integrate" functionality, it is necessary to bundle some of these options in these ways. In the table below, notations like !-k indicate that the flag is equivalent to the complement of the -k flag. The specific Booleans that can be turned on with a -g call are:
Num-
ber
Mean-
ing
Equiv-
alent
Num-
ber
Mean-
ing
Equiv-
alent
1 jagged mode -j 2 Update model profiles !-k
3 deadtime loss correct. !-l 4 Correlation along Y -z
5 internal flag   6 Use old background !-n
7 Use plane backgrounds -p 8 No exposure time corr. -g
9 Icering corrections -h 10 Moderately verbose log. -s
11 Very verbose log file -v
Thus integrate -g8 -g10 would specify that we should _not_ correct for exposure time variations, and we should produce a moderately verbose log file.
-i<val> This specifies the fraction of the background that will
be updated with the value in the current frame. Thus specifying this value as 0.08 will cause the new background value at a given pixel to be (new background) = 0.92*(old background) + 0.08 * current data value. Default value: 0.08 for IPs and CCDs, 0.0625 for all other detector types.
-j<val> This specifies the (X,Y) RMS residual above which
detector remappings will be performed after each on-the-fly refinement. If <val> is greater than zero, the cutoff residual in pixels will be 0.0001 * <val>, and the remappings will be done independently in all the detector regions, as in the M command in refinement. If <val> is less than zero, the cutoff will be -0.0001 * <val>, but the remappings will be done using polynomial fits as in the H command in refinement.
-m<val> If this value is greater than one, it specifies a
saturation level. Specifically, it defines the minimum unreliable# counts/pixel or #adus/pixel. If a pixel has more adus than this value in it, then it is assumed to be an unreliable measurement. If three or more pixels are unreliable in this sense, the reflection is not integrated. If only one or two are unreliable in this sense, the profile-fitted value is substituted for the observed value in those one or two pixels and the reflection is output. If this value is less than one, it takes on a different meaning: it causes the variance of each reflection to be inflated by the square of a machine error term (<val>*I). Thus if this value is 0.01, then output variance = (input variance) + (0.01 * I) * (0.01 * I). Default value: In the context of the maximum pixel count, the default is 240000 for Mar IPs and R-Axis IPs; 4094 for an ancient Argonne CCD with a 12-bit output; 65000 or 60000 for others. In the context of variance inflation, the default is zero.
-o<val> This specifies the fraction of the input radiation that
is polarized. This value is 0.5 for unpolarized X-rays; it is 0.4722 for the output of a graphite monochromator; and it is near 1 for synchrotron radiation. The default behavior of the program with respect to polarization is described below.
-r<val> This specifies how often, in frames, the program will
perform a parameter refinement. Thus if this value is 35 there will be a refinement every 35 frames. Default value: 24 for Xentronics, SDMS, and Fast detectors; 12 for other detector types.
-t<val> This specifies the fraction of the dark current image
that will be subtracted from any image. Thus if this value is taken as 1., we will integrate data from (data frames - 1.0 * dark-current image). Default value: 0.
-w<val> A nonzero value <val> here directs integrate to write the
background image (BGIMAGE) out to a disk-file after every <val> frames. By default BGIMAGE is only written out after initialization and at the end of the run; specifying 100 here would cause it to be written out after every hundredth frame as well.
-y<val> This specifies the minimum value of the y component of
the diffraction vector that will be allowed to be integrated. Reflections with very small s(y) have very large Lorentz corrections and stay very close to the rotation axis, so they are difficult to integrate. Default value: 0.03.
-z<val> This turns OFF the values of various Boolean flags. Since
there are more than 26 options to the "integrate" functionality, it is necessary to bundle some of these options in these ways. As in the list under "-g", above, notations like !-j indicate the complement of what the -j flag does. The specific Booleans that can be turned off with a -z argument are the inverses of those given above for the "-g" argument.
Thus integrate -z4 -z7 would specify that we should _not_ set up high correlations along Y, and we should _not_ use plane background calculations,

Parameters: firstfm lastfm lowres highres

firstfm This specifies the first frame in the range to be
examined in determining the intensities of the spots contained therein. Default value: first frame enumerated in the frame index.
lastfm This specifies the last frame in the range to be examined
in determining the intensities of the integrate contained therein. Default value: last frame enumerated in the frame index.
lowres This specifies the low-resolution cutoff in Angstroms,
below which reflections will not be integrated. Default value: 999.
highres This specifies the high-resolution cutoff in Angstroms,
above which reflections will not be integrated. Default value: 0.
 

Polarization:

The behavior of "integrate" as regards the input beam polarization, in the absence of Booleans and switches that specifically regulate polarization, depends on an environment variable, POLARIZATION_TYPE. This environment variable (or its lower-case equivalent) may take on either numerical or alphabetic values with the following meanings: 0 means no polarization; 1, "mi", or "u" means unpolarized radiation (e.g. mirrors); 2, "g", or "mo" indicates a graphite monochromator; 3 or "s" means an insertion-device storage-ring beamline with a horizontal rotation axis; 4 or "sv" means an insertion-device beamline with a vertical rotation axis; 5 means a bending-magnet beamline with a horizontal rotation axis; and 6 means a bending magnet with a vertical rotation axis.
Thus the polarization parameters of the run will be set according to the value of this environment variable. If the environment variables POLARIZATION_TYPE and polarization_type have not been set, then condition one (unpolarized) is used.
 

EXAMPLES

integrate
Integrate all the data in a dataset, using default settings of
all parameters, covering all resolution ranges reachable on the detector, and using the polarization formula defined by the the POLARIZATION_TYPE environment variable:
integrate -sr17 5 135
Integrate just images 5 through 135, refining
the parameters every 17 images, and printing a moderately verbose log file:
 

REPORTING BUGS

Report bugs to Andy Howard at howard@iit.edu or 312-567-5881.  

COPYRIGHT

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


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
Polarization:
EXAMPLES
REPORTING BUGS
COPYRIGHT

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