restrictalign(1) General Commands Manual restrictalign(1)
NAME
restrictalign - Restrict tilt alignment parameters for low number of
fiducials
SYNOPSIS
restrictalign options tiltalign_command_file
DESCRIPTION
Restrictalign will modify the parameter settings in a command file for
running Tiltalign so that they are appropriate for the number of
fiducials available. It uses two fundamentally different methods for
reducing the number of variables being solved for. The original
method, currently the default, is based on the ratio of measured values
to unknown variables. Variables are reduced until this ratio rises to
a target or minimum level. Although this ratio provides some guidance
for how to avoid over-fitting, this method cannot take into account the
signal-to-noise ratio of the data, namely how much random error there
is in the measurements.
Cross-validation
The newer method is cross-validation: running Tiltalign numerous
times with a small fraction of points left out, measuring how well each
solution predicts the positions of the points left out, and computing
an average "leave-out error". This error, not the mean residual error,
accurately reflects whether a different selection of parameters gives a
better solution or not. The mean residual will always go down when
more variables are solved for (e.g, by adding a parameter to solve for
or reducing its grouping), whereas the leave-out error will go down
when the added variables improve the fit and go up when they over-fit
to the data. The downside of this superior method of avoiding overfit-
ting is that it takes much more time for the many runs of Tiltalign;
this becomes a major consideration with local alignments and many fidu-
cials.
The variables tested are completely different depending on whether
local alignments are to be tested. Without local alignments, the pro-
gram tests a sequence of the global variables being solved for. For
each variable, it tests with default grouping if there is no grouping,
with intermediate grouping, with very large grouping, and with the
variable fixed (or, for rotation, with solving for only one rotation
angle), stopping when the leave-out error rises. The order of the
tests is X-stretch and skew together, tilt angle, rotation, magnifica-
tion, beam tilt, X axis tilt, and projection stetch. With local align-
ments, the program can test either by restricting alignment variables
in a similiar sequence, or by increasing the size of local areas
together with the required number of fiducials in each, or with both
kinds of tests. Here the sequence of variables is X-stretch and skew
together, tilt angle, rotation, and magnification. It is recommended
that the area requirements be tested first because the same requirement
tends to be chosen regardless of which order they are done in, whereas
the variables tend to be restricted more when tested before the area
requirement has been increased.
If robust fitting is being done, the program may first disable it per-
manently if the ratio of measurements to unknowns is too low. If not,
the program uses a weighted leave-out error computed with and without
robust fitting to assess the benefit from robust fitting, and if the
benefit is not above a criterion, it turns off robust fitting temporar-
ily for all further tests simply in order to save time.
Restrictions Based on the Ratio of Measurements to Unknowns
In the old method, the program proceeds by applying a series of
restrictions - grouping a variable instead of solving at every tilt, or
fixing it instead of grouping - in a specified order until an appropri-
ate ratio of measured values to unknown variables is reached. That
ratio is picked based on two parameters, the minimum required ratio,
and a target ratio. When two restrictions both give more than the min-
imum ratio, the one closest to the target is chosen. To have the pro-
gram always pick the first restriction where the ratio is above the
minimum, set the target ratio equal to the minimum ratio.
The -order option controls the order in which restrictions will be
applied by changes in the magnification, rotation, and tilt solutions,
but these are not the only changes that can occur. Before applying any
of these restrictions, the stretching solution (X-stretch and skew),
local alignments, and variable X-axis tilt (except between two halves
of a tilt series) will be turned off. If these restrictions are suffi-
cient, no further changes are made. When there are fewer than 4 beads,
the beam tilt solution, projection stretch, and variable X-axis tilt
between two halves of a tilt series are turned off; all of these
involve solving for a single variable. The solution for one rotation
angle is turned off with only one bead. When the ratio of measurements
to unknowns falls below the minimum, robust fitting is turned off.
The program always changes parameters so as to solve for fewer vari-
ables than in the current file. If the ratio is already greater than
the minimum and closer to the target than with any restriction applied,
no change will be made.
To use the program with the default settings with a single-axis tilt
series, simply enter:
restrictalign align.com
to use the original method, or
restrictalign -cross 1 align.com
to do cross-validation when local alignments are not being used, or
restrictalign -cross 1 -local 3 align.com
to test the local area requirements then the local variables. The
existing file will be renamed to align.com~ and the file with the
changed parameters will be written as align.com, unless the -trial
option is entered.
OPTIONS
Restrictalign 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.
-align (-a) OR -AlignCommandFile File name
Command file for running Tiltalign. If this option is not
entered, the first non-option argument will be used for the name
of the command file.
-fiducials (-f) OR -NumberOfFiducials Integer
Numbers of fiducial markers (beads) in the alignment model.
With this entry, he program will assume that each bead is marked
on every view. If this option is not entered, the program will
use the number of contours in the fiducial model with more than
one point, and count up the number of points in those contours.
The latter will give more accurate estimates of the ratio of
measurements to unknowns when there beads marked on only a sub-
set of views.
-views (-vi) OR -NumberOfViews Integer
Number of views in the tilt series. If this option is not
entered, the program will use the number of views in the image
file listed in the command file.
-target (-ta) OR -TargetMeasurementRatio Floating point
Target ratio of measurements to unknown values. If two succes-
sive restrictions give a ratio above the minimum required by the
-minimum option, the restriction that gives a ratio closest to
this value will be chosen. The default is 3.6.
-minimum (-m) OR -MinMeasurementRatio Floating point
Minimum ratio of measurements to unknown values. Restrictions
will be applied until at least one ratio rises above this value.
The default is 3.2.
-order (-or) OR -OrderOfRestrictions Multiple integers
Order in which possible restrictions should be applied to
achieve the target. The restrictions are numbered as follows:
1: Group rotations
2: Solve for one rotation
3: Fix tilt angles
4: Group magnifications
5: Fix magnifications
The default order is 1,4,3,2,5, which means rotations will be
grouped, then magnifications grouped, tilt angles fixed, then
one rotation solved for, then magnifications fixed. If fewer
than 5 numbers are entered, they will replace just the first
numbers in the order list, and they must be different from the
remaining values
-cross (-cr) OR -UseCrossValidation Integer
With this option, the program will test for the value of
restricting the alignment parameters using cross-validation.
Namely, alignment is run repeatedly with ~10% of points left
out, and the error in predicting the positions of the left-out
points from the solution obtained with the remaining points is
computed. A set of alignment parameters is considered to be
better if it reduces this error, regardless of the effect on the
mean residual of the fit with all points. If 1 is entered, sets
of 5 points on adjacent views are left out, with error measured
from the middle 3 points. If 2 is entered, contours will be
left out instead. The latter approach is unsuitable if there
are few contours.
-local (-l) OR -LocalAlignValidation Integer
Do cross-validation on local alignment parameters: enter 1 to
test the variable selections, increasing the grouping or turning
off magnification, rotation, tilt, and x-stretch and skew
together. Enter 2 to test the required number of fiducials in
local areas while increasing their target size (or reducing the
number if that is specified instead of target size). Enter 3 or
4 to do both tests, first areas then variables with a 3, or
variables then areas with a 4. These tests can take several to
many minutes. No tests will be done on global variable selec-
tions. Local alignment must be selected in the command file.
-benefit (-b) OR -MinRobustBenefit Floating point
Minimum percentage benefit (reduction in leave-out error) with
robust fitting needed to keep using robust fitting during cross-
validation tests. The benefit is the difference between the
non-robust and robust weighted errors of the points left out,
i.e., the weights from robust fitting with no points left out
are applied identically to the prediction errors of the points
left out without and with robust fitting. When the benefit is
less than the give amount, robust fitting will be omitted in
order to speed up the tests. The default is 2%.
-cvorder (-cv) OR -CrossValTestOrder Multiple integers
Order in which different variables are tested with cross-valida-
tion. variables are numbered as follows and the default is to
test in this order
1: X stretch and skew
2: Variable tilt around the X axis
3: Tilt
4: Rotation
5: Magnification
6: Single variables: beam tilt, single X-tilt, projection
stretch
Fewer than 6 numbers may be entered; they will replace the
first ones in order list and must be different from the remain-
ing values. The same order will apply to local variable tests,
although only 1, 3, 4, and 5 are relevant there.
-onestep (-on) OR -OneStepPerVariableTest Integer
Make only one change for a variable before testing other vari-
ables. With an entry of 0, the program will test all the possi-
ble restrictions on the first variable in the testing order and
adopt each restriction that improves the leave-out error, then
do the same for the second variable, etc. With the default
value of 1, the program will test restrictions on a variable
until an improvement occurs, accept that restriction, then go on
to the next variable. It will cycle through the variables
repeatedly until there is nothing left to test. When testing
both local variables and local areas, it will alternate between
a change in variable and a change in local area. With an entry
of 2 or 3, the program will test restrictions on a variable
until the first improvement occurs, but not accept the restric-
tion. After all variables have been tested, it will accept the
restriction that gave the biggest or smallest improvement with
an entry of 2 or 3 respectively. Then it will cycle through the
variables again, until finished.
-permute (-p) OR -TestPermutations Multiple integers
List of variables for which to try all permutations in testing
order when evaluating global variables. These variables will
exchange positions with each other in the order and others will
keep their defined positions. The whole sequence of tests is
run for each permutation, so this will take 6 times as long to
permute 3 variable, and 24 times as long to permute 4. Vari-
ables are numbered as in -cvorder above. If this option is
entered, the default value of -onestep becomes 0 and a non-zero
entry for -onestep will give an error. This option will be
ignored if local alignments are being evaluated.
-skipbeam (-s) OR -SkipBeamTiltWithOneRot
By default, the program will add a solution for beam tilt if and
when it switches to solving for only one rotation angle. (If
parameters are already set to solve for only one rotation angle,
this switch does not occur and it will not add beam tilt.) With
this option, it will not add the beam tilt solution along with
this restriction.
-trial (-tr) OR -TrialMode
Output modifications to a different command file instead of
replacing the input file. The output file will be named as the
root of the input file plus "_new.com"
-verbose (-ve) OR -VerboseOutput
Output the errors at each step when doing cross-validation
-PID Print process ID
-help (-h) OR -usage
Print help output
-StandardInput
Read parameter entries from standard input
FILES
The input file is renamed by adding a ~ to the end of its name and
replaced with the new file, or new file is produced in trial mode with
the root of the input name followed by "_new.com".
AUTHOR
David Mastronarde
SEE ALSO
tiltalign
BUGS
Email bug reports to mast at colorado dot edu.
IMOD 5.2.1 restrictalign(1)