findbeads3d(1)                                                  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
       denisty.  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
       need to be removed before reprojecting the points with Tilt.  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 dis-
       played, 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 might be a good
       starting point.

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.

       -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.

       -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 (-y) 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.  Too many weak peaks can prevent a dip from showing up in
              the smoothed histogram of strengths.  The default is 0.05.  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 filtering and correlation 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 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
              strength above which peaks will be stored.  Enter a negative
              number to specify the number to store as a fraction of the num-
              ber 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.

       -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.



BL3DEMC                              4.7.3                      findbeads3d(1)