autopatchfit(1)             General Commands Manual            autopatchfit(1)



NAME
       autopatchfit - Run 3D patch correlation and fitting iteratively

SYNOPSIS
       autopatchfit  options  tiltalign_command_file

DESCRIPTION
       Autopatchfit will run 3D patch correlations then fit transformations to
       the patch displacements, repeating the process with increasing patch
       size and possibly increasing density until a desired fitting error is
       achieved.  It is designed to be used as part of the tomogram combina-
       tion process.  Thus, it works with the command files "patchcorr.com"
       (to run Corrsearch3d) and "matchorwarp.com" (to run Refinematch
       and Matchvol or Findwarp and Warpvol via Matchorwarp).  It
       relies on those files already having a number of of the options needed
       for optimal automated patch fitting, as set up by Setupcombine with
       the -autopatch option.  As in Setupcombine, the thickness dimension
       is referred to as Z when specifying sizes, but is assumed to be the Y
       dimension in the actual tomograms.

       The program will start with the patch size and number already specified
       in "patchcorr.com", and when fitting fails, it will increase the patch
       size up to the size specified in the -final option.  It may also adjust
       the patch number to a standard spacing when increasing the size.  If
       the patchcorr.com file has an entry for initial shifts, the program
       will do a second trial with the final patch size but with double the
       patch density in X and Y, and higher density in Z also.  The logic here
       is that the initial shift is a sign of high warping between the tomo-
       grams, which may be fit better with much denser patches.  This default
       behavior can be modified with the -high option.

       If the starting and final patch sizes match two of the stock sizes rep-
       resented by the letters S, M, L, and E, the program will step through
       these fixed sizes.  Otherwise, it will increase patch size in each
       dimension by the same factor on each trial, where 1.25 is the target
       value of the factor, but the number of steps is rounded up to keep the
       factor from exceeding ~1.3.  However, patch size in Z will not be
       increased above two-thirds of the range allowed by the Z limits for
       patch correlation if there is more than one patch in Z.

OPTIONS
       Autopatchfit 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.

       -final (-f) OR -FinalPatchTypeOrXYZ      Text string
              Largest patch size to try.  Enter a letter to indicate the size
              of patches, or three numbers for the desired size in X, Y, and
              Z.  The sizes available by letter are S for small (64x32x64), M
              for medium (80x40x80), L for large (100x50x100), or E for extra
              large (120x60x120).

       -extra (-e) OR -ExtraResidualTargets     Text string
              Extra target residual values for Findwarp in final trial.  These
              values should be higher than any of the ones present on the
              -warplimit entry in matchorwarp.com.  However, if they are
              already present at the end of the existing list, they will be
              removed for the earlier trials.

       -high (-hi) OR -HighDensityFinalTrial    Integer
              Enter -1 to prevent a higher density final trial even when
              "patchcorr.com" has initial shifts, or 1 to make it happen even
              without the initial shifts.

       -trial (-t) OR -TrialMode
              Run Matchorwarp with -trial option to stop before
              Matchvol/Warpvol

       -skip (-s) OR -SkipFirstPatchcorr
              Skip the first run of patchcorr and work from existing patches.
              There is no check that the existing patch.out is based on the
              correct patch size; this option is purely for testing.

       -help (-he) OR -usage
              Print help output

       -StandardInput
              Read parameter entries from standard input

FILES
       The initial patchcorr.com and matchorwarp.com will become backup files
       patchcorr.com~ and matchorwarp.com~.  After a fitting fails, except on
       the final step, the patch.out file will be renamed patch_NXxNYxNZ.out,
       where NX, NY, NZ are the sizes in X, Y, and Z.

AUTHOR
       David Mastronarde

SEE ALSO
       corrsearch3d, matchorwarp, refinematch, matchvol, find-
       warp(1), warpvol, setupcombine

BUGS
       Email bug reports to mast at colorado dot edu.



IMOD                                 5.2.0                     autopatchfit(1)