refinematch(1)                                                  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.

       -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 (-pr) 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).

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



BL3DEMC                              4.7.3                      refinematch(1)