autofidseed

autofidseed(1) General Commands Manual autofidseed(1)
NAME
 autofidseed - Automatically make a seed model for tilt series fiducial
 tracking
SYNOPSIS
 autofidseed options
DESCRIPTION
 Autofidseed uses a series of other programs to generate a seed model
 for tracking tilt series fiducial particles in Beadtrack. Given a
 desired number or density of beads to be found, it attempts to select a
 well distributed set of good-quality beads. If beads are on two sur-
 faces, it will aim for an even distribution of beads on both surfaces.
 The program first determines three views around zero tilt that are
 suitable for finding beads on. It aims to have the views be separated
 by 2 degrees in tilt. It runs Imodfindbeads on those views. If too
 few beads are found to achieve the requested number of beads for track-
 ing, it then reruns Imodfindbeads with 5 or 7 initial views instead,
 in case that brings in more beads. (The -views option can be used to
 make it use only a specific number of views between 3 and 7.) The pro-
 gram next assesses whether some beads have a large shift between these
 views that needs to be supplied to Beadtrack. It does this by using
 Imodmop to extract images that contain only the gold beads and run-
 ning Tiltxcorr to find one or two peak positions in the correlation.
 If the results make sense and indicate a significant shift, they are
 supplied as parameters to Beadtrack to help the tracking get
 started. The program next extracts the beads found on each view into a
 separate model and runs Beadtrack independently with each model as
 seed. The beads are typically tracked over 11 views, or possibly over
 as few as 7 views if the tilt increment is large. In each case, Bead-
 track(1) puts out a file with the mean residual and some measures of
 elongation for each bead that was tracked. If beads are to be sorted
 onto two surfaces, then Beadtrack also puts out a file with the X,
 Y, and Z coordinates of each bead, and Sortbeadsurfs is called to
 sort the beads onto two surfaces independently for each starting view.
 The tracked models, the residual/elongation information, and the sur-
 face information is then passed to Pickbestseed, which takes every-
 thing into account to pick out the best beads for a seed and produces
 the final seed model.
 The various intermediate files involved are placed in a temporary
 directory created in the current directory (see the -tempdir option).
 Some of them are cleaned up after a run, but some are kept so that
 Pickbestseed can be run over again with different parameters, with-
 out having to rerun the bead finding and tracking, and some are left
 for information only. (See the FILES section below for a description
 of files.) Autofidseed retains a file with information about the ini-
 tial steps so that it can tell whether the existing temporary files are
 valid on a new run. The default name of this file is "autofid-
 seed.info" for a single axis data set, or "autofidseeda.info" or "aut-
 ofidseedb.info" for dual axis data, while the temporary directory is
 "autofidseed.dir", "autofidseeda.dir", or "autofidseedb.dir". If Aut-
 ofidseed is run with the option "-remove 1" it will clean up existing
 files and start a new run from scratch; with the option "-remove -1" it
 will simply clean up files, remove the temporary directory, and exit.
 The program requires at least two arguments, -track to indicate a Bead-
 track(1) command file, and either -number or -density to indicate the
 desired total number of beads or the density per megapixel (1K x 1K
 area). The command file is the primary source for information about
 the data set and also the basis for the commands used to track the
 beads. Parameters (such as whether beads are white, or Sobel filtering
 parameters) should be set in this file before running Autofidseed.
 However, the selection for local tracking is ignored; Autofidseed sets
 up local tracking depending on the size of the area and the number of
 beads found initially.
 In typical use, only a few other options should be needed, primarily
 -two to request sorting onto two surfaces, and -boundary to specify a
 model with contours enclosing the regions where beads should be
 located. If Imodfindbeads fails to find a dip in the histogram of
 peak strengths or does not find nearly enough beads, the best thing to
 try is the -guess option, although it may also be helpful to make a
 boundary model that excludes bright areas in the resin outside of a
 cell.
 A major source of problems is a severe imbalance between the number of
 beads on two sides. If the imbalance is big enough, the sorting of
 beads onto two surfaces can fail, leading to an inappropriate distribu-
 tion of points, and even selection of points that are in clusters. In
 other cases, a big imbalance can lead to selection of the lowest qual-
 ity beads on the minority surface, which might be ribosomes instead of
 gold beads. In these cases, the best approach may be to leave off the
 -two option. The program will add beads from the majority surface, if
 possible, to achieve the requested number or density of beads. This
 can lead to an undesirable imbalance in the final seed model, and the
 -ratio option is available to set the allowed ratio between the major-
 ity and minority surfaces.
 Large clumps of gold can also create problems at both the tracking
 steps and when sorting beads onto two surfaces. If the problem is pri-
 marily in sorting, with some of the selected beads assigned to the
 wrong surface, then one remedy is to exclude bad surface information
 from particular Beadtrack runs. Use 3dmodv to examine the sorted
 models with extension ".sortmod" in the temporary directory. If at
 least one of these models shows proper sorting and some models do not,
 use the -ignore option to exclude surface information from the runs
 with bad sorting. If that is unsuccessful, you can try the -drop
 option instead to omit those tracked models completely from considera-
 tion.
 Another remedy for problems created by large clumps is to use a bound-
 ary model to exclude them. Note that it is possible to draw contours
 just around areas to exclude, rather than around areas to include, if
 you use the -exclude option.
 If there are particles other than gold selected as beads, or if some
 gold particles seem not to be found, it may help to examine the
 ".pkmod" model produced by Imodfindbeads(s) and left in the temporary
 directory. Open the Bead Fixer in 3dmod to see whether adjusting the
 threshold upward removes undesired points; if so you can try the -peaks
 option with a value less than 1 to remove a fraction of the points with
 the lowest peak strengths. To add more points than appear in this
 model, use -peaks options with a value greater than 1.
 When sorting onto two surfaces is requested, the points are still
 placed in a single object in the output model, but the ones on the top
 surface are given a different surface number so that they can appear in
 a different color. Points on the bottom have the object color, green,
 and points on the top appear as magenta, since surface 1 in the object
 has that color set as a fine-grained property.
 In the output model, seed points have values based on the overall score
 that Pickbestseed assigned to them. The score is a weighted sum of
 several factors: the mean residuals in the various tracks, the mean
 deviation between multiple tracks of the same bead, the fraction of
 tracks in which the bead is missing, and the fraction of points missing
 from each track. In addition, 1 is added if a bead is clustered, and
 0.3-1 is added if it is elongated. Good scores are thus on the order
 of a mean residual value, and bad ones may be up to 3 or more. The
 value stored in the model file is the inverse of the score so that low
 values will be worse, allowing them to be examined in the Bead Fixer in
 3dmod. There, you can adjust a slider to turn off points below a
 threshold value, and then delete the points below threshold if desired.
 The values there will be on the order of 2-3 for good beads, and less
 than 1 for the worse ones.
 Pickbestseed places into the temporary directory another output
 model containing all of the points that are candidates for being
 selected, color-coded by whether they are clustered or elongated. The
 contours are assigned to up to 8 model surfaces. Surface numbers 0 to 3
 are for non-clustered 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 navi-
 gate to contours within and between surfaces and to see labels for the
 surfaces.
 Autofidseed should work with data having a small pixel size and large
 beads, provided that the command file for running Beadtrack has var-
 ious size-dependent parameters scaled for unbinned data, which is done
 by Copytomocoms as of IMOD 4.10.33. The -weights option to
 Pickbestseed will be modified to avoid over-weighting distance-
 dependent measures of bead quality, but the entry to the -density
 option will not be changed and needs to be appropriate for the current
 binning of the pre-aligned stack.
