findbeads3d(1) General Commands Manual findbeads3d(1)
NAME
findbeads3d - Find spherical densities in a volume
SYNOPSIS
findbeads3d [options] input_image_file output_model_file
DESCRIPTION
Findbeads3d will find gold particles and other spherical densities in
tomograms. Given the diameter of the beads, it will search for parti-
cles of this size and store their locations in a model along with the
strengths of their correlations with an average particle. It will
automatically determine the threshold strength that separates the gold
particles from lesser densities.
The search occurs in two phases. First, density is summed over small
cubes centered on each pixel, about 3/8 of the bead diameter on a side,
and local peaks in the summed density are found. The peak strength is
measured by an integral of the densities relative to the background
density. When two of these candidate peaks are too close together, the
weaker one is eliminated. The integrals are scaled so that they range
up to 1, a subset of the strongest peaks are selected, and an average
bead is obtained by extracting a small volume at each selected peak
location. By default, the subset is selected by analyzing a histogram
of the peak strengths to find a dip separating the gold from weaker
features; however, the -threshold option can be used to specify a num-
ber of peaks to use or a relative peak strength to use as the thresh-
old.
In the second phase, the average bead is cross-correlated with subvol-
umes at all of the candidate peak locations from the first phase. This
time the value of the cross-correlation (not a normalized correlation
coefficient) is taken as the peak strength, and again they are scaled
to range up to 1. A selection of the strongest peak locations are then
written to the output model. Again, the default method for this selec-
tion is to analyze a histogram of peak strengths for a dip between
beads and weaker peaks, but the number of points stored in the model
can also be controlled with the -store option.
The output model consists of a scattered point object with one point
per contour. The peak strength is stored as a general value, and the
object properties are generally set so that only points above threshold
are displayed. However, points below threshold generally do exist and
may need to be removed before reprojecting the points with Tilt. As
of IMOD 4.10.43, both Tilt and Ccderaser now have a -skip option
to ignore points below threshold if the flag is set not to display them
in 3dmod. With this option, "what you see is what you get" and it is
not necessary to delete points below threshold. To see all of the
points, adjust the threshold, or delete points below the threshold,
load the model into 3dmod and open the Bead Fixer in Seed mode. The
Bead Fixer will have a slider for adjusting the threshold, a checkbox
to controlling whether points below threshold will be displayed, and a
button to delete points below threshold. Since these points are
located on many Z planes, be sure to check "Delete on all sections"
before deleting the points.
The tomogram can be built from binned down aligned images, and the
model will load correctly on an unbinned tomogram. Also, a reprojec-
tion of the points by Tilt will load correctly on an unbinned or a
binned aligned stack. Findbeads3d will work much faster on a binned
tomogram and may even work better, as long as the bead size in the
binned tomogram is at least 5 pixels.
The tomogram needs to be thicker than normal because the program cannot
find beads too close to the surfaces of the tomogram. With the typical
elongation taken into account, the program will find only the beads
that are more than ~1.1 bead diameters from the surface. If gold is on
two surfaces, thickness thus needs to be at least 2.2 bead diameters
more than the average distance between the surfaces, which is indicated
in the Surface Analysis output of Tiltalign as "Thickness at Z
intercepts". To the extent that beads do not lie exactly in planes,
even more thickness will be required; 3 diameters is a good starting
point and is used in the interface in Etomo.
In IMOD 4.8.30, the program switched to taking the square root of cor-
relation peak strength. In a histogram, this change spreads out the
very large histogram peak from weaker, non-bead peaks, compacts and
accentuates the much smaller histogram peak from actual beads, and thus
makes the histogram dip more pronounced and easier to detect. The
square root values will be reported for the histogram dip and peaks and
stored in the model for visualization in 3dmod. If a relative peak
strength is entered for the threshold options -fBthreshold and -store,
it should be in terms of the square root values. However, the minimum
relative peak strength is still entered in terms of the raw correlation
values before taking the square root, in order to maintain the same
behavior for this routinely applied parameter.
OPTIONS
Findbeads3d 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 file with image volume
-output (-o) OR -OutputFile File name
Output file for model of correlation peaks
-candidate (-c) OR -CandidateModel File name
-size (-si) OR -BeadSize Floating point
Diameter of beads in pixels, a required entry. If the volume is
binned, this size can be entered in unbinned pixels and the
-binning entry used to specify the binning.
-binning (-bi) OR -BinningOfVolume Integer
The current binning of the image volume. The entered bead size
is divided by this binning to obtain the actual size of the
beads in the volume.
-xminmax (-x) OR -XMinAndMax Two integers
Starting and ending X coordinates of region in which to find
beads. X, Y, and Z coordinates are numbered from 1. The
default is to search the whole volume.
-yminmax (-ym) OR -YMinAndMax Two integers
Starting and ending Y coordinates of region to find beads in
-zminmax (-z) OR -ZMinAndMax Two integers
Starting and ending Z coordinates of region to find beads in
-light (-l) OR -LightBeads
Beads are light on dark background
-angle (-a) OR -AngleRange Two floats
Starting and ending tilt angles, for computing the elongation
factor due to the missing wedge in single-axis tomograpy. The
elongation is computed using a formula in Radermacher (1988),
with the maximum tilt angle for that formula taken as the mean
of the absolute values of the minimum and maximum angles of the
series. The elongation will be capped at 2.5, and the program
will exit with an error if it exceeds 5.
-tilt (-ti) OR -TiltFile File name
File with tilt angles, for computing elongation factor from the
minimum and maximum tilt angle, as just described. Only one of
-angle and -tilt may be entered.
-ylong (-yl) OR -YAxisElongated
Features are elongated by the missing wedge along the Y axis
instead of the Z axis. This entry is needed when analyzing a
tomogram as produced by Tilt with Z slices along the tilt
axis and Y perpendicular to the plane of the specimen.
-peakmin (-pe) OR -MinRelativeStrength Floating point
Minimum relative peak strength for keeping a peak in the analy-
sis. The square root of the specified value is used for compar-
ing with the square root of peak strength, for compatibility
with existing command files. The default is 0.05, which corre-
sponds to a relative square root peak strength of 0.22. Too
many weak peaks can prevent a dip from showing up in the
smoothed histogram of strengths. If the program fails to find a
histogram dip, one strategy is to try raising this value.
-threshold (-th) OR -ThresholdForAveraging Floating point
Threshold relative peak strength or number of beads for averag-
ing. With a non-zero entry, selected beads from the first round
of peak finding and integral measurement are averaged to produce
a reference for a second round. If a negative value is entered,
the program will analyze the histogram of peak strengths and
find the dip indicating the best boundary between actual and
false beads. The value has 4 different meanings depending on
the range:
Greater than 1: an absolute number of beads with the strongest
peaks
Between 0 and 1: minimum relative square root of peak strength
Between 0 and -1: negative of strongest fraction of peaks
above histogram dip (e.g., -0.33 for the strongest 1/3 of the
peaks above the dip)
-2: 1/4 of way from histogram dip to histogram peak (the
default)
-store (-st) OR -StorageThreshold Floating point
Threshold relative peak strength for storing peaks in model.
With a value of 0 (the default), the program will find the dip
in the histogram of peak strengths, find the mean and SD of the
strengths above the dip, and store all of the beads above the
dip plus additional ones below the dip. The latter will be up
to the 5 SD's below the mean or up to the number of ones above
the dip. Enter a number between 0 and 1 to specify a relative
square root strength above which peaks will be stored. Enter a
negative number to specify the number to store as a fraction of
the number above the histogram dip (e.g., -1 for all points
above the dip, -0.33 for the strongest 1/3 above the dip, -1.33
for all above plus 1/3 that many below the dip.) If you use the
default, or a number below -1, then you must examine the points
in 3dmod, adjust the threshold if necessary, and delete points
below the threshold.
-fallback (-f) OR -FallbackThresholds Two floats
Thresholds to use as fallbacks when no histogram dip is found.
The first number is a threshold to use for averaging when no dip
is detected in the histogram of peak strengths in the first
round. It can be between 0 and 1 to specify a relative peak
strength, or a number greater than 1 to specify a number of
beads. The second number is a threshold relative strength for
peaks to store, between 0 and 1, when no dip is found in the
histogram of second-round peak strengths. If a fallback is
desired for only one of these two rounds, enter a zero for the
other value.
-spacing (-sp) OR -MinSpacing Floating point
Minimum spacing between peaks as a fraction of the bead size.
When two peaks are closer than this distance apart, the weaker
one is eliminated unless the -both option is entered. The
default is 0.9. A value less than 1 is helpful for picking both
beads in a pair.
-both (-bo) OR -EliminateBoth
Eliminate both peaks when their spacing is below the minimum
spacing
-guess (-g) OR -GuessNumBeads Integer
A guess for the number of beads. This entry may sometimes be
required to help the program find a dip in the histogram, espe-
cially if there are very few beads. The number can be an under-
estimate and a very rough estimate. Use this entry if a his-
togram dip is found at a rather high peak strength with few
peaks above it.
-max (-m) OR -MaxNumBeads Integer
The maximum possible number of beads to look for. Only this
number of peaks will be retained and used for finding the his-
togram dip. If the program fails to find a histogram dip, try
entering a value that is at least twice the estimated number of
beads. The default is 50000.
-verbose (-v) OR -VerboseOutput Integer
Enter 1 for diagnostic output, 2 for listing of peaks, and 3 or
4 for verbose output from the histogram routines
-param (-pa) OR -ParameterFile Parameter file
Read parameter entries from file
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input.
HISTORY
Written by David Mastronarde 12/10/08
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 4.11.0 findbeads3d(1)