Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

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 transformation
  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 displacements
  that are likely to be incorrect because they are so extreme, when compared
  to the rest of the displacements.  This elimination is conservative, 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 contours 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 determine whether to
  include the patch.

  If there is only one layer of patches in one dimension, there is
  insufficient information to solve for the full transformation, so the
  program 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.

  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 command file or
  parameter file (without the -):

 -patch 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 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 OR -RegionModel   File name
    Model file with contours enclosing the patches to be included in the fit

 -volume OR -VolumeOrSizeXYZ   File name
    Either the name of the file or the X, Y, and Z dimensions of the volume
    being matched to.

 -residual 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 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 OR -MeanResidualLimit   Floating point
    Limiting value for the mean residual; above this value, the program will
    exit with an error.

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

 -param OR -ParameterFile   Parameter file
    Read parameter entries as keyword-value pairs from a parameter file.

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard 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.