OPTIONS
 Autofidseed 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.
 -track (-tr) OR -TrackCommandFile File name
 Command file for running Beadtrack. This entry is required
 as the command file is used both for tracking points found by
 Imodfindbeads and to obtain several parameters.
 -append (-ap) OR -AppendToSeedModel
 Read in existing output seed model and add points to it. All
 points will be retained in this model and additional points will
 be sought to reach the target number.
 -guess (-g) OR -MinGuessNumBeads Integer
 A guess for the minimum number of beads present. This entry may
 sometimes be required to help Imodfindbeads find a dip in the
 histogram, especially if there are very few beads. The default
 is one-fourth of the target number of beads if -number is
 entered; if -density is entered, the default is one-eight or
 one-fourth of the density times the area, depending on whether a
 boundary model is entered or not.
 -spacing (-sp) OR -MinSpacing Floating point
 Minimum spacing between peaks found in Imodfindbeads, as a
 fraction of the bead size. When two peaks are closer than this
 distance apart, the weaker one is eliminated. The default is
 0.85, since values of 0.8 to 0.9 are helpful for getting a more
 complete set of beads.
 -size (-si) OR -BeadSize Floating point
 Diameter of beads in the images to track, in pixels. This entry
 is not needed if there is a bead size entry in the Beadtrack
 command file, but would be needed if there is only a centroid
 radius entry there. It could also be used to enter an alternate
 size to use in Imodfindbeads. If it is entered, it must be
 in units of the potentially binned pixels of the stack being
 tracked.
 -adjust (-ad) OR -AdjustSizes
 Change all size-based parameters in Imodfindbeads using the
 measured size of the averaged bead. If the change in size is
 more than 5%, the new bead size will be used in tracking by this
 program (this feature was broken until IMOD 4.10.33). Also, in
 this case, a Beadtrack command file will be written with mod-
 ified parameters, named as the root name of the input command
 file followed by "_adjusted" and its extension. This option
 should be used only for cryo-samples or other samples taken with
 significant underfocus.
 -peak (-pe) OR -PeakStorageFraction Floating point
 Fraction of the peaks above the histogram dip that Imodfind-
 beads(1) should store in the model. The default is 1.0 to store
 all peaks above the dip. An value below 1 will omit the weakest
 peaks from the seed models for tracking and could be used if
 some non-gold particles are being selected. A value above 1
 will include peaks below the dip and could be used if some gold
 particles are being missed. For example, 1.1 would include the
 strongest peaks below the dip, 10% as many as are above the dip.
 The negative of this entry is used for the -store entry to
 Imodfindbeads.
 -find (-f) OR -FindBeadOptions Text string
 Additional options to pass to ImodFindBeads. The entry should
 be a single string (quoted when running from the command line)
 that contains the text that would be entered directly to
 ImodFindBeads, for example, "-peakmin .15 -store 30". Each
 option, recognized by the dash, is placed on a separate line of
 input to ImodFindBeads, at the end of the usual input.
 -views (-v) OR -NumberOfSeedViews Integer
 Number of views at which to find seed points for tracking beads.
 The program runs Imodfindbeads on this number of views and then
 runs beadtrack independently for each view with a seed model of
 all the points found on that view. The default is for the pro-
 gram to try 3 views, then run Imodfindbeads again with 5 or 7
 views with if there not enough candidate points found by
 Imodfindbeads. With this option, the program will run Imodfind-
 beads just once with the given number of views.
 -shifts (-sh) OR -ShiftsNearZeroFraction Floating point
 Fraction of the tracking box size above which to supply shifts
 near zero tilt to Beadtrack. The dominant net shifts in the
 bead positions between views are found as described above, and
 if one of the shifts is larger than this fraction of the -Box-
 SizeXandY entry to Beadtrack, then the shifts are provided
 when running Beadtrack on the initial seed models. Also, a
 command file will be written with modified parameters, named as
 the root name of the input command file followed by "_adjusted"
 and its extension. Enter 0 or a large value to disable this
 analysis. The default is 0.2.
 -justshifts (-j) OR -JustFindShiftsNearZero Integer
 Just find the shifts near zero tilt, adjust the Beadtrack
 command file if necessary, and exit. This operation requires
 finding beads in the usual way first. The value entered for
 this option should be an estimated number of beads, to provide
 the target for bead finding. The -number and -density options
 are ignored. The -guess option may be entered with a minimum
 number, but if not, the default is half of the value entered
 here. Information in an info file about a previous full run of
 Autofidseed will be removed.
 -boundary (-bou) OR -BoundaryModel File name
 Name of model file whose first object contains contours enclos-
 ing areas in which to find or exclude beads, depending on
 whether the -exclude option is given. If more than one contour
 is drawn on a view, points inside any one of the contours will
 be accepted. Contours should be drawn in the zero-tilt view, as
 those will govern the final selection by Pickbestseed. In
 Imodfindbeads, when peaks are examined on a view, contours on
 the nearest view are used, so contours can be drawn on other
 views if necessary to further constrain the areas examined at
 that stage.
 -exclude (-ex) OR -ExcludeInsideAreas
 Use the contours in the boundary model to define regions to
 exclude from analysis rather than regions to include.
 -border (-bor) OR -BordersInXandY Two integers
 Number of pixels to exclude from consideration near each edge in
 X and in Y. The default is based on the average of the X and Y
 sizes of the image; it is 32 pixels per 1024 up to a size of
 2048, plus 24 pixels per 1024 above 2048 pixels.
 -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.
 -number (-n) OR -TargetNumberOfBeads Integer
 Desired total number of beads to choose for final 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 taget. Either this option or -den-
 sity must be entered.
 -density (-de) OR -TargetDensityOfBeads Floating point
 Desired density of beads in final seed model per megapixel (1K x
 1K of area in the possibly binned pixels of the pre-aligned
 stack), 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.
 -ratio (-ra) OR -MaxMajorToMinorRatio Floating point
 Maximum ratio between number of beads on the surface with more
 beads and the number on the other surface. If this ratio is
 exceeded after running Pickbestseed, the target is revised and
 Pickbetseed is run again. The default is no limit, which means
 that the program will seek to reach the target number of beads
 regardless of the imbalance between surfaces.
 -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 (-c) 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. For compatibility with existing command
 files, 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 (-lo) OR -LowerTargetForClustered Floating point
 Include clustered and elongated points as allowed by the -clus-
 ter and -elongated 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.
 -subarea (-su) OR -SubareaSize Integer
 Size of subareas within which Sortbeadsurfs should analyze
 for two surfaces. This option and the -sort option cannot be
 used together. By default the -sort option is passed to Sort-
 beadsurfs(1).
 -sort (-so) OR -SortAreasMinNumAndSize Two integers
 Minimum bead number and area size for having Sortbeadsurfs pick
 subareas. With these parameters, Sortbeadsurfs will divide the
 area occupied by points into equal-sized areas that are at least
 the given minimum size in each dimension, and that have at least
 the given number of points. The default is 50 beads and 2500
 pixels.
 -ignore (-ig) OR -IgnoreSurfaceData List of integer ranges
 List of the numbers of tracked models where the sorting of beads
 into two surfaces failed (comma separated values or ranges num-
 bered from 1). These surface files for these models will not be
 sent to Pickbestseed and assignments of beads to surfaces
 will be based only on the surface data for the remaining
 model(s).
 -drop (-dr) OR -DropTracks List of integer ranges
 List of the numbers of tracked models that should not be sent to
 Pickbestseed for analysis (comma separated values or ranges
 numbered from 1). If tracking from one or more views behaved
 badly, this option can be used to omit those results from fur-
 ther consideration.
 -pick (-pi) OR -PickSeedOptions Text string
 Additional options to pass to Pickbestseed. The entry should be
 a single string (quoted when running from the command line) that
 contains the text that would be entered directly to Pickbest-
 seed, for example, "-ver 1 -phase -con 6,2". Each option, rec-
 ognized by the dash, is placed on a separate line of input to
 Pickbestseed. If the -weights option is included, it will over-
 ride Autofidseed's scaling of weighting factors for large bead
 sizes.
 -remove (-re) OR -RemoveTempFiles Integer
 Clean up the temporary files that are retained between runs so
 that Pickbestseed can be rerun without finding and tracking
 beads again. Enter 1 to remove these files and go on to a new
 run, or -1 simply to remove the files and exit. In the latter
 case, the temporary directory will be removed if it is the
 default one.
 -output (-o) OR -OutputSeedModel File name
 Output file name for saving the seed model, instead of using the
 name from the Beadtrack command file.
 -info (-in) OR -InfoFile File name
 File name for the info file that is written on a first run and
 read on later runs. The default info file is written in the
 current directory with the name autofidseeda.info if the root of
 the Beadtrack command file name ends in "a", autofidseedb.info
 it it ends in "b", otherwise autofidseed.info.
 -tempdir (-te) OR -TemporaryDirectory File name
 Path to temporary directory. The default is to use a directory
 in the current directory with the name autofidseed.tmp, autofid-
 seeda.tmp, or autofidseedb.tmp, depending on the ending of the
 root of the Beadtrack command file. The directory will be cre-
 ated if it does not exist.
 -leave (-le) OR -LeaveTempFiles
 For diagnosing problems, leave temporary files that would ordi-
 narily be deleted in the temporary directory.
 -help (-h) OR -usage
 Print help output
 -StandardInput
 Read parameter entries from standard input
