Boulder Laboratory for 3-Dimensional Electron Microscopy of Cells

BEADTRACK(1)							   BEADTRACK(1)

NAME
	beadtrack - Tracks fiducial gold particles through a tilt series

SYNOPSIS
	beadtrack

DESCRIPTION
  BEADTRACK will track selected fiducial gold beads through a series of
  tilted views.  It takes a "seed" model, where each bead of choice
  is marked with at least a single point on a view near zero tilt.  It
  tracks each bead as far as possible and puts out a new model.
  
  The program works from one view to the next, using the existing data
  about bead positions to deduce a projected position for each bead on
  the next view to be processed.  After bead positions are available
  on enough views, the program will use tilt alignment to estimate the
  3D position of each bead, and use this position to project a position
  on the next view.  The program searches for beads from the center
  outward.  Before looking for a particular bead, it uses the positions
  of beads already found on that view to refine the projected position.
  It will adjust by a shift if there are 3 points (or at least one
  point from the seed model), by shift and rotation if there are 4 or 5
  points, or by shift, rotation, and a size change if there are more
  than 5 points.
  
  The program will do one or two passes for each view.  On the first
  pass, it uses an average of the current bead over the nearest views
  for which positions have already been identified.  It cross-
  correlates that average with a box at the expected position of the
  bead and derives a bead position from the peak of the correlation.
  It then calculates the centroid and the integral of the density at
  that position.  To do so, it takes the average of pixels more than
  a certain radius away, subtracts this background value from the
  pixels within that radius, and uses pixels above the background to
  calculate a centroid and an integral.  If the integral is too low, or
  if the putative position is too far from the expected position, the
  program then attempts a "rescue".  The criterion for a rescue based
  on distance is set by the user.  The criterion for a rescue based on
  density is set by the mean value of the bead integral on previous
  views.  Specifically, the criterion is the minimum of a certain
  fraction of the mean and a certain number of standard deviations
  below the mean.  The latter parameters are also set by the user.
  To rescue, the program starts at the expected bead position and
  examines every position in a series of progressively wider circles
  around that point.  It calculates an integral for each position, and
  when it first finds an integral above a relaxed criterion value, it
  takes that position as the bead position.  The criterion can be
  relaxed by different factors for "density" and "distance" rescues.
  
  After the first pass, the program does a tilt alignment and uses two
  different tests for whether to  eliminate a point on the current
  view.  One test is whether the residual for the point is greater
  than a user-specifed limit ("criterion for rescue after fitting").
  The other test is whether the mean residual for that bead, averaged
  over all currently available views, has just increased by an unusual
  amount.  It finds the mean and SD of previous increases in this mean
  residual, and tests whether the latest increase exceeds the mean by
  a user-specified criterion number of SD's.
  
  If any points were eliminated by these tests, or if any points failed
  to be found, the program does a second pass.  On this pass there is
  no correlation, just an attempted rescue at the expected position
  (possibly refined because of the additional information about other
  beads on this pass).  The maximum distance for this rescue is set by
  the user.  After the second pass, the program does another tilt
  alignment and tests only the behavior of the increase in mean
  residual for each point.  If that increase is too great, a point is
  eliminated for good.
  
  The program will leave gaps in the model rather than insert bad
  points.  It will try to resume tracking after a gap, but only if the
  gap is not larger than a user-defined limit.
  
  The user can choose whether or not the program will fill in gaps in
  the incoming seed model.  If the image stack has sizable shifts that
  could prevent accurate tracking, then one should use one of the beads
  as a "pioneer".  It is not necessary to model that bead on every
  view, just on the views before and after a large shift.  However, one
  should be sure to have the program fill in gaps in this case.  Also,
  one can place one point for a bead on the view near zero tilt, then
  place a few points on distant views where one can anticipate that the
  program will have trouble tracking through (e.g., where another bead
  crosses, or where the bead goes too close to the edge).
  
  The program performs poorly when the tilt alignment solution gives a poor
  fit, which happens easily with large areas.  The solution to this
  is to track on subsets of beads in local areas and/or to restrict the number
  of views in the tilt alignment.  There are options to enable these features
  when the program is run with PIP input.  An alternative, available when
  running with sequential input, is to place seed points into separate objects
  in different areas; e.g., 4-9 areas for 2K x 2K images, depending on how
  many fiducials are available.  There should be at least 6-8 points per area.
  When there are multiple objects in the seed model, the program will
  automatically track them separately unless local area tracking or the
  TrackObjectsTogether option is selected.

  For each view and pass, the program outputs the results from the
  linear fit between actual and projected positions, the tilt
  alignment total error, and which beads have been deleted or added
  back. After doing all views, the program outputs a summary of which
  views are missing for each bead.
  
