fitpatches(1)                                                    fitpatches(1)

       fitpatches - manage and fit to patch vector files for supermontaging

       fitpatches  options  supermontage_info_file

       Fitpatches is a Python program that assists with the evaluation and
       editing of patch vector files produced by Edgepatches and provides
       information on aberrant vectors to Stitchalign.  It uses Refine-
       match(1) to fit a single linear transformation to the original patch
       vectors and produce a set of "reduced" vectors with the often large
       linear component removed.  The resulting patch vector file retains the
       correlation coefficients originally produced by Corrsearch3d.  The
       program also runs Findwarp on these reduced vectors and shows the
       mean and maximum residual and outlier information provided by fitting
       in Findwarp.  The resulting patch vector file contains a residual
       value for each vector and a value for the fraction of fits on which the
       vector was excluded as an outlier.  This file will be used by
       Stitchalign to determine which vectors to exclude as outliers or
       because of their high residuals.  Fitpatches also manages making vector
       models from the patch files when the latter are newly derived, and con-
       verting vector models back to patch files after they have been edited.

       The files managed by this program have the following names:
       edgename.patch         -  Original patch vectors with CCCs
       edgename_ccc.mod       -  Original vector model with CCCs
       edgename_reduce.patch  -  Reduced patch vectors with CCCs
       edgename_reduce.mod    -  Reduced vector model with CCCs
       edgename_resid.patch   -  Reduced vectors with residuals/outlier fractions
       edgename_resid.mod     -  Reduced vector model with residuals

       The program is designed to perform appropriate operations after you
       edit any one of the patch vector models.  Specifically, each time it is
       run, it first determines whether the vector model corresponding to each
       of the three kinds of patch files has been edited; i.e., whether it
       contains fewer vectors than the current patch file does.  If so, that
       vector model is converted back to a patch file, and the current file is
       saved as a backup by adding "~" to its name.

       Next, the program determines whether to make new reduced vectors from
       the original vectors.  It will do this if the reduced vectors do not
       yet exist, or if the original vectors have been edited while the
       reduced vectors have not been edited, either now or on a previous run
       of the program.  In other words, once you have edited the reduced vec-
       tors with CCCs, they are protected from being overwritten.  When the
       program makes a new set of reduced vectors, it will also make a vector
       model from the patch file.

       Finally, the program always runs Findwarp to make a new set of vec-
       tors with residual and outlier information.  The input patch vectors
       for this are either the reduced vectors or the existing set of vectors
       with residuals.  The reduced vectors are used if the vectors with
       residuals do not exist yet, or if the vectors with residuals have not
       been edited yet and the reduced vectors are new in some manner (i.e.,
       have just been edited, or have just been produced from the original
       vectors).  Otherwise, the residual vectors themselves are used as input
       to Findwarp to make a new set of vectors with residuals.  In other
       words, once you have edited the vectors with residuals, they will not
       be overwritten by running Findwarp on the reduced vectors.  After
       running Findwarp, the program makes a new vector model from the
       patch file.

       If you go back to Edgepatches to make new original patches,
       Edgepatches will remove the entries for the derived patches from the
       supermontage info file, and Fitpatches will make new patch files uncon-
       ditionally when you run it again.

       You should run Fitpatches immediately after Edgepatches, and also
       after any editing of the vector models, to ensure that Stitchalign
       has up-to-date information on the residuals and outliers.  You are free
       to edit any of the vector models in any sequence, but there is no rea-
       son to edit the original vectors, since it is easier to see problems in
       reduced vectors.  It is probably more useful to edit the patches with
       residuals than the reduced patches with CCCs.  If you do want to edit
       both kinds of patches, it is recommended that you first edit the
       reduced patches with CCCs, then run Fitpatches to make new patches with
       residuals, then edit the patches with residuals.

       Edgepatches 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.

       -info (-i) OR -InfoFile   File name
              Name of a supermontage info file in which all data about files
              is be stored.  It will be read in when the program starts, and
              renamed to filename~ before writing a new version when the pro-
              gram exits.  If this option is not entered, the first non-option
              argument will be taken as the name of the info file.

       -xrun (-x) OR -XRunStartEnd    Two integers
              Starting and ending frame number in X for patch files to analyze

       -yrun (-y) OR -YRunStartEnd    Two integers
              Starting and ending frame number in Y for patch files to analyze

       -zrun (-z) OR -ZRunStartEnd    Two integers
              Starting and ending Z value for patch files to analyze

       -target (-t) OR -TargetMeanResidual      Multiple floats
              One or more mean residual values to try to reach when Find-
              warp(1) searches for the best warping.  Multiple values should
              be entered in increasing order.  Findwarp will try to find a
              warping with the largest number of included patches that gives a
              mean residual below the first value; then it tries again with
              the second value, etc.  The default values are designed to pro-
              duce a successful fit even with rather bad patches.

       -clip (-c) OR -ClippingPlaneBoxSize      Integer
              Four clipping planes will be added to the reduced and residual
              models to allow a small square of the patch vector model to be
              viewed in isolation.  Use this option to change the size from
              the default of 600 pixels.

       -scale (-s) OR -ScaleFactor    Floating point
              Factor for scaling vectors in reduced and residual models.  The
              default is 10, is is used for vectors when combining tomograms.
              Note that the original vectors are always scaled by 5 in
              Edgepatches because they tend to be so long.

       -rescale (-r) OR -RescaleModels
              Remake the reduced and residual models with the current scale

              Read parameter entries from standard input

       The files managed by the program are listed above.  Every time the info
       file is modified, the existing copy is renamed to a backup with the ~

       David Mastronarde

       corrsearch3d, edgepatches, patch2imod, imod2patch,

       Email bug reports to mast at colorado dot edu.

BL3DEMC                              4.7.3                       fitpatches(1)