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