INPUTS TO THE PROGRAM
  
  Beadtrack uses the PIP package for input (see the manual page for pip)
  and can still take sequential input interactively, to maintain compatibility
  with old command files.  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 -):

 -InputSeedModel   File name
    Input model file of starting points to track.

 -OutputModel   File name
    Output file for tracked model.

 -ImageFile   File name
    Input file with images to track.

 -PieceListFile   File name
    Name of piece list file if image is montaged or out of sequence.  A
    montaged file should not be be used unless the overlaps between pieces are
    nearly exact.

 -ImagesAreBinned   Integer
    The current binning of the images relative to the original data.  This
    factor is used to scale the bead diameter from unbinned to binned
    coordinates.  The default is 1.

 -SurfaceOutputFile   File name
    File name for output of surface information.  The program will try to sort
    the beads onto two surfaces separately for each local area.  The file will
    have four columns: object and contour number, and number of times the bead
    came out on the bottom and top surfaces.

 -SkipViews   List of integer ranges
    List of views to skip over.  Model contours will pass through these views;
    points will need to be added by hand afterwards.  Ranges may be entered,
    e.g. 1,4-6.  Views are numbered from 1.

 -RotationAngle   Floating point
    Angle of rotation of the tilt axis in the images; specifically, the angle
    from the vertical to the tilt axis (counterclockwise positive).

 -SeparateGroup   List of integer ranges
    List of views that should be grouped separately in automapping the tilt,
    magnification, and rotation variables.  Multiple entries can be used to
    specify more than one set of separate views.
    (Successive entries accumulate)

 -first OR -FirstTiltAngle   Floating point
    Tilt angle of first view, in degrees.  Use this option together with
    TiltIncrement.

 -increment OR -TiltIncrement   Floating point
    Increment between tilt angles, in degrees.  Use this option together with
    FirstTiltAngle.

 -tiltfile OR -TiltFile   File name
    Use this option if tilt angles are in a file, one per line.

 -angles OR -TiltAngles   Multiple floats
    Use this option to enter the tilt angles for each view individually, in
    degrees.
    (Successive entries accumulate)

 -TiltDefaultGrouping   Integer
    Average default group size when automapping tilt variables

 -TiltNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    tilt variables should be grouped differently from the default.
    (Successive entries accumulate)

 -MagDefaultGrouping   Integer
    Default group size when automapping magnification variables

 -MagNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    magnification variables should be grouped differently from the default.
    (Successive entries accumulate)

 -RotDefaultGrouping   Integer
    Default group size when automapping rotation variables

 -RotNondefaultGroup   Three integers
    Starting and ending view numbers and group size for a set of views whose
    rotation variables should be grouped differently from the default. 
    Multiple entries can be used to specify more than one set of views with
    nondefault grouping.
    (Successive entries accumulate)

 -MinViewsForTiltalign   Integer
    Minimum number of views with bead positions available before trying to do
    a tilt alignment.  To skip the tilt alignment computations, set this to a
    number higher than the number of views.  (Default 4)

 -CentroidRadius   Floating point
    Radius for centroid calculation.  The radius need not be a whole number
    and should be somewhat larger than the bead radius.  Either this option or
    BeadDiameter must be entered, but not both.  If this option is entered,
    the diameter will be computed as 2 * radius - 3, then adjusted for
    binning, and the radius will be taken as (adjusted diameter + 3) / 2.

 -BeadDiameter   Floating point
    Actual diameter of beads in pixels in the original stack, before any
    binning.  If CentroidRadius is entered instead, the unbinned diameter will
    be taken as 2 * radius - 3.

 -LightBeads
    Not checked if beads are darker or checked if they are lighter than
    background.

 -FillGaps
    Fill in gaps in the seed model or leave them empty.

 -MaxGapSize   Integer
    Maximum size of gap to create in the model.  If a bead cannot be tracked
    through some views, the tracking may be resumed as long as the gap thus
    created is no larger than this amount.  (Default 5)

 -MinTiltRangeToFindAxis   Floating point
    Minimum range of tilt angles for which data must be available before
    trying to find the angle of the tilt axis (default 10).

 -MinTiltRangeToFindAngles   Floating point
    Minimum range of tilt angles for which data must be available before
    trying to solve for tilt angles (default 20).

 -BoxSizeXandY   Two integers
    X and Y dimensions of the box used to search for a bead, in unbinned
    pixels.  If images are binned, the box size will be taken as the maximum
    of this entry divided by the binning and 2 * max(0, binned diameter - 7) +
    32

 -RoundsOfTracking   Integer
    Number of rounds of tracking through the views.  On odd rounds, Tracking
    proceeds from low to high tilt on odd rounds and from high to low tilt on
    even rounds.

 -MaxViewsInAlign   Integer
    Maximum number of views to include in the tilt alignment.  Use this entry
    to do alignment only on a local subset of views at nearby tilt angles.  A
    value at least big enough to include half the views is recommended.

 -RestrictViewsOnRound   Integer
    If MaxViewsInAlign is entered, this entry can be used to apply the
    restriction on the number of the views in the tilt alignment on a
    particular round of tracking.

 -LocalAreaTracking
    Track subsets of beads in local areas.  The area containing beads near
    zero tilt will be divided into subareas, and the subareas will be tracked
    in order by increasing distance from the center of the image.  Each
    subarea will contain a minimum total number of beads (given by
    MinBeadsInArea), and areas after the first will contain a minimum number
    that are shared with a more central area (given by MinOverlapBeads)

 -LocalAreaTargetSize   Integer
    Target size for the local areas.  The program will try to make typical
    areas have this size, but some will be bigger to contain enough beads.

 -MinBeadsInArea   Integer
    Minimum number of beads in a local area; areas will be expanded from the
    target size to contain this minimum (default 8)

 -MaxBeadsInArea   Integer
    Maximum number of beads in a local area; the target size will be shrunk if
    possible until no local areas exceed this limit (default 500)

 -MinOverlapBeads   Integer
    Each area after the first one tracked will be required to have at least
    this many beads shared with areas tracked earlier.

 -TrackObjectsTogether
    When there is more than one object in the seed model and local area
    tracking is not specified, the objects will be tracked separately unless
    this option is entered.

 -MaxBeadsToAverage   Integer
    Maximum number of views over which to average a bead (default 4).  A
    running average is kept of the appearance of the bead over the most recent
    views examined; this parameter specifies the maximum number of views
    averaged.

 -PointsToFitMaxAndMin   Two integers
    Number of positions to use for extrapolating the bead position to the next
    view when no tilt alignment is available, and minimum required to do
    extrapolation rather than simply taking the mean of positions on the last
    few views.  (Defaults 7 and 3).

 -DensityRescueFractionAndSD   Two floats
    Fraction of mean bead integral, and number of standard deviations below
    mean, to use as the criterion for when to attempt a rescue based on bead
    density.

 -DistanceRescueCriterion   Floating point
    Criterion distance between found position and expected position for
    attempting a rescue based on excessive distance

 -RescueRelaxationDensityAndDistance   Two floats
    Factors by which to adjust (relax) the density criterion when trying to
    rescue.  Enter one factor for density rescue and one for distance rescue. 
    A value of 1 does not relax the criterion.

 -PostFitRescueResidual   Floating point
    Criterion distance for deletion of a point after tilt alignment.  Points
    with residuals greater than this amount will be deleted on the first pass,
    and a rescue search performed on the second pass.

 -DensityRelaxationPostFit   Floating point
    Factor by which to relax the density criterion on the second pass.

 -MaxRescueDistance   Floating point
    Maximum distance to search from the expected position on the second pass

 -ResidualsToAnalyzeMaxAndMin   Two integers
    Maximum and minimum number of changes in mean residual to use in finding
    the mean and SD of changes in the mean residual for a bead as more points
    have been added.  Default values 9 and 5.

 -DeletionCriterionMinAndSD   Two floats
    Minimum change in residual, and criterion number of SD's from the mean
    residual change, to require for deletion of a point on pass 1 or 2.

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

 -help OR -usage
    Print help output

