xfjointomo(1) General Commands Manual 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 out-
putting 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.
IMOD 5.0.2 xfjointomo(1)