beadtrack(1) General Commands Manual beadtrack(1)NAMEbeadtrack - Tracks fiducial gold particles through a tilt seriesSYNOPSISbeadtrack optionsDESCRIPTIONBeadtrack 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, sub- tracts this background value from the pixels within that radius, and uses pixels above the background to calculate a centroid and an inte- gral. The position is then refined with Sobel filtering of the image (see below), if that option is selected. 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 den- sity 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 "den- sity" 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 crite- rion 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 (possi- bly 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. A Sobel filter, an edge-detecting filter, can be used to get more accu- rate bead positions in many cases. This filter produces a ring of intensity around the edge of the bead. After filtering, a single bead image is correlated with a filtered reference based on many images of that bead, and of others if necessary (see the AverageBeadsForSobel option). For most data sets with relatively low noise, this method produces significantly better positions and a lower mean residual error in the alignment solution in Tiltalign. The improvements are less for higher-noise data (e.g., cryo data), and such data require a higher-than-default sigma value for the Gaussian smoothing filter applied before the Sobel filter, otherwise worse results may be obtained. When refining with the Sobel filter,the program stores the unrefined positions as well. At the end of each round (and for each local area when using them) it does a final alignment with each set of positions and keeps track of the mean residuals and the which set of positions gives a lower mean residual. At the end of tracking, the program prints the mean of those mean residuals and how often the centroid- based positions gave a lower value. If that occurs more in more than half the fits, the program gives a warning and falls back to the cen- troid-based positions. This protection is not present when using a restricted range of tilt angles for alignment. For data sets that track well, the benefit from using the Sobel filter can be assessed even before running Tiltalign and/or completing the model by examining the errors in the alignment solution that Beadtrack does. The summary line just described at the end of the log may be adequate, or if you are doing local tracking, you may want to look at the values for F (the root-mean-squared error) and for the mean resid- ual at the end of the tracking for several of the local areas, just before the output on the number of points missing for that area. The values for the centroid-based positions should be very close but not identical to what you would get without the Sobel filtering. Also, for high-noise data, you can run with different sigma values for the kernel filtering and see which gives the best result. 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 root- mean-squared 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.OPTIONSBeadtrack 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 -). Options can be abbreviated to unique letters; the currently valid abbreviations for short names are shown in parentheses.-InputSeedModelFilenameInput model file of starting points to track.-OutputModelFilenameOutput file for tracked model.-ImageFileFilenameInput file with images to track.-PieceListFileFilenameName 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.-prexf(-pr)OR-PrealignTransformFileFilenameFile with transformations applied to align the images. The pro- gram will assume that the transformations consist only of shifts and will use this information to avoid searching for a bead on a filled area that has no image data.-ImagesAreBinnedIntegerThe 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.-XYZOutputFileFilenameFile name for output of information that can be used by Sort- beadsurfs(1) to determine which of two surfaces each bead is on. This file has an entry for each bead with 5 columns: contour number, solved X, Y, Z coordinates, and the mean of the mean residuals from each local area. The program uses the X/Y/Z coordinates from beads that overlap between between local areas to resolve the sets of coordinates from multiple local areas into a single consistent set.-ElongationOutputFileFilenameFile name for output of mean residuals and bead elongation data, which can be used by Pickbestseed when selecting optimal beads for a seed model. The file has an entry for each bead with 10 columns: object and contour number, and mean of the con- tour's mean residuals from each local area that the bead occurs in, the mean, median, and standard deviation of one measure of elongation (the standard deviation of pixels around the edge of the bead when measuring the centroid), the mean, median, and standard deviation of the elongation of pixels above a thresh- old, and the mean bead integral.-SkipViewsListofintegerrangesList 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.-RotationAngleFloatingpointAngle of rotation of the tilt axis in the images; specifically, the angle from the vertical to the tilt axis (counterclockwise positive).-SeparateGroupListofintegerrangesList 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(-f)OR-FirstTiltAngleFloatingpointTilt angle of first view, in degrees. Use this option together with TiltIncrement.-increment(-i)OR-TiltIncrementFloatingpointIncrement between tilt angles, in degrees. Use this option together with FirstTiltAngle.-tiltfile(-t)OR-TiltFileFilenameUse this option if tilt angles are in a file, one per line.-angles(-a)OR-TiltAnglesMultiplefloatsUse this option to enter the tilt angles for each view individu- ally, in degrees. (Successive entries accumulate)-TiltDefaultGroupingIntegerAverage default group size when automapping tilt variables-TiltNondefaultGroupThreeintegersStarting 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)-MagDefaultGroupingIntegerDefault group size when automapping magnification variables-MagNondefaultGroupThreeintegersStarting and ending view numbers and group size for a set of views whose magnification variables should be grouped differ- ently from the default. (Successive entries accumulate)-RotDefaultGroupingIntegerDefault group size when automapping rotation variables-RotNondefaultGroupThreeintegersStarting 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)-MinViewsForTiltalignIntegerMinimum number of views with bead positions available before trying to do a tilt alignment. To skip the tilt alignment com- putations, set this to a number higher than the number of views. (Default 4)-CentroidRadiusFloatingpointRadius 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.-BeadDiameterFloatingpointActual 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.-MedianForCentroidTake the median instead of the mean of the pixels in the sur- rounding annulus when computing the centroid.-LightBeadsNot checked if beads are darker or checked if they are lighter than background.-FillGapsFill in gaps in the seed model or leave them empty.-MaxGapSizeIntegerMaximum 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)-MinTiltRangeToFindAxisFloatingpointMinimum range of tilt angles for which data must be available before trying to find the angle of the tilt axis (default 10).-MinTiltRangeToFindAnglesFloatingpointMinimum range of tilt angles for which data must be available before trying to solve for tilt angles (default 20).-BoxSizeXandYTwointegersX 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-RoundsOfTrackingIntegerNumber of rounds of tracking through the views. Tracking pro- ceeds from low to high tilt on odd rounds and from high to low tilt on even rounds.-MaxViewsInAlignIntegerMaximum 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.-RestrictViewsOnRoundIntegerIf 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.-UnsplitFirstRoundOn the first round, the program will track from the seed view halfway down to the first view, then halfway up to the last view, then return to the low views and finish with the high views. Use this option to return to the old behavior (prior to IMOD 4.6.8) of tracking all the way to the first view then tracking up to the last view.-LocalAreaTrackingTrack subsets of beads in local areas. The area containing beads near zero tilt will be divided into subareas, and the sub- areas 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)-LocalAreaTargetSizeIntegerTarget 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.-MinBeadsInAreaIntegerMinimum number of beads in a local area; areas will be expanded from the target size to contain this minimum (default 8)-MaxBeadsInAreaIntegerMaximum number of beads in a local area; the target size will be shrunk if possible until no local areas exceed this limit (default 500)-MinOverlapBeadsIntegerEach area after the first one tracked will be required to have at least this many beads shared with areas tracked earlier.-TrackObjectsTogetherWhen there is more than one object in the seed model and local area tracking is not specified, the objects will be tracked sep- arately unless this option is entered.-MaxBeadsToAverageIntegerMaximum 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.-SobelFilterCenteringUse an edge-detecting Sobel filter to refine the centroid-based bead positions.-KernelSigmaForSobelFloatingpointSigma for gaussian kernel filtering of single bead before Sobel filtering, which reduces the contribution of noise to the edge- filtered image. The default is 0.5, which is optimal for rela- tively low-noise data. Higher-noise data requires a higher sigma of around 1.5.-AverageBeadsForSobelIntegerNumber of beads to average for the reference for Sobel filter correlation. Images will be averaged from already-tracked nearby views separately for each bead. If there are not enough already-tracked views, averages will be combined from multiple beads to reach the desired number. If the number of averaged beads is less than half of this value, a model bead is used instead. The average or model is Sobel-filtered and correlated with the Sobel-filtered image of the single bead. The default is 50.-InterpolationTypeIntegerType of interpolation to use in the scaled Sobel filter: 1 for linear interpolation, 0 for cubic interpolation, and -1 for image reduction with an antialias filter instead of with inter- polation combined with binning. The default is 0 if the sigma for kernel filtering is less than 1.5, otherwise 1.-PointsToFitMaxAndMinTwointegersNumber of positions to use for extrapolating the bead position to the next view when no tilt alignment is available, and mini- mum required to do extrapolation rather than simply taking the mean of positions on the last few views. (Defaults 7 and 3).-DensityRescueFractionAndSDTwofloatsFraction of mean bead integral, and number of standard devia- tions below mean, to use as the criterion for when to attempt a rescue based on bead density.-DistanceRescueCriterionFloatingpointCriterion distance between found position and expected position for attempting a rescue based on excessive distance-RescueRelaxationDensityAndDistanceTwofloatsFactors 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.-PostFitRescueResidualFloatingpointCriterion 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.-DensityRelaxationPostFitFloatingpointFactor by which to relax the density criterion on the second pass.-MaxRescueDistanceFloatingpointMaximum distance to search from the expected position on the second pass-ResidualsToAnalyzeMaxAndMinTwointegersMaximum 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.-DeletionCriterionMinAndSDTwofloatsMinimum 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(-pa)OR-ParameterFileParameterfileRead parameter entries as keyword-value pairs from a parameter file.-help(-h)OR-usagePrint help outputOPTIONSFORTESTOUTPUTThese options are used for program testing and development.-BoxOutputFileFilenameRoot filename for diagnostic output of correlation boxes-SnapshotViewsListofintegerrangesList of views at which to snapshot model before deletion on first and second passes. The models will be named <Output- Model>.<view #>.<pass #>.-SaveAllPointsAreaRoundTwointegersArea or object and round at which to save all positions in new objects. Enter negative of the area number to exit after fin- ishing the area. This option will also enable some debugging output for that area and round.-StandardInputRead parameter entries from standard input.SEQUENTIALINPUTSImage 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.HISTORYWritten by David Mastronarde, 1995. Tilt alignment added 10/6/97.BUGSEmail bug reports to mast at colorado dot edu. IMOD 4.10.18 beadtrack(1)