OPTIONS FOR TEST OUTPUT 
  These options are used for program testing and development.

 -BoxOutputFile   File name
    Root filename for diagnositic output of correlation boxes

 -SnapshotViews   List of integer ranges
    List of views at which to snapshot model before deletion on first and
    second passes.  The models will be named <OutputModel>.<view #>.<pass #>.

 -SaveAllPointsAreaRound   Two integers
    Area/object and round at which to save all positions in new objects

  -StandardInput
     Read parameter entries from standard input.

SEQUENTIAL INPUTS
  
  Image file name

  Piece list file name if the file is montaged (or if it is digitized 
     out of order), otherwise enter a blank line
  
  Name of model file with starting bead coordinates
  
  Name of output model file
  
  List of views to skip over.  Model contours will pass through 
     these views; points will need to be added by hand afterwards. 
     Ranges may be entered, e.g. 1,4-6.  Views are numbered from 1.
  
  Angle of rotation of the tilt axis in the images; specifically, the
     angle from the vertical to the tilt axis (counterclockwise
     positive).

  Number of sets of views to treat separately from the main set of
     views when automapping the tilt angle and magnification
     variables.  Enter 0 if all views can be treated together when
     automapping.  These sets would typically be lists of views
     that were reshot.
  
  IF a number other than 0 was entered, next enter one line for each
      separate set, giving a list of the views included in that set.
      Ranges are allowed here.

  -1 to enter individual tilt angle for each view, 1 to specify a
     starting and increment tilt, or 0 to read tilt angles from a file
  
  IF you entered 1, next enter the starting and incremental tilt angles
  IF you entered -1, enter the tilt angle of each view.
  IF you entered 0, enter name of file with tilt angles
  
  The default number of views to group together in solving for tilt
     angles, and the number of ranges of views that should have some
     grouping other than the default.  If a negative number of views
     is entered, then reshoot sets will NOT be segregated from the
     rest of the views in this default mapping.
  
     IF you entered a non-zero number of ranges to be treated
        separately, then for each such range, enter the starting and
        ending view number and the number of views that should be
        grouped in that range.  If a negative number of views is
        entered, then reshoot sets will NOT be segregated from the
        rest of the views in this range.
  
  The default number of views to group together in solving for
     magnifications, and the number of ranges of views to group in
     some other way.  If you enter a non-zero number of ranges, then
     for each one, enter starting and emding view numbers and group
     size.  Note that extensive grouping of tilt angle and
     magnification variables is desirable, but the grouping should be
     adjusted if there are known places where magnification or the
     deviation from the ideal tilt angle changes abruptly.
  
  Minimum number of views with bead positions available before trying
     to do a tilt alignment.  To skip the tilt alignment computations,
     set this to a number higher than the number of views.

  Radius for centroid calculation, and 0 if beads are darker or 1 if
     they are lighter than background.  The radius need not be a whole
     number; e.g., 4.5 is acceptable.
  
  1 to fill in gaps in the seed model, or 0 not to fill in gaps
  
  Maximum size of gap to create in the model.  If a bead cannot be 
     tracked through some views, the tracking may be resumed as long as
     the gap thus created is no larger than this amount.
  
  Minimum range of tilt angles for which data must be available before
     trying to find the angle of the tilt axis, and minimum range of
     angles required before trying to solve for tilt angles.  Suggested
     values are 10 and 20.
  
  X and Y dimensions of the box used to search for a bead 
     (32,32 suggested)
  
  Maximum number of views over which to average a bead (4 suggested)
     A running average is kept of the appearance of the bead over 
     the most recent views examined; this parameter specifies the 
     maximum number of views averaged.

  Number of positions to use for extrapolating the bead position to
     the next view, and minimum required to do extrapolation rather
     than simply taking the mean of positions on the last few views.
  
  Fraction of mean bead integral, and number of standard deviations
     below mean, to use as the criterion for when to attempt a rescue
     based on bead density.
  
  Distance in pixels away from expected position at which to attempt
     a rescue based on excessive distance
  
  Factors by which to adjust (relax) the density criterion when
     trying to rescue.  Enter one factor for density rescue and one for
     distance rescue.  A value of 1 does not relax the criterion.

  Criterion distance for deletion of a point after tilt alignment.
     Points with residuals greater than this amount will be deleted on
     the first pass, and a rescue search performed on the second pass.
  
  Factor by which to relax the density criterion on the second pass, 
     and maximum distance to search from the expected position on this
     pass.
  
  Maximum and minimum number of changes in mean residual to use in 
     finding the mean and SD of changes in the mean residual for a
     bead as more points have been added.  Suggested values 9 and 5.
  
  Minimum change in residual, and criterion number of SD's from the
     mean residual change, to require for deletion of a point on pass 1
     or 2.


HISTORY
	  Written by David Mastronarde, 1995.  Tilt alignment added 10/6/97.