cryoposition(1) General Commands Manual cryoposition(1)
NAME
cryoposition - Find angles and Z positioning for a cryo-tomogram
SYNOPSIS
cryoposition [options] rootname
DESCRIPTION
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 tilt.com. It does not modify the tomopitch.com 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.
OPTIONS
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 tilt.com
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
(1.18)
4: Fraction to increase size in Y for oversized aligned stack
(1.06)
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
are:
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
-StandardInput
Read parameter entries from standard input
EXAMPLE
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).
FILES
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)
_cposBox.st 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
AUTHOR
David Mastronarde
SEE ALSO
binvol, xyzproj, matchrotpairs, corrsearch3d, refine-
match(1), matchvol
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 4.11.0 cryoposition(1)