Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

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 particles 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 number of peaks to use or a relative peak strength to
  use as the threshold.

  In the second phase, the average bead is cross-correlated with subvolumes 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 selection 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 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 reprojection 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.

  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 -):

 -input OR -InputFile   File name
    Input file with image volume

 -output OR -OutputFile   File name
    Output file for model of correlation peaks

 -candidate OR -CandidateModel   File name

 -size 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 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 OR -LightBeads
    Beads are light on dark background

 -angle 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 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 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 OR -MinRelativeStrength   Floating point
    Minimum relative peak strength for keeping a peak in the analysis.  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 OR -ThresholdForAveraging   Floating point
    Threshold relative peak strength or number of beads for averaging.  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 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 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.

 -spacing 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 OR -EliminateBoth
    Eliminate both peaks when their spacing is below the minimum spacing

 -guess 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, especially if there are very
    few beads.  The number can be an underestimate and a very rough estimate. 
    Use this entry if a histogram dip is found at a rather high peak strength
    with few peaks above it.

 -max 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 histogram 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 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 OR -ParameterFile   Parameter file
    Read parameter entries from file

 -help OR -usage
    Print help output

  -StandardInput
     Read parameter entries from standard input.


HISTORY
  Written by David Mastronarde  12/10/08