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



BL3DEMC                              4.7.3                    sortbeadsurfs(1)