pickbestseed

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. The median and MADN of all the scores are used to
 define a maximum acceptable score in this phase (8 MADNs from the
 median, by default). Once some points have been accepted, the program
 computes 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.
 In these phases, a larger maximum score is allowed (12 MADNS above the
 median by default), since most beads with high scores fall in these
 categories.
 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
 -zseed (-z) OR -SeedZvalue Integer
 Z value of seed for one Beadtrack run, numbered from 0. If this
 option is entered at all, it must be entered for each tracked
 models. (Successive entries accumulate)
 -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; float parameters have decimal points) 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 (1.375)
 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 (1.0).
 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.0 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.0 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.0 degrees, corresponds to simply averaging
 the two adjusted values)
 21: Maximum number of MADNs above the median score allowed to
 accept a candidate point in phases 1-4 (8.0).
 22: Maximum number of MADNs above the median score allowed to
 accept a clustered or elongated candidate point in phases 5-8
 (12.0). (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 5.2.0 pickbestseed(1)