imodfindbeads(1)                                              imodfindbeads(1)



NAME
       imodfindbeads - Find gold particles in images

SYNOPSIS
       imodfindbeads  options  input_image  output_model

DESCRIPTION
       Imodfindbeads finds gold particles or other circular densities (beads)
       in images by a combination of cross-correlation and other methods.  It
       starts by correlating with a model of a spherical bead of a specified
       size, then forms an average out of the most strongly-correlating subset
       and repeats the procedure by correlating with the average.  It analyzes
       the distribution of correlation strengths to find the strength that
       best separates the particles of interest from similar densities.  The
       positions of the beads are stored in an IMOD model along with strengths
       for each.  The points can then be visualized in 3dmod, and with the
       help of the Bead Fixer module, the threshold can be adjusted and points
       below threshold can be deleted.

       Rather than cross-correlating with a model or averaged bead, the pro-
       gram applies an edge-detecting filter (Sobel, by default) to both the
       images and the reference, and correlates the filtered images.  This
       method improves the detectability of the beads and may improve the
       accuracy of the center positions.  However, it only works well for
       beads in a certain size range, so the program first scales the images
       to bring the beads to a specified size (8, by default).  The peaks in
       this correlation are the set of candidate positions for the beads.

       At each position, the program then computes an integral of the bead
       density relative to the background in an annulus around the bead.  The
       program can then work with three measures of peak strength.  One is the
       strength of the Sobel-filter correlation (which includes a component
       based on the density of the bead, a factor lost when using a normalized
       correlation coefficient).  The second is the integrated density, and
       the third is the geometric mean of the first two.  Whichever measure is
       chosen, it is scaled so that the maximum value is 1.

       Correlation with a simple item like a bead always produces many more
       peaks than actual beads, but a histogram of peak strength generally
       shows a dip between actual beads and spurious peaks.  The program thus
       computes a histogram and smooths it with kernel smoothing, whereby a
       narrow distribution function instead of a single point is added into
       the histogram at every peak position.  The width of this function is
       the kernel width, referred to as H in program output.  The program
       tries a series of widths, from 0.2 downward, until it finds a dip in
       the histogram; then it computes it again with a kernel width of 0.05 in
       order to locate the dip more accurately.

       After the initial correlation with a model bead, the program uses the
       histogram analysis to select beads to average as a template for the
       second round correlation.  If the analysis fails, it is possible to
       bypass it by entering a relative peak strength to use as a criterion
       for selecting beads.  After the second round of correlations, the loca-
       tion of the dip is used to determine which points to output in the
       model.  The default is to output a number of points below the dip so
       that the user can check and adjust the threshold if necessary.  How-
       ever, with the -store option, you can output just the points above the
       dip or a certain fraction of the strongest peaks above the dip.  Or, if
       the histogram analysis fails, this option can be used to bypass it and
       specify the actual peak strength to use as the criterion for output.

       The most significant options described below are: -size to specify the
       bead size, -area to specify a model with contours around areas to ana-
       lyze, -light if beads are light on a dark background, -store to control
       storage of peaks in the model as just described, -spacing to allow
       points closer together than the bead size, -sections to select the sec-
       tions to be analyzed, and -maxsec to set how many of them will be ana-
       lyzed in one group.  In addition, if images are noisy, it may be help-
       ful to use linear interpolation with -linear and add some filtering
       with either -kernel or -rad2 and -sig2.  There are many other options
       that were added during program development and can be ignored.

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

       -input (-inp) OR -InputImageFile    File name
              Name of input image file.  If it is not entered with this option
              it must be entered with the first non-option argument.

       -output (-o) OR -OutputModelFile    File name
              Name of output model file.  If it is not entered with this
              option it must be entered with the second non-option argument.

       -filtered (-fi) OR -FilteredImageFile    File name
              Output file for images after they have been scaled and Sobel
              filtered.  The coordinate system in the header will be congruent
              with that of the original image file so that the model can be
              displayed on it.

       -area (-ar) OR -AreaModel      File name
              Model with contours enclosing areas to analyze or to exclude
              from analysis, depending on whether the -exclude option is given
              also.  More than one contour can be included on each section.
              If there are no contours on a section within the range being
              analyzed, the contours on the nearest section with contours will
              be used.

       -exclude (-e) OR -ExcludeInsideAreas
              Use the contours in the area model to define regions to exclude
              from analysis rather than regions to include.

       -query (-q) OR -QueryAreaOnSection       Integer
              Report area in megapixels that an area model includes in the
              analysis for the given section, and then exit.  This is the sum
              of areas inside the contours, or the whole image area minus that
              sum if -exclude is given.  With this option, only the input and
              area models need to be entered.

       -prexf (-pr) OR -PrealignTransformFile   File name
              File with transformations applied to align the images being ana-
              lyzed.  The program will assume that the transformations consist
              only of shifts and will use this information to avoid finding
              beads at the edge of a filled area that has no image data.

       -imagebinned (-im) OR -ImagesAreBinned   Integer
              The current binning of the images relative to the original data.
              This factor is needed to scale prealignment transforms.  The
              default is 1.

       -add OR -AddToModel       File name
              Model to append to.  After the analysis of histograms and
              thresholds, detected points will be eliminated if they are
              within the criterion spacing of a point in an existing object
              (where closed contour objects are excluded).  Points will be
              stored in new objects.

       -ref OR -ReferenceModel   File name
              Model with all beads marked in defined areas, used for determin-
              ing the accuracy of the bead detection.

       -boundary (-bou) OR -BoundaryObject      Integer
              Object in reference model with contours around the areas where
              beads have been fully marked.

       -size (-siz) OR -BeadSize      Floating point
              Size of beads in pixels, a required entry.  A model bead of this
              size is constructed for the first round of correlation, and this
              size together with the scaled size determine how much images
              will be scaled for filtering.

       -light (-lig) OR -LightBeads
              Beads are light on dark background

       -scaled (-sc) OR -ScaledSize   Floating point
              Size of beads in images scaled down for filtering; this entry
              together with the bead size determine the amount of scaling.  In
              tests, values of 7 to 10 have been found to give the best detec-
              tion with Sobel filter.  The default value is 8.

       -adjust (-adj) OR -AdjustSizes
              Change all size-based parameters using the measured size of the
              averaged bead.  After averaging selected beads, the program will
              estimate the bead diameter by forming a radial average, finding
              the radius where the density falls off the fastest, fitting a
              line to nearby points with sufficiently high gradient, and find-
              ing the intersection of that line with the background density at
              the edge of the average.  If the change is more than 5%, the
              program will add a third pass through the data.  If the change
              is more than a factor of 1.6, the change in size will be
              rejected as implausible.  This method does not give the right
              diameter for gold on plastic sections, so this option should be
              used only for cryo-samples or other samples taken with signifi-
              cant underfocus.

       -interpmin (-int) OR -MinInterpolationFactor       Floating point
              When images are being scaled down, this entry determines how
              much of the scaling down must be done with interpolation instead
              of binning.  Interpolation will preserve high frequency informa-
              tion better than binning does but may amplify noise.  The
              default value is 1.4, which means that data will not be binned
              unless they are being scaled down by a factor of at least 2.8.
              This entry makes no difference unless images are being scaled
              down by more than a factor of 2.

       -linear (-lin) OR -LinearInterpolation   Integer
              This option controls the type of interpolation used in scaling
              images.  Enter 1 to use linear instead of cubic interpolation;
              this option will help to reduce noise.  Alternatively, enter -1
              to use antialiased image reduction when images are being scaled
              down.  With this option, large size reductions will be done in
              one step instead of with binning then interpolation.  The noise
              reduction from antialias filtering would probably make kernel
              filtering unnecessary.

       -center (-c) OR -CenterWeight       Floating point
              The weighting for the center pixel in the edge detecting filter;
              1 and 2 correspond to Prewitt and Sobel filters, respectively;
              the default is 2.

       -box OR -BoxSizeScaled    Integer
              Box size for correlating and averaging beads in scaled down
              images.  The default is 3 times the scaled size plus 2.

       -threshold (-t) 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
                -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.)

       -fallback (-fa) OR -FallbackThresholds   Two integers
              Number of peaks to average to make the reference for the second
              round, and number of peaks to store in the model, if no dip is
              found when analyzing the histogram of the respective set of
              peaks.  If this option is not entered, or if 0 is entered for
              one of the fallbacks, then the program exits with an error after
              failing to find a histogram dip.

       -bkgd (-bk) OR -BackgroundGroups    Floating point
              After finding peaks, the program will sort the peaks based on
              the background density into the number of groups given by this
              entry, as long as there are at least 100 peaks in each group.
              The histogram will be analyzed separately for each group to find
              the dip, and then the peak strengths will be scaled so as to
              superimpose the dip values.  This scaling should make a single
              threshold value work better across a range of intensities.  The
              default value is 4; enter 0 to prevent this analysis.

       -annulus (-an) OR -AnnulusPercentile     Floating point
              By default, the program will use the mean in an annulus around
              the bead as the background for the analysis by groups.  This
              entry specifies a percentile of the pixel values to use instead
              (e.g., 0.5 for the median).

       -peakmin (-pe) OR -MinRelativeStrength   Floating point
              Minimum relative peak strength, after any background scaling,
              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.1, or 0.05 if a threshold for aver-
              aging is being found from histograms.

       -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.  The default is 1, but values of 0.8 to 0.9
              are helpful for getting a more complete set of beads.

       -sections (-se) OR -SectionsToDo    List of integer ranges
              List of sections to run.  Comma-separated ranges can be entered;
              sections are numbered from 0.  By default, all sections will be
              analyzed.

       -maxsec (-ma) OR -MaxSectionsPerAnalysis      Integer
              Maximum number of sections to include in one analysis.  With
              this entry, the list of sections will be divided into groups no
              bigger than this size.  Each group will be analyzed separately
              and results will be stored in a separate model object with its
              own threshold value.  By default, all sections are analyzed
              together.

       -remake (-rem) OR -RemakeModelBead
              Start with a model bead for each separate analysis when more
              than one group of sections is being analyzed.  The default is to
              use the average from the previous group for the first round of
              correlation on a group.

       -guess (-g) OR -MinGuessNumBeads    Integer
              A guess for the minimum number of beads per section.  This entry
              may sometimes be required to help the program find a dip in the
              histogram, especially if there are very few beads.

       -measure (-me) OR -MeasureToUse     Integer
              Measure to use for peak strengths: 0 for the correlation peak, 1
              for the integral of density above the background, 2 for the geo-
              metric mean of these two.  The default is 1; integrals were
              slightly better in test data sets.

       -kernel (-k) OR -KernelSigma   Floating point
              Sigma for real-space smoothing with a Gaussian kernel (in pix-
              els).  The smoothing is with a 3x3, 5x5 or 7x7 kernel whose
              coefficients are proportional to a Gaussian with the given sigma
              centered on the central pixel.  This smoothing is applied before
              the image is scaled for filtering.  The default is 0.85, which
              is equivalent to the simple smoothing filter in Clip and
              3dmod.

       -rad1 OR -FilterRadius1   Floating point
              Low spatial frequencies in the cross-correlation will be attenu-
              ated by a Gaussian curve that is 1 at this cutoff radius and
              falls off below this radius with a standard deviation specified
              by FilterSigma2.  Spatial frequency units range from 0 to 0.5.
              Use FilterSigma1 instead of this entry for more predictable
              attenuation of low frequencies.

       -rad2 OR -FilterRadius2   Floating point
              High spatial frequencies in the cross-correlation will be atten-
              uated by a Gaussian curve that is 1 at this cutoff radius and
              falls off above this radius with a standard deviation specified
              by FilterSigma2.

       -sig1 OR -FilterSigma1    Floating point
              Sigma value to filter low frequencies in the correlations with a
              curve that is an inverted Gaussian.  This filter is 0 at 0 fre-
              quency and decays up to 1 with the given sigma value.  However,
              if a negative value of radius1 is entered, this filter will be
              zero from 0 to |radius1| then decay up to 1.

       -sig2 OR -FilterSigma2    Floating point
              Sigma value for the Gaussian rolloff below and above the cutoff
              frequencies specified by FilterRadius1 and FilterRadius2

       -verbose (-v) OR -VerboseKeys       Text string
              Key letters for verbose output (1 for general, p for peak, f for
              first, l for last, e for every hist)

       -dump (-d) OR -DumpHistogramFile    File name
              Name of file in which to write all histograms.  Each histogram
              will be written with a type number, the peak strength, and the
              actual or smoothed number of counts.  The program will use suc-
              cessive type numnbers and print a line describing the histogram
              written with each type number.  Histograms can be displayed with
              commands like
                 onegenplot -con -sym 0 -ty <type>  <filename>
              where <type> is a type number and <filename> is the name pro-
              vided with this option.  Add the option "-ylog 10" to spread out
              the low parts of the histogram.

       -param (-pa) OR -ParameterFile      Parameter file
              Read parameter entries as keyword-value pairs from a parameter
              file.

       -StandardInput
              Read parameter entries from standard input


AUTHOR
       David Mastronarde

SEE ALSO
       beadtrack

BUGS
       Email bug reports to mast at colorado dot edu.



BL3DEMC                              4.7.3                    imodfindbeads(1)