xfjointomo(1)                                                    xfjointomo(1)



NAME
       xfjointomo - use model features to refine serial tomogram alignment

SYNOPSIS
       xfjointomo  [options]  input_file  output_file(s)

DESCRIPTION
       Xfjointomo computes transforms for aligning tomograms of serial sec-
       tions from features modeled on an initial joined tomogram.  This fidu-
       cial model can have two kinds of features: contours following trajecto-
       ries on either side of a boundary, and contours with one point on
       either side of a boundary.  Thus, features such as oblique microtubules
       can be used for alignment and, if trajectories at different angles are
       available, the optimal spacing between the tomograms can be determined.

       The inputs to and outputs from the program depend on how one plans to
       generate an aligned joined tomogram.  If this refinement step is done
       right after making a joined tomogram, then the results should be used
       to rerun Finishjoin, since this avoids interpolating the data twice.
       In this case, the program needs to be informed about the offsets and
       binning, if any, used to compute the joined file that was modeled.  It
       will output two transform files: one with the transforms that align
       each tomogram to the previous one (referred to as f transforms); and
       one with global transforms (g transforms) to be passed to Fin-
       ishjoin(1).  Note that the latter are not necessarily suitable for
       transforming the fiducial model into the new alignment; rather, trans-
       forms for this purpose should be obtained by running "xftoxg -n 0" on
       the output file of f transforms.  The resulting g transforms can be
       used with Xfmodel provided that the sizes of the sections are given
       to Xfmodel with the -chunk option.  When used in this mode, the pro-
       gram can run repeatedly to "edit" a file of f transforms.  For example,
       you can run it with one set of parameters and get solutions for a sub-
       set of the boundaries, then run it again with other parameters for a
       different subset of boundaries.

       The second way of using the program is with the intention of using New-
       stack(1) to transform the existing joined volume, or Xfmodel to
       transform a model on that volume.  Transforming the joined volume will
       degrade the image data slightly but might be the most convenient option
       in some cases.  To use this method, use the -slice option to get one
       transform per slice in the image file.  These are f transforms relating
       each slice to the previous, and need to be converted to g transforms
       with "xftoxg -n 0".  Note that the resulting transformation will be
       slightly different from that produced by running Xfjointomo without the
       -slice option, so you need to avoid mixing the modes of operation of
       this program.

       Data from trajectories such as microtubules are used to determine a
       pair of positions at a boundary between two sections, each position
       determined by extrapolating the trajectory on each side of the bound-
       ary.  When you model trajectories such as microtubules, use enough
       points on each side of a boundary so that a line fit will give a rea-
       sonable extrapolation of the trajectory.  The number of points used for
       the line fit is controlled by the -points entry; by default, fits will
       be done to 5 points if they are available, and to a minimum of 2
       points.  Points on each side of the gap must be on more than one Z
       slice, otherwise the line through them will not extrapolate to the
       other side of the gap.  If a microtubule is curved at some distance
       from a boundary, you should add points densely enough so that the
       points being fit will be in a straight segment near the boundary. Avoid
       using the "Fill in Z" option, because that will create redundant data
       between actual points within a section, and incorrect data in a line
       segment across the boundary.

       In addition to trajectories, you can use contours with two points in
       them to specify the centers of features that should align across a
       boundary.  You may find that setting a symbol size or spherical point
       size for each point allows you to judge the centering of the point in a
       feature such as a vesicle.  These pairs of points are included together
       with the pairs of positions extrapolated from trajectories in a single
       least-squares fit to find the transformation at a boundary.  You can
       select the kind of transformation to solve for: translation only, rota-
       tion as well, magnification as well, or a full linear transformation
       including stretch.  The linear transformation requires the most data,
       and requires data spread out over the area that you want to align well.

       With data from trajectories, the program can fit the data with differ-
       ent assumed spacings between the sections (gap sizes) and find the
       adjustment to the spacing that minimizes the error.  It will print out
       the error and other information for each gap size, and save the trans-
       form that occurs at the gap size wit the minimum error.  If you find
       that the minimum error occurs at a gap other than zero, you can change
       the number of sections in the final join, adding sections for a posi-
       tive gap size and taking some away for a negative gap size.  If you do
       not want to adjust the section spacing, leave out the -gap option to
       get the best fitting solution for the current spacing between sections.
       Note that if you are transforming a model and need to adjust section
       spacings, you can use Remapmodel after transforming.

