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