Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells
FINDGRADIENT(1) FINDGRADIENT(1)
NAME
findgradient - Finds mag gradient that minimize montage blending error
SYNOPSIS
findgradient [options]
DESCRIPTION
Findgradient finds parameters related to magnification gradients that
minimize the displacement errors when Blendmont shifts pieces into
registration. When the illumination in the microscope produces a
significant gradient in magnification with changing Z height, montages taken
at high tilt do not fit together well. The error in the overlap zones,
after shifting pieces into registration, can be several pixels. Correcting
for the gradient can reduce the error to a fraction of a pixel. Thus, the
parameters of the gradient can be found by adjusting them to give minimum
error. The two gradient parameters are the percent change in magnification
and the degrees of rotation per micron of Z height change. The other
parameter that affects the Blendmont error is the effective tilt angle for
the corrections, which can differ from the nominal tilt angle by several
degrees.
Findgradient can be run in three different modes, corresponding to the
number entered with the SearchType option. Two of these modes would be used
when measuring mag gradients from a set of calibration montages, and the
third would be used to adjust the tilt angles for an individual tilt series
to give optimum correction.
For calibrating gradients, it is recommended that montages be taken at a
single intensity at extreme positive and negative tilt angles (e.g., -60,
-50, 50, and 60 degrees). Then montages would be taken at one extreme angle
and a series of intensities. The first step in the analysis would be to run
Findgradient on the sections taken at the same intensity and over a range of
angles, computing the error from all of those sections together and
searching for both the magnification gradient and the best offset to the
tilt angle (SearchType 3, RunSeparately 0). Then take the tilt offset from
the search and specify it in the OffsetTilts entry, and search for the
magnification gradient separately for all of the sections at the extreme
angle (SearchType -2, RunSeparately 1).
To find the best tilt offset for an individual tilt series once the mag
gradients have been calibrated, select two or three views from each end of
the tilt series. Select views where Blendmont does not have any difficulty
finding the displacements in the overlap zones, which may not be the case at
the very highest tilt. Run Findgradient to analyze all of these sections
together and search for the tilt offset only (SearchType -1 or 1,
RunSeparately 0). The mag gradient file must also be specified with
GradientFile.
At the end of the search for each section or group of sections, the program
prints a summary of the number of iterations in the search, the final error,
and the gradient values. The latter values are in addition to any initial
gradient specified by a gradient file, so they would be entered into
Blendmont with the AddToGradient option.
Some of the options to Findgradient are passed directly to Blendmont. If
there are additional options that need to be used when running Blendmont,
they can be specified with BlendOption entries.
Findgradient uses the PIP package for input exclusively (see the manual page
for pip). The following options can be specified either as command line
arguments (with the -) or one per line in a command file or parameter file
(without the -):
-imin OR -ImageInputFile File name
Montaged image input file to be analyzed
-plin OR -PieceListInput File name
File with list of piece coordinates for image input file.
-rootname OR -RootNameForFiles Text string
Root name for temporary files. The program will append -fg and the
starting and ending section numbers to create the full root name. This
name is used for the input parameter file (.param), files for image output
and text output from Blendmont (.imtmp and .out), and the files created by
Blendmont for edge functions (.xef, .yef) and edge correlations (.ecd).
-distort OR -DistortionField File name
Image distortion field file to use for undistorting images. The
undistortion is applied when computing edge functions.
-imagebinned OR -ImagesAreBinned Integer
The current binning of the images, so that the image distortion field can
be applied correctly. This entry is required when doing image distortion
corrections unless the program can determine the binning unambiguously
from the image size.
-gradient OR -GradientFile File name
File with magnification gradients for each section; the minimization will
determine the amounts to be added to these gradients. This should be a
file listing the tilt angle, the percent magnification change per micron
of Z height, and the degrees of rotation per micron of Z height for each
section, such as is produced by Extractmaggrad.
-adjusted OR -AdjustedFocus
Focus was adjusted for changing Z height when montage was acquired
-addgrad OR -AddToGradient Two floats
This option provides starting values for the minimization. The reported
gradient is not incremental to these values, unlike when a gradient file
is entered. The magnification gradient correction is specified by two
parameters: % of mag change per micron of Z height, and degrees of
rotation per micron of Z height. If -gradient has been entered, the
values entered here will be treated as incremental to the values in the
gradient file for each section. If -gradient has not been entered, the
values entered here will be used for all sections; but in this case the
-geometry option must be entered to provide additional information.
-geometry OR -TiltGeometry Three floats
This entry can be used in place of a gradient file to specify the pixel
size in nanometers, tilt axis rotation angle, and tilt angle to be used
for the gradient computation. The entry has no effect if a gradient file
is provided.
-tiltfile OR -TiltFile File name
Name of file with tilt angles, one per line. These angles will be used
only if there is no mag gradient file to supply the tilt angles.
-offset OR -OffsetTilts Floating point
Add the given value to the tilt angles from the gradient file or the tilt
file. For a search of 1 or 3 parameters, this value will be used as the
starting value for finding the best offset.
-sections OR -SectionsToDo List of integer ranges
List of sections on which to minimize overlap errors; comma-separated
ranges are allowed. The mean error over all of these sections will be
minimized unless the -separate option is included, in which case the
procedure is run separately on each section.
-separate OR -RunSeparately
Run minimization separately on each section, instead of combining the
errors from all sections. With this option, the list of sections must be
specified with -sections.
-search OR -SearchType Integer
Enter 1 or -1 to find just the tilt offset with a fixed mag gradient, 2 or
-2 to find the mag gradient with a fixed tilt offset, and 3 to find both
the mag gradient and the best tilt offset. The latter should be used only
when multiple sections with a big difference in their tilt angles are
searched together (not separately). The positive values do a search with
a simplex algorithm. Use -2 to find gradients with a routine that uses an
estimated gradient from Blendmont to modify the gradient until it
converges. This method is faster and seems to be slightly more reliable.
Use -1 to search for the tilt offset with a simple routine that is faster
and probably as reliable as the simplex routine.
-trace OR -TraceOutput Integer
Output values during minimization: 1 for minima, 2 for all values
-blend OR -BlendOption Text string
Option and value to pass to Blendmont. This option will be added the end
of the .param file. There is no check for whether options entered this
way conflict with the options placed into the .param file by findgradient.
(Successive entries accumulate)
-param OR -ParameterFile Parameter file
Read parameter entries as keyword-value pairs from a parameter file.
-help OR -usage
Print help output.
-StandardInput
Read parameter entries from standard input.