cryoposition(1)                                                cryoposition(1)

       cryoposition - Find angles and Z positioning for a cryo-tomogram

       cryoposition  [options]  rootname

       The goal of this program is to create a model for positioning a cryo-
       tomogram with Tomopitch.  It uses Findsection to analyze the
       presence of structure in the tomogram, solve for the best orientation
       and limits of the volume, and create the positioning model.  However,
       the tomogram cannot be used directly for this analysis because the
       artifactual rays from the densest particles in a cryo-tomogram (i.e.,
       gold fiducials or particles of contamination) are as dense as the bio-
       logical structure of interest.  This program thus runs a series of
       operations to produce a volume without these extreme densities and
       their artifacts; only such a volume is suitable for analysis in Find-
       section(1).  Because of this, it is important to use the find option to
       find the gold beads whenever they are present even if fiducials were
       not used for alignment.

       The detection of structure in cryo-tomograms is challenging, and Find-
       section(1) cannot find boundaries nearly as well as it can for stained,
       sectioned material.  To have a reconstruction that contains all mate-
       rial of interest in nearly all cases, two things are advisable: 1) If
       there are gold beads, use them to set boundaries; i.e., use -find
       option with 2 instead of 1.  2) When generating a tomogram without
       checking the model for Tomopitch, make the thickness be 50 pixels
       bigger by setting the -extra option to Tomopitch to 25.

       This program picks a binning to use by default, and generates binned
       tomograms for analysis with no X-axis tilt, regardless of the current
       value in  It does not modify the command file
       to insert the binning or zero out the old X-axis tilt entry there.

       The steps followed by this program are as follows:

       1) The program picks a binning suitable for finding beads, or to bring
       the volume down to a small size if not finding beads.

       2) An aligned stack is created at that binning, with its size increased
       sufficiently to reduce edge effects when erasing high densities from
       this stack.

       3) An oversized reconstruction is built from that aligned stack.

       4) Beads are found in the subset of that reconstruction corresponding
       to the size of an unexpanded aligned stack.  The program uses fallback
       entries to Findbeads3d so a usable result will be produced even if
       beads cannot be well-distinguished.

       5) The program uses Boxstartend to extract boxes around all of the
       found beads into a single stack for analysis.

       6) The histogram of densities in the extracted boxes consists of a cen-
       tral peak dominated by the background density.  The beads or other
       extreme densities create an excess of counts on one side of that peak.
       The "histogram" operation of Clip is used with the -E option to ana-
       lyze these excess counts and find the density level that 95% of them
       are beyond.

       7a) If such a threshold is found, then the program makes sure that the
       threshold is not too lenient; i.e., that it will not cause too large a
       fraction of voxels to be selected.  The acceptable fraction of voxels
       is determined from the bead size and the number of beads found.  The
       program runs "clip hist" with the -t option to determine the threshold
       corresponding to the acceptable fraction, and revises the threshold to
       be applied if necessary.

       7b) If a threshold could not be found, or beads are not being found,
       the program runs "clip hist" with the -t option to determine the
       threshold corresponding to the fraction entered with the -erase option,
       which is 0.002 by default.

       8) The "threshold" operation of Clip is used to produce a binary
       volume in which points are marked as beyond the threshold only if they
       are part of a contiguous set of points of a minimum size set with the
       -M option.  The default minimum size is one third of the bead volume.
       This special thresholding is needed to keep many very small features
       from being erased.

       9) This thresholded volume is reprojected by Tilt with a special
       mode that produces binary projection images.  The marking of projection
       points as beyond threshold is generous.  The projection from a voxel is
       divided among 4 pixels in the projection image by interpolation, and
       any pixel with an interpolation fraction of at least 0.05 is marked as
       beyond threshold.

       10) Contours are generated around the points beyond threshold in the
       reprojections with Imodauto.

       11) Ccderaser is then run on the aligned stack to erase inside those
       contours. Large regions are tapered to their edges when erasing within
       contours; this is why the reprojection itself was not used as a mask
       for pixels to erase.

       12) A regular-sized reconstruction is generated from the erased aligned
       stack by restricting the width and slice numbers in Tilt.

       13) Findsection is run in a mode that analyzes the location of
       regions with high SD values, without attempting to find upper and lower
       surfaces at all positions.  See that man page for details.

       Cryoposition uses the PIP package for input (see the manual page for
       pip).  Options can be specified either as command line arguments
       (with the -) or one per line in a command file (without the -).
       Options can be abbreviated to unique letters; the currently valid
       abbreviations for short names are shown in parentheses.

       -root (-r) OR -RootName   Text string
              Root name of tomogram (include the a or b if dual axis)

       -thickness (-t) OR -ThicknessOfTomograms      Integer
              Thickness of reconstructions in unbinned pixels.  If there is a
              nonzero X-axis tilt, the thickness will be increased and a
              reconstruction built with zero X-axis tilt.

       -find (-fi) OR -FindBeadsInVolume   Integer
              Enter 1 to find gold particles with Findbeads3d, find a
              threshold density, and erase beads along with other compararable
              densities above that threshold.  Enter 2 to do this plus use the
              bead positions in solving for the best angles and in finding the
              boundaries of the sample.

       -size (-si) OR -BeadSize       Floating point
              Diameter of beads to find, in unbinned pixels.  This entry is
              not needed if there is a bead size entry in the Beadtrack
              command file, but would be needed if there is only a centroid
              radius entry there.  It could also be used to enter an alternate
              size to use in Findbeads3d.

       -light (-li) OR -LightFeatures
              Beads or other strong features are lighter, not darker than
              background.  This entry is not needed if there is a LightBeads
              entry in the Beadtrack command file; it will override what-
              ever entry is in that file.

       -binning (-bi) OR -BinningToApply   Integer
              Binning to use for the reconstructions to analyze.  The default
              binning if one is not entered depends on whether beads are being
              found.  If they are, the default binning will make the beads
              about 4-7 pixels, optimal for bead-finding.  Otherwise, the
              default binning will make the volume with a target size of ~650
              pixels in X and Z, up to a maximum binning of 4, by default.

       -erase (-e) OR -EraseFraction       Floating point
              Fraction of extreme pixels to erase if beads are not being
              found; the default is 0.002.

       -high (-hi) OR -HighSDCriterion     Floating point
              Criterion for a high SD to be considered structure in Findsec-
              tion(1); it is expressed as the number of Normalized Median
              Absolute Deviations (MADNs) above the median at the surfaces of
              the volume.  The default is 5.

       -boost (-boo) OR -BoostThickness    Floating point
              Fraction by which to increase the thickness found by the analy-
              sis of high SDs in Findsection.  The lower and upper bound-
              aries from this analysis will each be moved by half of this
              amount, or less if that brings one of them to the edge of the
              volume. The default is 0.1.

       -scales (-sc) OR -ScalesToApply     Multiple integers
              Binnings to apply in the Findsection analysis.  Sensible
              defaults are set based on the initial binning of the volume, so
              that the smallest combined binning of the data (the product of
              the initial binning and the first scale to apply) is at least 3.

       -box OR -BoxSizeInXYZ     Three integers
              Size of boxes at the first scale being analyzed in Findsec-
              tion(1).  The default is 16x4x16 if the combined binning at the
              first scale is 3 or more; 32x8x32 if it is 2, or 48x12x48 if it
              is 1.

       -spacing (-sp) OR -SpacingOfBoxesInXYZ   Three integers
              Spacing between boxes at the first scale being analyzed in Find-
              section(1).  The default is to space boxes apart by half of
              their size in X and Z and a quarter of their size in Y.

       -gpu (-g) OR -UseGPU      Integer
              This entry will replace whatever UseGPU entry is in the
              file.  Enter 0 to use the best GPU on the system, or the number
              of a specific GPU (numbered from 1), or -1 not to use a GPU.

       -pitch (-p) OR -TomoPitchModel      File name
              Alternative file name for boundary model output by Findsection;
              otherwise it will have the standard name for a Tomopitch model
              (i.e., tomopitch.mod for a single-axis data set).

       -control (-c) OR -ControlValue      Two floats
              Parameter number and value for setting algorithm control parame-
              ters.  Parameters and their numbers (and default values in
              parentheses) are:
                1: Maximum binned bead size (7)
                2: Maximum binning (4)
                3: Fraction to increase size in X for oversized aligned stack
                4: Fraction to increase size in Y for oversized aligned stack
                5: Fallback threshold for averaging in Findbeads3d (0.5)
                6: Fallback threshold for storing beads in Findbeads3d (0.5)
                7: Fraction of extra counts on one side of extracted bead den-
              sity histogram at which to pick threshold; this is used in the
              -E option of "clip hist" (0.95)
                8: Fraction of bead volume to use as minimum feature size in
              thresholded volume; this is used in the -M option of "clip
              thresh" (0.33)
                9: Bead diameter to assume for computing minimum feature size
              when no beads are being found (3)
               10: Criterion value for binary marking of pixels in reprojec-
              tion; this value is used in the ThresholdedReproj option to
              Tilt (0.05)
               11: Minimum value for maximum voxels to erase when the esti-
              mated fraction of voxels in beads is taken into account (0.0005)
               12: Maximum fraction of voxels to erase (0.01)
               13: Fraction of voxels in beads for a volume where the maximum
              fraction of voxels to erase should be 0.01; the maximum fraction
              to erase is the fraction of voxels in beads times 0.01 divided
              by this value (6.7e-5) (Successive entries accumulate)

       -fsopt (-fs) OR -FindSecOptions     Text string
              Options to pass to Findsection.  These options must be in
              command-line format and all included in one entry of this
              option.  For example, "-con 28,0.25 -deb 1" would set control
              value 28 to 0.25 and turn on debugging output.

       -leave (-le) OR -LeaveTempFiles     Integer
              1 to keep all temporary files; -1, -2, or -3 to keep _cpos.rec,
              _cposErase.rec, or both

       -use OR -UseTempFiles     Integer
              Use temporary files if possible up to the given step.  Steps
                1: Oversized binned aligned stack
                2: Oversized binned reconstruction
                3: Extracted boxed beads or extreme densities
                4: Thresholded reconstruction
                5: Reprojection of thresholded reconstruction
                6: Contour model of reprojection
                7: Erased aligned stack
                8: Reconstruction from erased stack

       -help (-he) OR -usage
              Print help output

              Read parameter entries from standard input

       When there are gold beads present in the sample, a command like this
       can be used:
          cryoposition -find 2 -thick 800 setname
       where "setname" is the name of the files in the data set without the
       extension, and you would use a thickness substantially bigger than you
       expect the sample to be.  Add the option "-leave -1" if you want to use
       the initial binned oversized reconstruction (setname_cpos.rec) to check
       the result, or "-leave -2" if you want to use the reconstruction with
       beads erased (setname_cposErase.rec).

       All temporary files produced by this procedure can be are placed into
       the current directory and named with _cpos in their names.  They are
       all deleted when the program exits unless the -leave option is used to
       retain them.  The files are:
         _cpos.ali        Oversized binned aligned stack
         _cpos.rec        Oversized binned reconstruction
         _cpos.pkmod      Model of beads found with Findbead3d(1)      Stack of extracted boxes around beads
         _cposThresh.rec  Thresholded volume made from oversized reconstruction
         _cpos.reproj     Binary reprojection of thresholded volume
         _cposAuto.mod    Contour model of binary reprojection
         _cposErase.ali   Erased aligned stack
         _cposErase.rec   Reconstruction built from erased aligned stack

       David Mastronarde

       binvol, xyzproj, matchrotpairs, corrsearch3d, refine-
       match(1), matchvol

       Email bug reports to mast at colorado dot edu.

IMOD                                 4.9.5                     cryoposition(1)