autofidseed(1)                                                  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 Imofindbeads(1) 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 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, Beadtrack 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 surface information is then
       passed to Pickbestseed, which takes everything 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.

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.  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 to run Imodfind-
              beads just once with the given number of views.

       -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 -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), 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.

       -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                                 4.9.5                      autofidseed(1)