sortbeadsurfs(1) General Commands Manual sortbeadsurfs(1)
NAME
sortbeadsurfs - preprocess 3D model of gold bead positions for flatten-
warp
SYNOPSIS
sortbeadsurfs [options] input_model output_model
DESCRIPTION
Sortbeadsurfs can be used to process two different kinds of models of
the 3D positions of gold beads to make them suitable to use in Flatten-
warp(1) for describing a surface to be flattened. One kind of model
would be of gold positions measured directly in the tomogram, such as
by Findbeads3d. Here it is essential that if the beads are on two
surfaces, each surface be represented by a separate object. Sort-
beadsurfs uses the same routine that Tiltalign does to sort the
beads into two objects. The second kind of model is the one produced
by Tiltalign of the fiducial positions in 3D. Here it is essential
that the model be tilted around the X axis by the X axis tilt used to
generate the tomogram, that its X and Y coordinates be shifted and/or
scaled as appropriate to match the final tomogram, and that the points
are in only one object for each surface.
If you have a model from Findbead3d(1), you should first edit it to
remove points that are obviously not on the surfaces. (Flattenwarp has
an option for removing more subtle outlying points, but it is best to
get rid of the obvious points beforehand.) Then run this program on
the model. Examine the output model to make sure points have been
sorted correctly between the two surfaces. If not, and if the failure
is because the surface is too warped to analyze all at once, then try
the -subarea option to analyze the beads in subareas. If subareas are
not suitable, you may have to edit the model to fix errors. Each point
in the output model is a separate contour, so it is possible to click
on points with the third mouse button in the model view window to
select them, and use the Edit_contour-Move dialog to move the points to
the right object.
If you have a model from Tiltalign, you should run this program on
it to apply the X axis tilt that was used when generating the tomogram.
The program will attempt to sort the points into two surfaces, but if
this creates a problem, use the -already option to skip the sorting if
they are already sorted into two surfaces. If fiducials were tracked
with multiple objects, the program automatically combines them into two
objects based on the colors of the objects. If the beads are on one
surface, use the -one option to skip the sorting and combine multiple
objects, if any, into one object. The program has a host of options
for adjusting for: a full aligned stack bigger or smaller than the
original stack; binning of the prealigned stack or of the final aligned
stack or tomogram; trimming of the tomogram in X or Y (or alterna-
tively, generation of a tomogram that is a subarea in X and Y); or
flipping by Y and Z rather than rotation around X in the trimming step.
You should be able to load the resulting model on the tomogram to ver-
ify that it has the right coordinates. To do so, be sure to use the
-rescale option to account for any change in binning and to start
3dmod with the -m option so that it ignores previous scale informa-
tion in the model. The points will not be on the right Z planes, so
you will have to use the Edit-Model-Offsets dialog to shift the model
in Z until it fits.
OPTIONS
Sortbeadsurfs uses the PIP package for input exclusively (see the man-
ual 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 (-inp) OR -InputFile File name
Input model file with scattered points for 3D gold bead posi-
tions. If this option is not entered, the first non-option
argument will be used for this file.
-output (-outp) OR -OutputFile File name
Output file for processed model or surface information If this
option is not entered, the second non-option argument will be
used for this file.
-text (-t) OR -TextFileWithSurfaces File name
Output a text file with the original contour number and the
top/bottom assignments (values 1 and 2) for each point. This is
meant to be used by Pickbestseed, so input data should have
only one object and only one point per contour.
-flipyz (-f) OR -FlipYandZ Integer
This option allows control over whether the Y and Z coordinates
of the model are flipped. By default, flipping will be done if
the Z dimension (nz) of the modeled volume is greater than the Y
dimension (ny). Enter 1 to force flipping even if this is not
the case, or 0 to prevent it if this is the case.
-subarea (-su) OR -SubareaSize Integer
Size of subareas over which to analyze for two surfaces. This
option is needed only if the area coated with beads is large
enough and warped enough that the analysis fails to separate the
two surfaces. The area occupied by beads will be divided into
non-overlapping subregions of approximately the given size in
each dimension. Each will be analyzed separately to sort all of
the beads between the two surfaces. Make this value as large as
possible, since the analysis can easily fail if there are only
~10 beads in any of the subareas.
-pick (-pi) OR -PickAreasMinNumAndSize Two integers
The program can divide the analysis in to subareas automatically
if this option is used to enter the minimum number of beads
required in each area and the minimum subarea size allowed. The
program will pick the smallest possible subarea size that fits
these constraints.
-majority (-m) OR -MajorityObjectOnly
Output a model with only one object containing the points on the
surface that has the most beads. Use this option if there are
too few fiducials on one surface to fit a smooth surface to in
Flattenwarp.
-xaxis (-xa) OR -XAxisTilt Floating point
The value of X axis tilt used when the tomogram was generated.
This value is needed for a 3D fiducial model output by Tiltal-
ign(1) (and only for such a model).
-invert (-inv) OR -InvertZAxis
Invert the Z coordinates of the points so that they will match a
reconstruction that was Y-Z flipped rather than rotated around
the X axis. This option is needed only for a 3D fiducial model
output by Tiltalign.
-already (-alr) OR -AlreadySorted
Use this option to skip the analysis that sorts beads between
two surfaces, and combine multiple objects by color if there are
any. You would use this for a 3D fiducial model from Tiltal-
ign(1) if the beads are already correctly sorted into two sur-
faces, or if they are on only one surface and in only one
object.
-one (-on) OR -OneSurface
Use this option to skip the analysis that sorts beads between
two surfaces, and to combine all points into one object. You
would use this for a 3D fiducial model from Tiltalign if the
beads are all on one surface but in different objects.
-aligned (-ali) OR -AlignedSizeXandY Two integers
Unbinned X and Y size of the aligned stack used to make the
reconstruction. Use this option if the reconstruction is based
on a final aligned stack whose unbinned size is smaller or
larger than that of the raw stack, and if you are processing a
3D fiducial model from Tiltalign. If the prealigned stack
was binned, you must also enter the -prebin option.
-xtrim (-xt) OR -XTrimStartAndEnd Two integers
Starting and ending X coordinates of the aligned stack that
appear in the final trimmed reconstruction, numbered from 1.
See next option.
-ytrim (-y) OR -YTrimStartAndEnd Two integers
Starting and ending Y coordinates of the aligned stack that
appear in the final trimmed reconstruction, numbered from 1.
These two options are needed only for a 3D fiducial model from
Tiltalign. If you built the full reconstruction (no SLICE or
WIDTH and OFFSET entries to Tilt), then the coordinates for
these two options are just the ones used to trim the volume with
Trimvol. If you built a subset of the reconstruction, the
WIDTH and OFFSET entries can be used to derive the X coordi-
nates, and the SLICE entries provide the Y coordinates. If you
then trimmed the volume, you need to combine the trimming coor-
dinates with the one used to build the reconstruction. If you
enter these coordinates, you must enter the prealigned and the
aligned stack binning if either is different from one.
-prebin (-pr) OR -PrealignedBinning Integer
Binning of prealigned stack used to build a 3D fiducial model.
This option is needed for a binning other than 1 if you enter
the aligned stack size or trimming coordinates, or if you want
to rescale to the coordinates of the reconstruction.
-recbin (-rec) OR -ReconstructionBinning Integer
Binning of aligned stack used to build the reconstruction. This
option is needed for a 3D fiducial model if you are entering
trimming coordinates or if you want to rescale coordinates to
match the reconstruction.
-rescale (-res) OR -RescaleByBinnings
Rescale the model coordinates to account for binning of the pre-
aligned or final aligned stack. By default output coordinates
will still have the scaling of the prealigned stack; use this
option to rescale them so that they match the scaling of the
reconstruction.
-check (-c) OR -CheckExistingGroups
Check that the sorting is the same as in the input model, which
must already have points divided into two groups. All other
output is suppressed, and if the sorting matches the program
just exits with 0 status; if there is a mismatch it prints the
number of incorrect points and exits with an error status.
-values (-v) OR -ValuesToRestrainSorting Integer
Use the general values of the points or contours in the model to
identify a fraction of points as outliers that should be
excluded from the initial pairing of points at steep angles to
each other. Enter 1 to exclude points with particularly high
values (e.g., for mean residual values from Beadtrack), or -1
to exclude points with low values (e.g., for peak values from
imodFindBeads(1)).
-outlier (-outl) OR -OutlierCriterionDeviation Floating point
When the -values option is entered, the values of points are
analyzed to determine the normalized median absolute deviation
(MADN) from the median value. Points with an absolute deviation
from the median bigger than a criterion times the MADN are iden-
tified as outliers and excluded from initial pairing. Use this
option to change the criterion, whose default is 2.24.
-set (-se) OR -SetSurfaceSortParam Two floats
Set one parameter specified by the first number to the value
specified by the second number in the surfaceSort routine. See
the library documentation of surfaceSort (in libcfshr - "Other
utilty functions") for an explanation and a list of the parame-
ters. To set the verbose level, use "-set 13,1" or "-set 13,2".
(Successive entries accumulate)
-help (-h) OR -usage
Print help output.
-StandardInput
Read parameter entries from standard input.
HISTORY
Added to IMOD, 12/6/09
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.0.2 sortbeadsurfs(1)