Makeshoe: make shoebox files
The first step in integrating data using "evalccd" is to make
so-called shoe box files: for each reflection a 3-dimensional box of
intensities (x,y,framenumber) is written to a file with a number of
associated variables. The resulting shoe box files can later be integrated
using the evalall program.
Usage
The makeshoe program can be called as follows:
makeshoe [options] [.rmat filename] [kcdfilenames or directory name]
The "kcdfilenames" can be standard KCD files or compressed KCD files
(recognized by the extension .Z, .gz, or .bz2) or any mixture.
Alternatively, a directory name can be specified, and all kcd files in
that directory will be used. If no directory and no filenames are
given, all kcd files from the current directory will be used.
Only one .rmat file name should be specified. Interfering lattices
can not yet be specified via the command line, they must be introduced
via the GUI.
Command line options are:
- nogui
-
If "nogui" is specified, the program does not show a
GUI to change input values.
- norun
-
If "norun" is specified, the program will create all input scripts for the
"view" program that does the actual creation of the shoe box files, but
the "view" program will not be started.
- noplot, plot, plotall
-
If "noplot" is specified, the shoe box creation will not be displayed
on the screen. If "plot" is specified, one in every 10 frames will be
shown. Using "plotall", all frames will be displayed.
- scanrmat
-
Enables per-scan .rmat files to compensate for a slipping crystal.
The .rmat files that are read are named like "s01f_i.rmat" (i.e. they
are prefixed with the scan prefix and an "_" character. These files
can be created using the "xtalorient" option of the postrefine program. The default setting for
this option can be set in the configuration file.
- noscanrmat
-
Disables per-scan .rmat files.
- shoedir=dir
-
By default, the shoe box files will be created in a subdirectory of
the current directory. The name of this subdirectory is constructed
from the name of the "rmat" file with the cell and twin-cell. If the
shoe box files should be created somewhere else, this target directory
can be specified using this option.
- perfile=n
-
The makeshoe program will normally create a new shoe box file every 1000
reflections. If you want a different number, this can be specified using
the "perfile" option (eg: "perfile=2000").
- shoecompress
-
If the "shoecompress" option is specified, all shoe box files will be
compressed after being completed.
- preref
-
Pre-refine the detector position before making the shoe box files. This
is done on a per-scan basis using the preref program.
- datcolboxes=n
-
Show the generation of shoeboxes 'n' frames before and 'n' frames
after the central frame (only affects the visualization). Valid values
for 'n' are 0, 1 and 999.
- thmin=f, thmax=f, resolution=f,f
-
Set the resolution bounds in Angstrom (or theta limits in degrees).
Using the "resolution=" keyword argument it is only possible to change
both the upper and lower resolution limits at once.
All command line options except for "nogui" and "norun" can also be
set from the GUI, so normally there is no need to specify any command
line options at all.
Operation
After the program is started, a dialog is shown with all parameters
relevant to the generation of the shoe boxes.
The variables are:
- Orientation matrix file
-
The name of an "rmat" file should be given that contains the orientation
matrix of the unit cell.
- Twin orientation matrix files
-
If there are interfering lattices, the names of the files containing
the orientation matrices should be given here, separated by spaces. If
there is no interfering lattice, this should be left empty.
- Minimal diffraction angle theta
-
The lowest theta at which reflections will be integrated. Low order reflections
might (partly) disappear behind the primary beam stop, invalidating the
integrated intensity.
- Maximal diffraction angle theta
-
Integrating beyond where the crystal diffracts will cost much CPU time.
A reasonable diffraction limit should be given here.
- Depth of the shoeboxes
-
The number of frames that a reflection is followed. Should be an odd
integer. Normally 5 is enough, but if your slices are very thin or the
mosaicity is high, increasing this number might be necessary to make
sure that there is a "background" image on both sides of the
reflection.
- Size of the shoeboxes
-
Number of pixels horizontally and vertically that are included in each
shoebox. This should be clearly larger than the largest spot size (the
integration needs a few background pixels on each side). Increasing
the value too much will dramatically increase the size of the shoe box
file and slow down the integration. A too small value will result in
reflections with error flags.
- Graphical display
-
The shoe box generation can be visualized. If the "graphical display"
is set to "All", all images will be shown with all reflections on
there. If it is set to "Some", every 10th image will be shown. If it
is set to "None", no images will be shown, and in fact no image
display window will pop up at all. The default is set to "Some", such
that severe problems can be spotted before the actual integration
step. Setting it to "All" significantly slows down the shoe box
generation and is only advised for problem tracing or instruction.
- Display boxes
-
In the visualisation window, pixels that are copied into shoe boxes
are outlined by boxes. Using this option the amount of boxes can be
controlled a bit. If it is set to "Central", only the central plane of
the shoe box, that is expected to contain the (main part of) the
reflection, is drawn. If it is set to "Central+1", the frame just
before the central and just after the central frame are also outlined
in a different color. If set to "All", all planes that are copied to
shoe boxes are outlined.
The default value is "Central+1", which normally gives a reasonable
compromise between coverage (not too many reflections are visible
outside boxes) and image load (not too many boxes are shown).
Under "More options" a number of expert variables can be found:
- Minimum Zeta
-
Reflections that are close to the rotation axis have very high Lorentz
factors, and can be difficult to integrate properly. They can be left
out here. A proper strategy made using "collect" will re-measure these
reflections in another spot.
- Suppress text output
-
If set to "Yes" (the default) all debugging output by the program is
suppressed.
- Shoebox file compression extension
-
This can be set to ".bz2", ".gz", or ".Z" to compress each shoe box
file using the appropriate program immediately after it is created.
- Directory for shoebox files
-
Normally the shoe box files are created in a directory that is
constructed from the names of the orientation matrix files. If this
automatically determined location is not the desired one, and alternative
directory can be specified here. Should normally be left blank.
- Number of reflections per shoebox file
-
Every 1000 reflections by default a new shoebox file is opened. This is
to prevent huge shoebox files (they are sequential access, so if you need
reflection number 9999 you will need to read and skip 9998 earlier
reflections, very time consuming!). There should be no need to change
this number.
- Prerefine detector position per scan
-
If "YES", runs the preref program for each
scan to refine the detector position before running the shoe box
generation. This may help to get all reflections close to the center
of the shoe box.
- Use per-scan .rmat files
-
Expert option that can help if the crystal is moving during the measurements.
This accompanies an option in the postrefine
program that can determine a unit cell orientation for each scan. This should
otherwise never be used.
When the values are confirmed using the "Ok" button, a new dialog pops up
asking which of the sets of KCD files that were found on disk should be
read:
Unwanted scans can be deselected using the check boxes on the left.
When this dialog is closed using "Ok", the program will scan the disk files,
and create the input files (named datcol*.vic) for the "view" program. It
will then invoke the view program to create the actual shoe box files.
If image display is requested, the shoe box generation can be followed
on the screen. The "view" program will pop up a window showing its progress.
The two circles represent the minimum and maximum resolution cutoffs.
The hourglass-shaped curve delineates the area of reflections below the
zeta-limit: reflections seen inside the top and bottom area's will not
be considered (integration of the few reflections that occur in this
area would be relatively inaccurate. The strategy calculation in
"collect" already takes this exclusion zone into account so all
reflections should also appear in a more favorable location).
The following color coding is used to display the shoe boxes:
- If integrating a single lattice:
- Dark yellow: The center of the reflection is predicted 2 or more images
past the current one.
- Light yellow: The center of the reflection is predicted in the next image.
- White: The center of the reflection is predicted in this frame. The white
boxes should contain the bulk of the reflection, certainly if the
data set is widely sliced.
- Light blue: The center of the reflection is predicted in the previous image.
- Dark blue: The center of the reflection is predicted 2 or more images
before the current one.
- If integrating two lattices:
- Light red: The center of the reflection in the primary lattice is
predicted in the current image.
- Darker Red: The center of the reflection in the primary lattice is
predicted in one of the previous or one of the following frames.
- Light green: The center of the reflection in the secondary lattice is
predicted in the current image.
- Darker Green: The center of the reflection in the secondary lattice is
predicted in one of the previous or one of the following frames.