FILES
 The temporary and intermediate files are named "afsnnn.#.ext", where
 "nnn" is a process ID, "#" is the tracked model number, and "ext" is an
 extension indicating the contents of file.
 afsnnn.pkmod - model produced by Imodfindbeads
 afsnnn.#.seed - seed model for tracking from one view
 afsnnn.#.track - model tracked from one view
 afsnnn.#.xyzpt - text file with X/Y/Z coordinates of tracked beads
 afsnnn.#.elong - text file with mean residual and elongation data
 afsnnn.#.xyzmod - 3D model of beads tracked from one view
 afsnnn.#.sortmod - 3D model after sorting onto two surfaces
 afsnnn.#.surf - text file with surface assignments
 clusterElong.mod - model of candidate points in Pickbestseed
 The ".seed", ".xyzpt", and ".surf" files are cleaned after a run; the
 ".track", ".xyzmod", and ".elong" files are needed for rerunning Sort-
 beadSurfs(1) and Pickbestseed, and the "pkmod" and ".sortmod" files
 are left solely for user information. A copy of the track command file
 is also placed in the temporary directory so that the program can make
 sure that it has changed.
AUTHOR
 David Mastronarde
SEE ALSO
 imodfindbeads, beadtrack, sortbeadsurfs, pickbestseed
 Email bug reports to mast at colorado dot edu.
IMOD 5.2.6 autofidseed(1)