OPTIONS
       Xfjointomo uses the PIP package for input exclusively (see the manual
       page for pip).  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 -).  Options can be abbreviated to
       unique letters; the currently valid abbreviations for short names are
       shown in parentheses.


       -input (-i) OR -InputFile      File name
              Input model file from which transforms will be found.  If this
              option is not entered, the first non-option argument will be
              used.

       -foutput (-f) OR -FOutputFile       File name
              Output file for list of f transforms, which align each section
              to the previous one.  If this option is not entered, the second
              non-option argument will be used.

       -goutput (-go) OR -GOutputFile      File name
              Output file for list of global transforms that can be supplied
              to Finishjoin, adjusted for any offsets used when making the
              join file that was modeled.  This entry is required unless not
              outputting transforms for every slice, in which case it must be
              omitted.  If this option is not entered, the third non-option
              argument will be used.

       -edit (-e) OR -EditExistingFile
              If the specified output file for f transforms exists, read
              transforms from it and use them for any boundaries not being
              aligned.  This option allows the program to be run repeatedly,
              computing transforms for a subset of boundaries each time.

       -slice (-sl) OR -SliceTransforms
              Output transforms for every slice of joined tomogram that was
              modeled.  Use this option if you plan to transform the joined
              file instead of rerunning Finishjoin.

       -join (-j) OR -JoinFileOrSizeXYZ    File name
              Joined tomogram that model was built on, or its size in X, Y,
              and Z.  If this option is not entered, the image X and Y size
              will be used from the model header.

       -sizes (-si) OR -SizesOfSections    Multiple integers
              Number of slices in each section of joined file

       -zvalues (-z) OR -ZValuesOfBoundaries    Multiple integers
              Z value of last slice before each boundary (numbered from 1).
              Either this entry or the sizes of the sections must be entered.
              If this option and the -slice option are used, then a -join
              entry is also needed to inform the program of the full Z size of
              the file.

       -offset (-of) OR -OffsetOfJoin      Two integers
              Offset applied in making the join file that was modeled.  This
              is the same as the offset entry to Finishjoin, and the nega-
              tive of the shift values that appear in eTomo.

       -binning (-bi) OR -BinningOfJoin    Integer
              Binning used to make the join file that was modeled

       -refsec (-re) OR -ReferenceSection       Integer
              Reference section that was not transformed in the join, numbered
              from 1

       -transonly (-t) OR -TranslationOnly
              Solve for transformations that include only translations in X
              and Y.

       -rottrans (-ro) OR -RotationTranslation
              Solve for transformations that include rotations and transla-
              tions, which requires at least 2 points at each boundary.

       -magrot (-m) OR -MagRotTrans
              Solve for transformations that include magnifications, rotations
              and translations, i.e. no stretch.  These solutions require at
              least 3 points at each boundary.  If none of of these three
              options is given, the default is to solve for a full linear
              transformation, which requires at least 4 points.

       -boundaries (-bo) OR -BoundariesToAnalyze     List of integer ranges
              List of boundaries to find transformations across, numbered from
              1.  The default is to do all boundaries.

       -points (-po) OR -PointsToFit       Two integers
              Maximum and minimum number of points to fit on each side of
              boundary.  If a contour contains the minimum number of points in
              each of the sections forming a boundary, then lines will be fit
              separately to the points on each side.  The number of points in
              each fit is limited by the given maximum value.  A contour is
              ignored at a particular boundary if it has fewer than the mini-
              mum number of points in the section on either side, unless it
              has just one point on each side.  The defaults are 5 and 2.

       -gap (-ga) OR -GapStartEndInc       Three floats
              Starting and ending gap size to try between sections, and incre-
              ment between gap sizes.  The gap sizes can be negative or posi-
              tive.  Only one gap size will be used if the ending value equals
              the starting value or the increment is 0.  The default is 0,0,0.

       -objects (-ob) OR -ObjectsToInclude      List of integer ranges
              Objects to include in the fits

       -param (-pa) 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.

HISTORY
       Written by David Mastronarde, 10/26/06

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                       xfjointomo(1)