pickbestseed(1)             General Commands Manual            pickbestseed(1)



NAME
       pickbestseed - Selects best seed points for autofidseed

SYNOPSIS
       pickbestseed options

DESCRIPTION
       Pickbestseed is used by Autofidseed to select an optimal set of seed
       points fof the desired number, using bead models tracked starting from
       several different views and using information on the quality of the
       tracking, the shape of the beads, and on which of two surfaces they are
       located.

       The program operates with the following steps:

       1) It reads in the different tracked models and identifies cases where
       the same bead was tracked in different models, as signified by tracks
       that are sufficiently close to each other over the whole range of views
       tracked (controlled by parameters 1 and 6 below).

       2) Each unique bead becomes a candidate, and a single score is obtained
       by taking a weighted mean of four measures of the consistency and qual-
       ity of tracking: the mean residual from alignment during tracking; the
       fraction of models in which the bead is missing; the fraction of points
       missing from each track of the bead; and the mean distances between
       corresponding points in the tracks, computed from each pair of tracks.
       By default, these measures are give equal weighting.  A lower score is
       better.  When beads are located on two surfaces, each candidate is
       assigned to a surface based on which assignment predominates in the
       multiple surface analyses available.

       3) The total area to be analyzed is measured, so that it is possible to
       convert between number of beads and average density per unit area.

       4) Information on the elongation of beads is analyzed, namely statis-
       tics from the standard deviation of pixels around the bead and for the
       elongation.  An adjusted value for the mean of the elongation over the
       11 views of a track is computed by, in effect, rotating a plot of mean
       elongation versus the standard deviation of the elongation by an angle
       (parameter 18 below) that removes much of the variability due to the SD
       of the elongation, and using the new Y coordinate as the adjusted
       value.  The same operation is performed with the SD of pixels around
       the beads to obtain an adjusted edge SD (rotation angle controlled by
       parameter 19).  The latter values are scaled to have the same standard
       deviation as the adjusted elongation values, and then a plot of
       adjusted elongation versus scaled, adjusted SD is rotated so as to com-
       bine them into a single measure (parameter 20 below), with a final
       elongation measure taken as the Y coordinate after rotation.  This mea-
       sure is analyzed by taking the median, finding the median absolute
       deviation, and considering values as outliers if their deviation from
       the median is more than the normalized median absolute deviation (MADN)
       times a criterion (parameter 12 below).  A candidate is marked as elon-
       gated if it is an outlier or if the median elongation exceeds an abso-
       lute threshold (parameter 16 below).

       5) Beads are identified as clustered if they are within a criterion
       distance (parameter 5 below) of any other bead on the same surface.
       This distance is evaluated at the highest tilt angle of the series,
       assuming that the distance between beads perpendicualr to the tilt axis
       is foreshortened by tilting.

       6) Elongation is analyzed again, considering only points that are not
       identified as clustered.  When there are many clustered points, which
       also tend to have high elongation values, this can skew the criterion
       for identifying outliers, so analyzing unclustered points separately
       can identify additional outliers.  Each unclustered point is given the
       maximum of the elongation score from the two analyses.

       7) Beads are sorted in order by their overall score and two different
       procedures are used to accept points in the final model, in a set of
       phases.  Only unclustered, unelongated beads are considered for the
       first 4 phases.  Once some points have been accepted, the program com-
       putes a continuous 2D density function from the points using kernel
       density estimation with a triweight kernel.  Specifically, for each
       bead, a component proportional to (1 - (dist / H)^2)^3 is added for a
       point at distance "dist" from the bead.  H is chosen based on the tar-
       get spacing to be achieved between points in the current phase, times
       parameter 10 below.

       7.1) Phase 1: The target density is converted to an equivalent spacing
       and beads are accepted in order by their score, provided that they are
       not closer to an already-added bead than a certain fraction of this
       spacing (parameter 14 below).  This procedure is then repeated with the
       best half of the candidates, adding them if they are not closer to an
       added bead than a lower fraction of the target spacing (parameter 15
       below).  When there are beads on two surfaces, this procedure is done
       separately for each surface.

       7.2) Phase 2: A gap-filling routine is used to add further points up to
       a desired density, if necessary.  This routine repeatedly finds the
       point with lowest density then searches out from that point in succes-
       sively wider rings for a bead to add.  The ring spacing is the target
       spacing times parameter 3 below.  If multiple beads are found in a
       ring, they are prioritized by an adjusted score, which is their overall
       score divided by the distance to the nearest accepted bead.  In addi-
       tion, if clustered and overlapped points are being accepted (in a later
       phase), the score is increased for a clustered or overlapped point, and
       a point within the clustering distance of another accepted point is
       simply excluded.  After a search is done in one location, points within
       a certain distance of the density minimum are excluded from further
       consideration on that call of the gap-filling routine.  (This criterion
       distance is the target spacing times parameter 2 below.)  The search is
       terminated when all density minima below a fraction of the target den-
       sity are examined.  This fraction is parameter 8 below, but if there
       are two surfaces and the ratio of minority to majority surface is less
       than parameter 13 below, it uses the higher fraction in parameter 9
       instead for the minority surface. The gap-filling routine is called
       twice, once allowing two rings, then allowing the number of rings in
       parameter 4 below.

       7.3) Phase 3: If there are two surfaces, it now tries to beef up the
       number on the majority surface to make up for the deficiency.  The tar-
       get number for this surface is the full target number minus the number
       on the minority surface, unless the "-nobeef" option is entered, in
       which case the target is still half the full target.  First it calls
       the routine that considers points in order by score and adds them if
       their distance from other points is high enough.  Then calls the gap-
       filling routine, but now density is computed from points on both sur-
       faces so that it can fill gaps left by the beads on the minority sur-
       face preferentially.  Again, the gap-filling routine is called twice
       with two different numbers of rings.

       7.4) Phase 4: If points are still deficient, it calls the gap-filling
       routine, examining points with density up to the higher fraction
       (parameter 9) of the target density.  A revised target is used for the
       majority surface unless "-nobeef" is entered, and the original target
       is used for the minority surface.  Densities are computed per surface,
       and the routine is called only once with the full number of rings.

       7.5) Phases 5-8: If clustered and/or elongated points are allowed to be
       included, then it runs the same procedure as in phase 4, first allowing
       clustered points if they are allowed, and then elongated points with
       progressively higher elongation numbers, which are based on the frac-
       tion of tracked models in which the bead was identified as elongated.

       8) Accepted points are put into the output model, along with a general
       value equal to the inverse of the score.  With two surfaces, points on
       the top surface are given surface number 1, which is assigned magenta
       color.


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

       -tracked (-tr) OR -TrackedModel     File name
              Name of tracked model file from one Beadtrack run.  This entry
              is needed for each run to be included in the analysis.  (Succes-
              sive entries accumulate)

       -surface (-su) OR -SurfaceFile      File name
              Name of file with surface information from one Sortbeadsurfs
              run.  There must be the same number of surface file entries as
              tracked models.  (Successive entries accumulate)

       -resid (-re) OR -ElongationFile     File name
              Name of file with residual and elongation data from one Bead-
              track run.  There must be the same number of elongation file
              entries as tracked models.  (Successive entries accumulate)

       -output (-o) OR -OutputSeedModel    File name
              Name of final output model file

       -append (-a) OR -AppendToSeedModel
              Read in existing output seed model and add points to it.  All
              points will be retained from this model.  Candidate points that
              match these points will be accepted before phase 1, then the
              regular sequence of phases will be followed to reach the target
              number.

       -size (-si) OR -BeadSize       Floating point
              Diameter of beads in pixels in the images where beads were found

       -image (-i) OR -ImageSizeXandY      Two integers
              X and Y dimensions of image file used for finding and tracking
              beads

       -border (-bor) OR -BordersInXandY   Two integers
              Number of pixels to exclude on each side in X and in Y

       -middle (-m) OR -MiddleZvalue       Integer
              Z value of middle section for tracking, numbered from 0

       -two (-tw) OR -TwoSurfaces
              Try to sort beads onto two surfaces then select a seed model
              that has equal numbers of beads on the two surfaces if possible.

       -boundary (-bou) OR -BoundaryModel       File name
              Name of model file whose first object contains contours enclos-
              ing areas in which to use or to exclude beads, depending on
              whether -exclude is entered.  If more than one contour is drawn
              on a view, points inside any one of the contours will be consid-
              ered inside the area.  This program will use only the contours
              on the view closest to the middle section for tracking.

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

       -counting (-cou) OR -BoundaryForCounting
              Use the contours in the boundary model just for counting candi-
              dates inside and outside the boundary when outputting a candi-
              date model.

       -number (-nu) OR -TargetNumberOfBeads    Integer
              Desired total number of beads to choose for output seed model.
              If beads are on two surfaces, the program will seek to find half
              the target number on each surface, then pick more beads on
              either surface to reach the target.  Either this option or -den-
              sity must be entered.

       -density (-d) OR -TargetDensityOfBeads   Floating point
              Desired density of beads in final seed model per 1000 square
              pixels of area, excluding the area outside boundary contours if
              any.  This option provides an alternative way of specifying the
              target that is independent of data set size.

       -nobeef (-no) OR -LimitMajorityToTarget
              Do not increase the number of beads on the surface with more
              beads to make up for a deficiency on the other surface.  Aut-
              ofidseed(1) uses this option to limit the number of beads on the
              majority surface in response to its -ratio option.

       -elongated (-el) OR -ElongatedPointsAllowed   Integer
              Enter 1, 2, or 3 to include beads identified as elongated in up
              to 1/3, up to 2/3, or all of the Beadtrack runs, respectively.

       -cluster (-cl) OR -ClusteredPointsAllowed     Integer
              Enter 1 to include clustered beads. i.e, ones that appear to be
              located within 2 diameters of other beads, where foreshortening
              perpendicular to the tilt axis is taken into account in comput-
              ing this separation.  Only one of a pair of clustered points
              will be accepted.  If -elongated is not entered, 2, 3, or 4 can
              be entered to also include beads identified as elongated in up
              to 1/3, up to 2/3, or all of the Beadtrack runs, respectively.

       -lower (-l) OR -LowerTargetForClustered       Floating point
              Include clustered and elongated points as allowed by the -clus-
              ter and -overlap options only when the total number of beads is
              still below the reduced target given here.  The value entered
              should be in the same form as the regular target was specified,
              i.e, a number of beads if -number was entered or a bead density
              if -density was entered.

       -rotation (-rot) OR -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).

       -highest (-hi) OR -HighestTiltAngle      Floating point
              Absolute value of highest tilt angle

       -weights (-w) OR -WeightsForScore   Multiple floats
              Alternative weights for composing a score for each candidate
              bead.  Enter 4 weights: for fraction of points missing in a
              track; for fraction of Beadtrack runs from which the point is
              missing; for mean residual during bead tracking; and for the
              mean deviation between the different tracks of the same bead.
              The default weights are all 1.

       -control (-con) OR -ControlValue    Two floats
              Parameter number and value for setting algorithm control parame-
              ters.  Parameters and their numbers (and default values in
              parentheses) are:
               1: Deviation between points as fraction of bead diameter for
              tracks to be close (0.5)
               2: Multiple of target spacing at which to exclude points from
              further searches (0.75)
               3: Width of rings for finding points when filling gaps, as
              fraction of target spacing (0.25)
               4: Number of rings to search (4)
               5: Maximum # of bead diameters separation for points to be con-
              sidered clustered (2.)
               6: Fraction of points that must be close in two tracks for them
              to be considered same (0.6)
               7: Scaling factor for the two elongation criteria (parameters
              12 and 16), applied to the default or entered values.
               8: Maximum fraction of target density at which to add points in
              initial phase (0.9)
               9: Higher fraction of target at which to add points in more
              desperate searches (1.1)
               10: Scaling from desired spacing to H for kernel density compu-
              tation (1.3)
               11: Scaling from desired spacing to density grid spacing (0.2)
               12: Criterion for edge SD values or elongations to be consid-
              ered outliers (2.24)
               13: Ratio of minority to majority for using higher density fac-
              tor (0.65)
               14: Fraction of nominal spacing allowed for initial addition of
              points (0.85)
               15: Fraction of spacing for adding best half of points on next
              phase (0.7)
               16: Absolute threshold for elongation to be considered overlap
              (2.5)
               17: Option flags: the sum of 1 for fitting elongation measures
              versus bead integral and replacing measures with the residual of
              the fit (which does not help), and 2 for analyzing the elonga-
              tion measure in successive groups of at least 50 values, when
              values are arranged in order by bead integral (which does not
              help)
               18: Angle to rotate plot of mean of edge SD versus SD of edge
              SD to obtain an adjusted edge SD (-59 degrees, the mean from 7
              data sets)
               19: Angle to rotate plot of mean versus SD of elongation mea-
              sure to obtain an adjusted elongation measure (-67 degrees, the
              mean of 8 data sets)
               20: Angle to rotate plot of adjusted elongation measure versus
              adjusted edge SD to obtain the final elongation measure to ana-
              lyze for outliers (45 degrees, corresponds to simply averaging
              the two adjusted values) (Successive entries accumulate)

       -phase (-p) OR -PhaseOutput
              Color output points by the phase in which they were added as
              well as by their surface.  Available colors in order are green,
              magenta, yellow, cyan, red, solid blue, orange, purple, dark
              blue, salmon, dark red.  One or two colors will be used for each
              phase, depending on whether beads are sorted into two surfaces.
              If more than 10 colors are needed the 9 after green are reused.

       -root (-roo) OR -DensityOutputRootname   Text string
              Root name for output of density maps in gnuplot format

       -candidate (-ca) OR -CandidateModel      File name
              Filename for an output model with all candidates beads sorted by
              clustering and elongation scores.  Points will be assigned to up
              to 8 model surfaces.  Surface numbers 0 to 3 are for non-clus-
              tered points with elongation values of 0 to 3, and are colored
              dark green, magenta, bright green, and yellow, respectively.
              Numbers 4 to 7 are for clustered points with elongation values
              of 0 to 3, and are colored mustard green, red, light blue, and
              orange.  Open the Surface/Contour/Point dialog in 3dmod (Edit-
              Surface-Go To) to navigate to contours within and between sur-
              faces and to see labels for the surfaces.

       -verbose (-v) OR -VerboseOutput     Integer
              1 for verbose output including lists of candidates and their
              properties; 2 for more verbose output from addPointsInGaps rou-
              tine.

       -help (-he) OR -usage
              Print help output

       -StandardInput
              Read parameter entries from standard input


AUTHOR
       David Mastronarde

SEE ALSO
       autofidseed

       Email bug reports to mast at colorado dot edu.



IMOD                                4.10.10                    pickbestseed(1)