matchorwarp(1) General Commands Manual matchorwarp(1)
NAME
matchorwarp - Find registration between two volumes and transform one
SYNOPSIS
matchorwarp [options] input_file output_file
DESCRIPTION
Matchorwarp runs Refinematch to attempt to find a single linear
transformation relating two volumes. If a single transformation gives
an adequate fit, Matchorwarp runs Matchvol to generate the output
file from the input file. Otherwise, it runs Findwarp to find a set
of warping transformations that relate the two volumes. If an adequate
fit is found, it then runs Warpvol to generate the input file from
the output file; otherwise it exits with an error. There are options
to run Matchorwarp in a trial mode and to exclude rows or columns of
patches, so this program can be used to explore different fits before
or instead of running Findwarp interactively.
The program can run several iterations to refine the fit. Iterating
can be helpful if there is a large degree of warping between the vol-
umes, because of inaccuracies in the initial warping and because
patches that rotate significantly in the warping should correlate bet-
ter after warping. On iterations after the first, the program will run
Corrsearch3d to find patch vectors between the currently warped vol-
ume (e.g, "setnameb_mat.mrc") and the other axis tomogram (e.g., "set-
namea_rec.mrc"). It runs the existing "patchcorr.com" but without the
initial shift entry and with the iteration number added to output file
names. Then it runs Findwarp to find the incremental warping trans-
forms, combines those with the full transforms computed on the previous
iteration, and writes new full transforms. Warpvol is then run to
compute a new warped file from the original tomogram on that axis. If
no warping is needed in the initial fit with Refinematch, no itera-
tions are run. The Findwarp output includes a line with "Patch vec-
tor length mean, SD and max:" which will indicate how well-aligned the
last warped volume was. Two or three iterations should be sufficient
to reach a point of small vectors with minimal improvement beyond that
point.
OPTIONS
Give the command "matchorwarp" without arguments to see a list of the
current defaults for many of these options. Options may be abbreviated
to the minimum number of unambiguous characters.
Matchorwarp uses the PIP package for input (see the manual page for
pip). Options can be specified either as command line arguments
(with the -) or one per line in a command file (without the -).
Options can be abbreviated to unique letters; the currently valid
abbreviations for short names are shown in parentheses.
-inputvolume (-inp) OR -InputVolume File name
Input file to be transformed. If this option is not entered,
the first nonoption argument is taken as the input volume.
-outputvolume (-o) OR -OutputVolume File name
Name of transformed file to be produced. If this option is not
entered, the second nonoption argument is taken as this name.
-size (-si) OR -SizeXYZorVolume Text string
Specifies the size of the volume being matched to; the entry can
be either the name of that file or its NX,NY,NZ dimensions.
-refinelimit (-refinel) OR -RefineLimit Floating point
The maximum mean residual that will be allowed when running
Refinematch and Matchvol.
-warplimit (-warpl) OR -WarpLimits Text string
A list of mean residuals that Warpvol will attempt to achieve
automatically. Values should be in increasing order and sepa-
rated by commas.
-structurecrit (-str) OR -StructureCriteria Text string
A list of one or more criterion values for selecting patches
based on a measure of structure contained in the patch file.
Both Refinematch and Findwarp will be run with these lim-
its for selecting patches with the structure value greater than
the criterion. In Findwarp, each criterion will be applied
at a mean residual limit before going on to the next residual
limit. The measure of structure will be the fraction of ana-
lyzed boxes within a patch with a standard deviation indicative
of a strong structure, which is saved in the patch file by
Corrsearch3d as an extra column with ID 5.
-extentfit (-e) OR -ExtentToFit File name
Minimum number of rows and columns of patches to include in each
local fit in Findwarp.
-modelfile (-m) OR -ModelFile File name
Name of a model file with contours enclosing the patches to
include in fits.
-patchfile (-patchf) OR -PatchFile File name
Name of the existing file with list of patch displacements
(default patch.out).
-solvefile (-so) OR -SolveFile File name
Name of the existing file with the initial transformation
between volumes (default solve.xf).
-refinefile (-refinef) OR -RefineFile File name
Name of the file into which Refinematch will place the refin-
ing transformation (default refine.xf).
-inversefile (-inv) OR -InverseFile File name
Name of the file into which Matchvol will place the inverse
cumulative transformation (default inverse.xf).
-warpfile (-warpf) OR -WarpFile File name
Name of the file into which Warpvol will place the inverse
warping transformations (default warp.xf).
-residualfile (-res) OR -ResidualFile File name
Name of the file into which Refinematch and/or Warpvol
will place a new list of the patches, their displacements, and
the residual from the fits.
-vectormodel (-v) OR -VectorModel File name
Name of patch vector model file to create from the residual file
with Patch2imod.
-clipsize (-c) OR -ClipPlaneBoxSize Integer
If writing a patch vector model, set up four clipping planes
enclosing a square central area of the given size.
-tempdir (-te) OR -TemporaryDirectory File name
Path name of directory into which Matchvol or Warpvol can place
temporary files.
-xlowerexclude (-xl) OR -XLowerExclude Integer
The number of columns of patches to exclude on the left side of
the volume.
-xupperexclude (-xu) OR -XUpperExclude Integer
The number of columns of patches to exclude on the right side of
the volume.
-ylowerexclude (-yl) OR -YLowerExclude Integer
The number of rows or slabs of patches to exclude on the lower Y
side of the volume.
-yupperexclude (-yu) OR -YUpperExclude Integer
The number of rows or slabs of patches to exclude on the upper Y
side of the volume.
-zlowerexclude (-zl) OR -ZLowerExclude Integer
The number of slabs or rows of patches to exclude on the lower Z
side of the volume. This would be used to specify rows on the
bottom when viewing a volume in flipped orientation.
-zupperexclude (-zu) OR -ZUpperExclude Integer
The number of slabs or rows of patches to exclude on the upper Z
side of the volume. This would be used to specify rows on the
top when viewing a volume in flipped orientation.
-linear (-l) OR -LinearInterpolation
Use linear instead of quadratic interpolation for transforming
the volume with Matchvol or Warpvol.
-trial (-tr) OR -TrialMode
Use a trial mode, in which the program exits after finding a
good fit rather than going on to Matchvol or Warpvol.
-iterations (-it) OR -IterationsToRun Integer
Number of times to run the operations of finding a warping and
warping the volume. Iterations are numbered from 1, the initial
sequence of Findwarp and Warpvol considered to be itera-
tion 1.
-stop (-sto) OR -StopIteratingCriteria Three floats
The program stops iterating if the the mean residual error from
Findwarp increases enough twice in a row, or if either the
mean or the maximum mean residual increase too much from the
prior iteration. This option takes 3 entries: the factor by
which the mean residual must increase for it to be counted as an
increase for stopping purposes (default 1.03), and the factors
by which the mean or maximum mean residual must increase for it
to stop immediately (defaults 1.25 and 2.0). When the itera-
tions are stopped through this mechanism, the program will issue
a warning that the existing "mat" file from the previous itera-
tion is still usable for combining. This stopping capability
was introduced when the wrong transforms were being written but
might still be useful for pathological situations.
-patchcorr (-patchc) OR -PatchcorrCommandFile File name
Command file for running Corrsearch3d when iterating (default
patchcorr.com)
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input
FILES
Unless optional arguments are entered, the program assumes the exis-
tence of patch.out and solve.xf. When iterating, various outputs are
numbered with the iteration number, but the usual outputs from the
first iteration are left without numbers. Warpvol is run to obtain
a filled-in warp file (with transaforms for all possible positions)
from the previous iteration. Thus, there will be a "warp-filled.xf",
"warp2-filled.xf", etc. The warped "mat" file from the previous itera-
tion is renamed before a new one is made (e.g., "set-
nameb_warp1_mat.mrc"). The original "mat" file created by Matchvol
is not renamed and will generally still exist as a backup file (.e.g.,
"setnameb_mat.mrc~"). To rerun matchorwarp, it is necessary to either
recreate this file or rename it from backup.
AUTHOR
David Mastronarde <mast at colorado dot edu>
SEE ALSO
patchcrawl3d, refinematch, matchvol, findwarp, warpvol,
patch2imod
IMOD 5.2.15 matchorwarp(1)