refinematch(1) General Commands Manual refinematch(1)
NAME
refinematch - Solve for a refined match between two tomograms
SYNOPSIS
refinematch [options] input_file [output_file]
DESCRIPTION
Refinematch will solve for a general 3-dimensional linear transforma-
tion to align two volumes to each other. It performs multiple linear
regression on the displacements between the volumes determined at a
matrix of positions. The displacements must be contained in a file
with the following form:
Number of displacements One line for each displacement consisting of
the X, Y, and Z
coordinates in the first volume, then the displacements in X, Y
and Z involved in moving from the first to the second volume
The program will automatically eliminate "outliers", patch displace-
ments that are likely to be incorrect because they are so extreme, when
compared to the rest of the displacements. This elimination is conser-
vative, but if for some reason it operates incorrectly, you can control
the parameters of elimination or stop the elimination from occurring.
The program will eliminate up to 10% of the patches. If more than this
number are bad, either get a new set of patches that do not approach so
close to the edge of the volume, make a model in the tomogram with con-
tours enclosing the patches to use, eliminate the bad ones from the
file by hand, or use Findwarp to eliminate a whole row or column of
patches. When the mean residual exceeds a value that you specify, the
program will exit with an error.
A model specifying which patches to include in the fit can be quite
simple, consisting of just a single contour enclosing the region where
patches are generally good. This contour can be drawn in any Z plane
of the flipped tomogram. However, if the good region changes through
the depth of the tomogram, you can draw contours at several Z levels.
If you have two layers of patches, draw two contours, one near the top
and one near the bottom of the tomogram; if you have three layers, add
another contour in the middle, etc. For a given patch, the program
will find the contour at the nearest Z level and use that one to deter-
mine whether to include the patch.
If there is only one layer of patches in one dimension, there is insuf-
ficient information to solve for the full transformation, so the pro-
gram will solve for only two of the three columns of the transformation
matrix. This typically occurs in the Y dimension, in which case the
second column of the matrix is fixed at 0, 1, 0.
OPTIONS
Refinematch uses the PIP package for input (see the manual page for
pip) but can still take input interactively for compatibility with
old versions of Matchorwarp. The following options can be specified
either as command line arguments (with the -) or one per line in a com-
mand file or parameter file (without the -). Options can be abbrevi-
ated to unique letters; the currently valid abbreviations for short
names are shown in parentheses.
-patch (-pat) OR -PatchFile File name
Name of input file with positions and displacements. If this
option is not entered, the first non-option argument will be
used for the input file name.
-output (-o) OR -OutputFile File name
Optional output file for the refining transformation. If this
option is not entered, the second non-option argument (if any)
will be used for the output file name.
-region (-reg) OR -RegionModel File name
Model file with contours enclosing the patches to be included in
the fit
-volume (-v) OR -VolumeOrSizeXYZ File name
Either the name of the file or the X, Y, and Z dimensions of the
volume being matched to.
-residual (-res) OR -ResidualPatchOutput File name
Output file for positions, displacements, and residual values.
If the patch input file has correlation coefficients, they will
be replaced by the residuals.
-reduced (-red) OR -ReducedVectorOutput File name
Output file for residual vectors from the fit, which represent
the vectors remaining after removing the linear component of the
vector field. These are referred to as reduced vectors. If the
input patch file has correlation coefficients, they will be
passed into this output file; otherwise the residual values will
be placed into the file.
-limit (-l) OR -MeanResidualLimit Floating point
Limiting value for the mean residual; above this value, the pro-
gram will exit with an error.
-extra (-e) OR -ExtraValueSelection Two integers
Select only patches with extra value on one side of a criterion.
The patch vector file can have additional columns of values
after the displacements in X, Y, and Z. These extra columns are
numbered from 1, and they may also have ID values on the first
line of the file indicating their type. To include patches
based on values in an extra column, enter two numbers for this
option: the ID value or the negative of the extra column number;
and 1 to select patches above the criterion or -1 to select ones
below it. You must also enter one or more threshold values with
the -select option. (Successive entries accumulate)
-select (-se) OR -SelectionCriteria Multiple floats
One or more criteria for selecting patches based on extra val-
ues. If multiple criteria are entered, the fitting process will
be repeated with each selection criterion to try to satisfy the
residual criterion. If there are multiple values being selected
on, this option must be entered the same number of times as the
-extra option and it must have the same number of criteria
entered each time. (Successive entries accumulate)
-maxfrac (-ma) OR -MaxFractionToDrop Floating point
Maximum fraction of patches to drop from the fit by outlier
elimination. Enter 0 to for no outlier elimination. The
default is 0.1.
-minresid (-mi) OR -MinResidualToDrop Floating point
The minimum residual for outlier elimination; patches with
residuals smaller than this value will be retained no matter how
extreme they are relative to the other patches. The default is
0.5.
-prob OR -CriterionProbabilities Two floats
Two probabilities controlling outlier elimination: a criterion
probability for a patch to be evaluated as an outlier (default
0.01), and a criterion probability for a patch to be eliminated
regardless of the distribution of extreme values (default
0.002).
-initial (-i) OR -InitialTransformFile File name
File with the 3D transformation that was used to create the vol-
ume being aligned. This transformation will be multiplied by
the refining transform and output in the file specified by the
-product option. The two options must be entered together. A
side-effect of using this option is that the program will report
the shift in Y (the presumed depth dimension) needed to align
corresponding patches in the center of the volumes.
-product (-prod) OR -ProductTransformFile File name
Name of output file for the product of the transform entered
with the -initial option and the refining transform.
-scale (-sc) OR -ScaleShiftByFactor Floating point
Factor by which to scale shifts in the transform written when
the -product option is given. This option is needed to get a
transformation that can be applied to an unbinned volume when
binned volumes have been analyzed.
-param (-par) OR -ParameterFile Parameter file
Read parameter entries as keyword-value pairs from a parameter
file.
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input.
INTERACTIVE INPUT
If the program is started with no command line arguments, it takes
interactive input with the following entries:
Name of file with positions and displacements
Either the file name, or the X, Y, and Z dimensions of the volume being
matched to.
Name of an IMOD model file with contours enclosing the patches to
be included in the fit, or Return to use all patches.
Limiting value for the mean residual; above this value, the program
will exit with an error.
Name of output file in which to place the transformation, or Return
for no output to a file
HISTORY
Written by David Mastronarde, 1995
12/24/98: added outlier elimination; 6/6/99: added error exit
8/21/06: converted to PIP, made it handle both orientations of volume
better, changed outlier output to be a summary as in Findwarp,
added options for controlling outlier elimination and getting
residual output.
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.2.0 refinematch(1)