tiltalign

tiltalign(1) General Commands Manual tiltalign(1)
NAME
 tiltalign - Solve for alignment of tilted views using fiducials
SYNOPSIS
 tiltalign
DESCRIPTION
 This program will solve for the displacements, rotations, tilts, and
 magnification differences relating a set of tilted views of an object.
 It uses a set of fiducial points that have been identified in a series
 of views. These input data are read from a model in which each fiducial
 point is a separate contour.
 This program has several notable features:
 1) Any given fiducial point need not be present in every view. Thus,
 one can track each fiducial point only through the set of views in
 which it can be reliably identified, and one can even skip views in the
 middle of that set.
 2) The program can solve for distortion (stretching) in the plane of
 the section. It does so with two additional variables: "dmag", an
 increment to the magnification along the X axis; and "skew", the dif-
 ference in rotation between the X and Y axis. If there is stretch in
 the plane of the sections, then in general the aligned images will
 backproject correctly only at one plane in Z. This solution thus
 includes a set of adjustment factors that can be passed to the Tilt
 program to correct for this effect.
 3) It is possible to constrain several views to have the same unknown
 value of rotation, tilt angle, magnification, compression, or distor-
 tion. This can reduce the number of unknowns and can give more accu-
 rate overall solutions.
 4) If the fiducial points are supposed to lie in one or two planes,
 then after the minimization procedure is complete, the program can ana-
 lyze the solved point positions and determine the slope of this plane.
 It uses this slope to estimate how to adjust tilt angles so as to make
 the planes be horizontal in a reconstruction.
 5) The program can solve for a series of local alignments using subsets
 of the fiducial points. This can be useful when aligning a large area
 which does not behave uniformly during the tilt series. The local
 alignments can then be used to obtain a single large reconstruction
 whose resolution is as good as would be attained in a smaller volume.
 6) The program can use a robust fitting method to give different
 weights to different modeled points based on their individual fitting
 errors. Points with the most extreme errors are eliminated from the
 fit, and ones with high but less extreme errors are down-weighted.
 This fitting provides a substitute for fixing many modeled point posi-
 tions based on their errors.
 7) The program includes an option for cross-validation, which measures
 how well a solution can predict the positions of points that are left
 out of the fitting. The method is useful for optimizing the selection
 of parameters to be fit and avoiding overfitting with too many parame-
 ters.
 Mapping of Variables
 The constraining of different views to have related values of some
 unknown variable is called "mapping"; it works differently for tilt
 than for other variables. For variables other than tilt, if two or
 more views are mapped to the same variable, then all of those views
 will have the same value. For tilt angle, if two views are mapped to
 the same tilt variable, then the DIFFERENCE between their tilt angles
 is constrained to be a constant equal to the difference between their
 initial tilt angles. So, if they have the same initial tilt angle,
 they will always have the same tilt; and if their initial tilt angles
 differ by 10, their tilt angles will always differ by 10.
 Mapping can be set up relatively easily with "automapping". When you
 select automapping, the program will map views in a group of adjacent
 views to the same variable, and it will determine a set of groups of a
 specified size. You control the mapping by specifying the default size
 of the groups. In addition, if some views need to be grouped differ-
 ently, you can specify one or more ranges of views to have different
 sized groups.
 With automapping, the program can also set up variables that change
 linearly from one group to the next, rather than being constrained to
 the same value for all views in a group. In other words, the values
 for all of the views in a group will be a linear combination of the
 same two actual variables (typically the first one in the group and the
 first one in the next group). This feature usually gives a solution
 with less error. The distinction between actual variables and combina-
 tions can be seen in the "Variable mappings" table. Actual variables
 would appear as, e.g., "tilt 15" and "tilt 25", while combinations of
 the two appear as "t 15+ 20". There are also linear combinations
 between a variable and a fixed value, which appear in the table as "t
 70+fix". Currently, the linear mapping is available only with automap-
 ping, not with manually specified mappings.
 With automapping, the size of the groups will be adjusted dynamically
 for two variables, tilt angle and x-axis stretch, so that groups become
 smaller at higher tilt angles. This is done because it is easier to
 solve accurately for tilt angle at higher tilt, and because the solu-
 tion for x-axis stretch tends to change rapidly at high tilts. The
 group size that you specify for these variables will be the average
 size of the whole range of tilts. If this dynamic automapping gives
 problems with tilt angle, use mapping in blocks rather than linear map-
 ping to have stricter control over the mapping process. The dynamic
 automapping is used for both kinds of mapping of x-axis stretch because
 the mapping in blocks is the preferred method for grouping this vari-
 able. (Linear mapping does not always work properly.)
 The size of groups when automapping will also be adjusted to provide
 more grouping when some views have only one or two points. Specifi-
 cally, views with fewer than 3 points will not be counted toward the
 total number of views to be included in a group. This feature is most
 important with the local alignments described next, where there may be
 relatively few points in a local area.
 Local Alignments
 The program can embark on local alignments after obtaining the standard
 global solution with all of the fiducials. The program divides the
 image area, or the area occupied by fiducials, into a regular array of
 overlapping subareas. Fiducials whose X and Y coordinates fall within
 a subarea are included in the computations for that subarea. A subarea
 is expanded about its center, if necessary, to include a certain mini-
 mum number of fiducials. The program then seeks a solution for the
 subset of fiducials that is, for all variables, "incremental" to the
 global solution; that is, it solves for variables that are added to the
 parameters from the global solution. This method allows a dramatic
 reduction in the number of variables to be solved for, mostly because
 rotation and magnification can be mapped to a much smaller number of
 variables than in the global solution. The usual need for each view to
 have its own rotation and magnification variable is already accommo-
 dated in the global solution.
 One option in the local alignment is whether to solve for the X-Y-Z
 coordinates of the subset of fiducials, or to fix them at their values
 from the global solution. Solving for the coordinates may give a more
 accurate solution but it does require more fiducials to get a reliable
 result. Fixing the coordinates reduces the number of variables to be
 solved for and allows a reliable solution with only a relatively few
 fiducials; it also avoids distortions in the resulting reconstruction
 that could be difficult to account for when trying to combine recon-
 structions from tilts around two axes.
 Robust Fitting
 The goal in robust fitting is to reduce the effect of incorrectly
 placed model points on the fitted solution by giving less weight to
 points which appear to be outliers. Because it is not possible to be
 certain about which points are indeed incorrect, each point is given a
 weight that depends on how large its error is relative to that of other
 points. When the option to use robust fitting is selected, the program
 first obtains a global alignment solution, or one for a local area,
 which gives a residual error value for each projection point. The
 residual values are analyzed to derive a weight between 0 and 1 for
 each one, and the fitting routine is call again to refine the solution
 with these weights. This solution provides new residuals, and this
 process is repeated until the weights do not change significantly or
 until the fitting routine only runs for one iteration several times in
 a row. At the end, the program prints out the final F value from the
 fit, which is the square root of the mean squared weighted errors, and
 it also prints a weighted mean residual value immediately after the
 ordinary mean. It also prints a line showing the number of weights
 that were set to 0, less than 0.1, less than 0.2, and less than 0.5.
 The latter number is usually about 5% of the total points. The numbers
 of down-weighted points can be increased or decreased by entering the
 KFactorScaling with a value less than or greater than 1, respectively.
 The weights are derived by the following method. The median residual
 is first obtained for each view from the errors of the unweighted fit,
 and these values are smoothed to obtain a curve for the dependence of
 median residual on view number. The projection points are divided into
 groups of about 100 by forming groups of adjacent views, and, for the
 global solution, by sorting the points into concentric rings based on
 distance from the center. These two measures are used to reduce the
 influence of systematic variations in residual error with tilt angle
 and with distance from the center on the detection of incorrectly posi-
 tioned points. For a group of points, each point's residual is divided
 by the smoothed median residual for that point's views. The median of
 the values is found, as well as the normalized median absolute devia-
 tion from the median (the MADN). For each point with residual greater
 than the median, the value
 x = (residual - median) / (K * MADN)
 is computed, where K is the K factor (4.685 by default), and the weight
 is
 (1 - x**2)**2
 for x < 1, or 0 for x > 1.
 The Alignment Model
 The program implements the following model for the imaging of the spec-
 imen in each individual view:
 1) The specimen itself changes by
 a) an isotropic size change (magnification variable);
 b) additional thinning in the Z dimension (compression variable); and
 c) linear stretch along one axis in the specimen plane, implemented by
 variables representing stretch along the X axis and skew between
 the X and Y axes;
 2) The specimen is tilted slightly around the X axis (X tilt variable)
 3) The specimen is tilted around the X axis by the negative of the beam
 tilt, if any (one variable for all views)
 4) The specimen is tilted around the Y axis (tilt variable)
 5) The specimen is tilted back around the X axis by the beam tilt, if any
 6) The projected image rotates in the plane of the camera (rotation
 variable)
 7) The projected image may stretch along an axis midway between the
 original X and Y axes (one variable for all views)
 8) The image shifts on the camera
 Only a subset of this complete model can be solved for in any given
 case. In particular, thinning cannot be solved for together with tilt
 angle and stretch along the X axis; it is very difficult to solve for X
 axis tilt together with rotation angle; and it is almost impossible to
 solve for beam tilt together with rotation and skew.
 The complete model is summarized in:
 Mastronarde, D. N. 2008. Correction for non-perpendicularity of beam
 and tilt axis in tomographic reconstructions with the IMOD package. J.
 Microsc. 230: 212-217.
 The version of the model prior to the addition of beam tilt is
 described in more detail in:
 Mastronarde, D. N. 2007. Fiducial marker and hybrid alignment methods
 for single- and double-axis tomography. In: Electron Tomography, Ed.
 J. Frank, 2nd edition, pp 163-185. Springer, New York.
 Cross-validation
 For cross-validation, the program does many fits, each with a subset of
 points left out, and predicts the position of each of the left-out
 points from the solution obtained without them. The errors in these
 predictions are averaged and reported as the "leave-out error". This
 error is a valid indicator of whether solving for additional parameters
 truly improves the solution. In contrast, the mean residual error of a
 fit will always go down when parameters are added, and there is no good
 indication of whether the solution is indeed better or is just overfit-
 ting to accommodate random errors. The program Restrictalign can
 test systematically for whether more restricted parameters will improve
 the leave-out error.
 The default parameters will leave out segments of 5 points on adjacent
 views, and evaluate prediction errors on the 3 middle points of each
 segment. About 10% of points are left out on each fit, and enough fits
 are done with different sets of points to accumulate an error value
 accurate enough to compare between parameter selections. The padding
 by one point is intended to reduce the influence on the solution of a
 possible dependency between adjacent points. This strategy is used to
 avoid several problems with leaving out whole contours, the most impor-
 tant two being: 1) When there are fewer than 10 fiducials, more than
 10% of points have to be left out, which could destabilize the solu-
 tion. 2) When there are fewer than 20 fiducials, only one will be left
 out of each fit and there will be only as many unique runs as the num-
 ber of fiducials, limiting the accuracy of the result.
 The disadvantage of cross-validation is that it does require multiple
 fits, so the computational time could be 20-50 times higher than for a
 single fit. This is particularly problematic if robust fitting is used
 as well, and one strategy (used by Restrictalign) is to turn off
 robust fitting during the validations unless it is beneficial enough.
 When cross-validation is used with robust fitting, the output of leave-
 out errors is more complex. It has this form:
 Global non-robust leave-out error (10888 pts): 0.3111 nm weighted 0.2720 nm
 Global robust leave-out error (10888 pts): 0.3026 nm weighted 0.2638 nm
 Benefit from robust fitting: unweighted 0.0084 weighted 0.0082 nm
 On the first line, the first value (0.3111) is the error of the left-
 out points in the unweighted solution before robust fitting. Results
 from robust solution are on the second line: first the mean error with
 no weights applied, then the error after applying the weights from the
 full robust solution that included all the points. The first value
 includes all the points that have been downweighted or eliminated in
 the robust solution with all points and is thus the result of two coun-
 tervailing factors: the errors of those points should have increased
 while the error of the remaining points decreased. The second value
 from robust fitting appropriately discounts the outlying points. It
 can be compared with the second value on the first line, in which the
 errors of points left out of the non-robust solution have been multi-
 plied by the same weights used for the weighted errors from the robust
 solution. Since potentially outlying points have been discounted in
 the identical way in the two weighted values, their difference (the
 second value on the "Benefit" line) is the best measure of how much
 benefit robust fitting gave. A negative value indicates that the
 robust solution is actually worse.
OPTIONS
 Tiltalign uses the PIP package for input (see the manual page for
 pip) and can no longer take sequential input interactively. The
 following options can be specified either as command line arguments
 (with the -) or one per line in a command file or parameter file (with-
 out the -). Options can be abbreviated to unique letters; the cur-
 rently valid abbreviations for short names are shown in parentheses.
 In all entries of view numbers, the views are numbered from 1.
 INPUT AND OUTPUT FILE OPTIONS
 These options give information about input and output files.
 -ModelFile File name
 Input fiducial model file
 -ImageFile File name
 Image file that fiducial model was built on, used to obtain
 information for scaling the model. If this entry is omitted,
 the program will use values entered with ImageSizeXandY, ImageO-
 riginXandY, and ImagePixelSizeXandY, or values from the model
 itself if those options are omitted. In general, the informa-
 tion from the model header should be sufficient and none of
 these entries should be needed.
 -ImageSizeXandY Two integers
 Dimensions of image file (optional)
 -ImageOriginXandY Two floats
 X and Y origin values from image file header (optional)
 -ImagePixelSizeXandY Two floats
 X and Y Pixel spacing from image file header, in Angstroms
 (optional)
 -UnbinnedPixelSize Floating point
 Pixel size of unbinned data in nanometers
 -ImagesAreBinned Integer
 The current binning of the images relative to the original data.
 This factor is used to scale the values entered with AxisZShift
 and AxisXShift from unbinned to binned coordinates. The default
 is 1.
 -OutputModelFile File name
 File in which to place 3-D model of the fiducials based on their
 solved positions
 -OutputResidualFile File name
 Output file for a list of the residuals at all projection
 points, which can be converted to a model with Patch2imod.
 These residuals are in pixels.
 -OutputModelAndResidual File name
 Root name for output of both a 3-D model and residuals; the
 files will have extensions .3dmod and .resid, respectively.
 -OutputFilledInModel File name
 Output file for fiducial model with missing points filled in on
 the views included in the solution. This model can be used for
 erasing fiducial markers. A missing point is first computed
 from the projection position of the solved 3-D position of the
 fiducial. Then, a line is fit to the residuals of points on the
 6 nearest views and an estimated residual is subtracted from the
 projection position, in order to incorporate a consistent dis-
 parity between the fiducial positions and the solution. Projec-
 tion positions from a global solution are replaced by ones from
 local solutions, if any, and ones from multiple local areas are
 averaged. This option is ignored for a model from patch track-
 ing.
 -OutputTopBotResiduals File name
 Root name for output of residuals for fiducials on the top and
 bottom surfaces into separate files, with extensions .topres and
 .botres.
 -OutputFidXYZFile File name
 File for text output of the solved X-Y-Z coordinates
 -FixedXYZInputFile File name
 File with fixed X-Y-Z coordinates to use in local alignments.
 The values will be used when initializing the coordinates for
 the search in each local area, but they will have little effect
 unless -FixXYZCoordinates is entered. Each line of this file
 should start with the three coordinates; numbers after that are
 ignored. There must be the same number of lines in the file as
 the number of fiducials.
 -OutputTiltFile File name
 Output file for the solved tilt angles after adjustment for beam
 tilt, if any
 -OutputUnadjustedTiltFile File name
 Output file for the solved tilt angles before adjustment for
 beam tilt, if any
 -OutputXAxisTiltFile File name
 Output file for tilts around the X axis.
 -OutputTransformFile File name
 Output file for 2-D transformations needed to align images
 -OutputZFactorFile File name
 Output file for factors to adjust X and Y as function of Z in
 backprojection. When there is specimen stretch along an axis, a
 2-D transformation of the projections cannot fully correct for
 this effect, and these factors are needed to adjust the backpro-
 jection position for different Z heights in the reconstructed
 slice.
 ANGLE AND VIEW RELATED OPTIONS
 These options provide information about tilt angles and the views to
 be included in the analysis.
 -IncludeStartEndInc Three integers
 Starting and ending view numbers, and increment between views,
 to include in analysis. This option, IncludeList, and
 ExcludeList are mutually exclusive. The default is to include
 all views that have points in the model.
 -IncludeList List of integer ranges
 List of views to include in the analysis (ranges allowed)
 -ExcludeList List of integer ranges
 List of views to exclude from the analysis (ranges allowed)
 -RotationAngle Floating point
 Initial angle of rotation in the plane of projection. This is
 the rotation (CCW positive) from the Y-axis (the tilt axis after
 the views are aligned) to the suspected tilt axis in the
 unaligned views.
 -SeparateGroup List of integer ranges
 List of views that should be grouped separately in automapping.
 Multiple entries can be used to specify more than one set of
 separate views. (Successive entries accumulate)
 -NoSeparateTiltGroups Integer
 Allow tilt angles to be grouped across separate view groups in
 order to prevent large jumps in the solved tilt angles. Enter 1
 to allow this grouping with a patch tracking model, or 2 to
 allow it for any fiducial model.
 -first (-f) OR -FirstTiltAngle Floating point
 Tilt angle of first view, in degrees. Use this option together
 with TiltIncrement.
 -increment (-i) OR -TiltIncrement Floating point
 Increment between tilt angles, in degrees. Use this option
 together with FirstTiltAngle.
 -tiltfile (-t) OR -TiltFile File name
 Use this option if tilt angles are in a file, one per line.
 -angles (-a) OR -TiltAngles Multiple floats
 Use this option to enter the tilt angles for each view individu-
 ally, in degrees. (Successive entries accumulate)
 -AngleOffset Floating point
 Amount to add to all entered tilt angles.
 GLOBAL VARIABLE SELECTION OPTIONS
 These options specify the variables to be included in the global fit
 to all of the points and information about them, such as group sizes.
 -ProjectionStretch
 Solve for a parameter representing a skew between the microscope
 X and Y axes that occurs during projection of all images. This
 is equivalent to a stretch along a 45-degree line between the
 axes. A component of stretch parallel to the axes cannot be
 distinguished from a stretch of the 3D fiducial coordinates par-
 allel to the axes, so as of IMOD 3.10.7 only this skew component
 is solved for. The initial rotation angle of the tilt axis is
 used to determine the approximate axis along which this stretch
 would occur after the final image rotation.
 -BeamTiltOption Integer
 Type of solution for non-perpendicularity between tilt axis and
 beam axis, referred to as beam tilt:
 0 for beam tilt fixed at the initial value,
 1 to include beam tilt as a variable in the minimization
 procedure,
 2 to perform the minimization at a series of fixed beam tilt
 values and search for the value that gives the smallest
 error.
 Because some variables can covary with the beam tilt to give
 nearly equivalent solutions, the second option for finding the
 beam tilt gives more reliable results. Some combinations of
 variable simply cannot be solved for, in particular the stretch
 variables and rotation together with beam tilt; either omit the
 stretch variables or solve for a single rotation angle. Note
 that only the component of the beam tilt around the X axis is
 solved for; the component around the Y axis is indistinguishable
 from a change in tilt angle. When the beam tilt is non-zero,
 either as a result of a search or because a fixed value was
 entered, its effect is expressed as a varying tilt around the X
 axis and a modification of the tilt angles and in-plane image
 rotations. Thus, a file of X-tilt angles should be output when
 beam tilt is included in the solution.
 -FixedOrInitialBeamTilt Floating point
 The entry provides either an initial value for the beam tilt,
 when it is being solved for, or a fixed value when it is not.
 -RotOption Integer
 Type of rotation solution:
 0 for all rotations fixed at the initial angle,
 1 for each view having an independent rotation,
 2 to enter general mapping of rotation variables,
 3 or 4 for automapping of rotation variables (3 for linearly
 changing values or 4 for values all the same within a
 group), or
 -1 to solve for a single rotation variable.
 -RotDefaultGrouping Integer
 Default group size when automapping rotation variables
 -RotNondefaultGroup Three integers
 Starting 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)
 -RotationFixedView Integer
 Number of view whose rotation should be fixed at the initial
 rotation angle. This entry is relevant with any of the positive
 RotOption entries.
 -TiltOption Integer
 Type of tilt angle solution:
 0 to fix all tilt angles at their initial values,
 1 to solve for all tilt angles except for a specified view,
 2 to solve for all tilt angles except for the view at minimum
 tilt,
 3 to solve for all tilt angles except for a specified view and
 the view at minimum tilt,
 4 to specify a mapping of tilt angle variables,
 5 or 6 to automap groups of tilt angles (5 for linearly
 changing values or 6 for values all the same within a
 group), or
 7 or 8 to automap and fix two tilt angles (7 for linearly
 changing values or 8 for values all the same within a group)
 -TiltFixedView Integer
 Number of view at which to fix the tilt angle (required with
 TiltOption 1, 3, 7, or 8)
 -TiltSecondFixedView Integer
 Number of second view at which to fix the tilt angle (required
 with TiltOption 7 or 8)
 -TiltDefaultGrouping Integer
 Average default group size when automapping tilt variables
 -TiltNondefaultGroup Three integers
 Starting 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)
 -MagReferenceView Integer
 Number of reference view whose magnification will be fixed at
 1.0. The default is the view at minimum tilt.
 -MagOption Integer
 Type of magnification solution:
 0 to fix all magnifications at 1.0,
 1 to vary all magnifications independently,
 2 to specify a mapping of magnification variables, or
 3 or 4 for automapping of variables (3 for linearly changing
 values or 4 for values all the same within a group).
 -MagDefaultGrouping Integer
 Default group size when automapping magnification variables
 -MagNondefaultGroup Three integers
 Starting 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)
 -CompReferenceView Integer
 Number of the view to fix at compression 1.0 (something other
 than a view whose tilt angle is fixed at zero.) Required if
 CompOption not 0.
 -CompOption Integer
 Type of compression solution:
 0 to fix all compressions at 1.0,
 1 to vary all compressions independently,
 2 to specify a mapping of compression variables, or
 3 or 4 for automapping of variables (3 for linearly changing
 values or 4 for values all the same within a group).
 -CompDefaultGrouping Integer
 Default group size when automapping compression variables
 -CompNondefaultGroup Three integers
 Starting and ending view numbers and group size for a set of
 views whose compression variables should be grouped differently
 from the default. (Successive entries accumulate)
 -XStretchOption Integer
 Type of X-stretch solution:
 0 to fix all X stretches at 0,
 1 to vary all X stretches independently,
 2 to specify a mapping of X-stretch variables, or
 3 or 4 for automapping of variables (3 for values all the
 same within a group or 4 for linearly changing values).
 -XStretchDefaultGrouping Integer
 Default average group size when automapping X stretch variables.
 -XStretchNondefaultGroup Three integers
 Starting and ending view numbers and group size for a set of
 views whose X stretch variables should be grouped differently
 from the default. (Successive entries accumulate)
 -SkewOption Integer
 Type of skew solution:
 0 to fix all skew angles at 0.0,
 1 to vary all skew angles independently,
 2 to specify a mapping of skew variables, or
 3 or 4 for automapping of variables (3 for linearly changing
 values or 4 for values all the same within a group).
 -SkewDefaultGrouping Integer
 Default group size when automapping skew variables
 -SkewNondefaultGroup Three integers
 Starting and ending view numbers and group size for a set of
 views whose skew variables should be grouped differently from
 the default. (Successive entries accumulate)
 -XTiltOption Integer
 Type of X-axis tilt solution:
 0 to fix all X tilts at 0.,
 1 to vary all X-tilts independently,
 2 to specify a mapping of X-tilt variables, or
 3 or 4 for automapping of variables (3 for linearly changing
 values or 4 for values all the same within a group).
 -XTiltDefaultGrouping Integer
 Default group size when automapping X-axis tilt variables
 -XTiltNondefaultGroup Three integers
 Starting and ending view numbers and group size for a set of
 views whose X-axis tilt variables should be grouped differently
 from the default. (Successive entries accumulate)
 MINIMIZATION AND OUTPUT OPTIONS
 These options control the minimization procedure and the outputs of
 the program.
 -ResidualReportCriterion Floating point
 Criterion number of standard deviations above mean residual
 error that should be reported. This can be based on either the
 overall mean and S.d. of the residual errors, or on a mean and
 S.d. computed from points in nearby views. Enter a positive
 value for a report based on overall mean, or a negative value
 for a report based on the mean residual in the same and nearby
 views.
 -SurfacesToAnalyze Integer
 0 to omit surface analysis, or 1 or 2 to fit points to one or
 two surfaces and derive a surface angles and recommended tilt
 angle offset. This entry has no effect on the global alignment
 solution.
 -MetroFactor Floating point
 This entry determines how large a step the variable metric mini-
 mization procedure (METRO) tries to take. The default is 0.25,
 which typically works even for large data sets. When METRO
 fails for various reasons, the program will retry with several
 other nearby values of the factor.
 -MaximumCycles Integer
 Limit on number of cycles for minimization procedure (default
 1000).
 -AxisZShift Floating point
 Amount to shift the tilt axis in Z, relative to the centroid in
 Z of the fiducial points or relative to the original Z axis
 location if ShiftZFromOriginal is entered. It is also possible
 to enter 1000 to shift the tilt axis to the midpoint of the
 range of Z values. Enter this value in unbinned pixels.
 -ShiftZFromOriginal
 Apply Z shift relative to original tilt axis location. If
 images were initially aligned by cross-correlation, this option
 will keep specimen material near the center of the reconstruc-
 tion even if fiducials are on one surface.
 -AxisXShift Floating point
 Amount to shift the tilt axis in X away from the center of the
 image. Enter this value in unbinned pixels.
 ROBUST FITTING AND CROSS-VALIDATION OPTIONS
 These options control robust fitting to downweight outlying points
 and cross-validation by leaving out sets of points.
 -RobustFitting
 Use a robust fitting method that gives less weight to points
 with residuals higher than the median residual, and no weight to
 the most extreme points.
 -WeightWholeTracks
 When doing robust fitting with a model from patch tracking,
 assign the same weight to all the points in each contour. Con-
 tours with mean residuals higher than the median will thus be
 given less weight, and ones with the most extreme residuals will
 be given weights of 0.02.
 -KFactorScaling Floating point
 Amount to scale the K factor that controls how many points are
 down-weighted in the robust fitting. The default scaling of 1
 gives a K factor of 4.685, the factor commonly used for the
 Tukey bisquare weighting. A smaller factor will down-weight and
 eliminate more points.
 -WarnOnRobustFailure
 Give just a warning instead of exiting with an error if the
 robust fitting fails and only a global alignment is being done.
 If local alignments are being done, a failure in either the
 global alignment or a local area will always result in just a
 warning. In all cases, the non-robust alignment is restored
 after a failure.
 -MinWeightGroupSizes Two integers
 Minimum sizes of the groups of points used for computing
 weights, in global and local alignment runs. In order to apply
 the robust method to points that are relatively similar to each
 other, deviations from a median residual are computed within
 subsets of points that are located on adjacent views; and if
 there are enough points, the points in a global alignment run
 are also sorted into rings based on distance from the center.
 These entries set the minimum sizes of these groups. If the
 total number of points available for fitting falls below the
 minimum, the robust fitting is not done and a warning or error
 is issued. The defaults are 100 and 65 when adjusting weights
 for individual points. When assigning weights to whole contours
 with data from patch tracking, a similar approach is used to
 divide the contours into groups that are analyzed together.
 Here, the defaults are 30 and 20.
 -CrossValidate Integer
 Do cross-validation by leaving out sets of points in multiple
 runs. In each run, the positions of points left out are pre-
 dicted from the solution and a "leave-out" error is computed.
 This error is averaged over enough runs with different points
 left to give an estimate of leave-out error that is accurate
 enough for comparing the merit of different variable selections.
 Enter 1 to do this procedure for both global and local align-
 ments, or 2 to do it only for local aligments. The details of
 cross-validation are governed by the following options, which
 all have reasonable defaults.
 -FractionToLeaveOut Two floats
 Fraction of points to leave out of each cross-validation run.
 An entered value will be limited to be between 0.01 and 0.2.
 The default is 0.1 for 10 or more fiducials, or 0.1 times the
 number of fiducials for fewer than 10 fiducials, down to 0.04.
 -LeaveOutPredictAndPad Two integers
 Number of points on contiguous views to leave out as a group and
 from which to use predicted positions to measure the leave-out
 error; and number of additional points on each side of this
 group to leave out as padding. More padding will require more
 runs to reach a given accuracy level. If the first value is 0,
 whole contours (fiducials) will be left out in each run and the
 second value does not matter. The default is 3,1. ^ Completely
 unrelated to the function of this option, entering a negative
 value for the second number will cause the model to be treated
 as if it were from patch tracking. This is useful when analyz-
 ing a true fiducial model whose contours have been broken into
 pieces by Imodchopconts. It allows the program to identify
 which contours have come from the same point, which is important
 for determining the actual number of fiducials present in a
 local area. (The absolute value of this second number will be
 used for the padding entry.)
 -CVCoverageTargetOrFactor
 This entry determines how many cross-validation runs will be
 done with different sets of points left out and thus how accu-
 rate the estimated error will be. The value can be either a
 target number of points to get leave-out errors from, or a fac-
 tor whose product with the number of fiducials would be the
 desired number of points to get errors from. If whole contours
 are being left out, the total number left out may be limited.
 Specifically, if the number of fiducials times the fraction of
 points to leave out rounds down to 1 or less, then only one con-
 tour would be left out at once, and the number of runs would be
 limited to the number of fiducials. When more than one contour
 is left out per run, there is no redundancy with a coverage
 above 1 because different combinations of fiducials will be
 used. The default is 12000 points.
 -CVMinAndMaxCoverageFactor
 Minimum and maximum values for the actual coverage factor, or
 average number of times each point is left out. When the cover-
 age falls below the minimum and the number of points that would
 be used with the minimum coverage is more than twice the target
 number set by -CVCoverageTargetOrFactor, the coverage is reduced
 below the minimum and the number of points to be used is
 increased above twice the target by the same factor. This fea-
 ture reduces the excess computations that can happen with local
 alignments. The default is 0.3 and 5.
 -RandomSeed Integer
 A value for the seed of the random number generator used in
 cross-validation, or 0 for a seed computed from the current
 time. Using a fixed seed value for multiple runs is important
 when looking at the effects of changing alignment parameters
 because it minimizes variability between runs due to different
 sets of points being chosen. The default is to used a fixed
 seed.
 -TestSetIntervalOrFrac Floating point
 When running cross-validation by leaving out points or contours
 on multiple runs, a fraction of fiducials can be reserved as a
 test set as well. Solutions will be obtained using just the
 remaining points, including the multiple solutions with some of
 those points left out. The errors for the test set will be
 reported both for the full solution with the remaining points
 and for the cross-validation runs. This option is useful for
 validating the cross-validation itself but not for tuning param-
 eters in actual data sets without a large excess in the number
 of fiducials.
 LOCAL ALIGNMENT OPTIONS
 These options control local alignments.
 -LocalAlignments
 Do alignments with subsets of points in local areas. When this
 option is selected, the appropriate Local...Option values must
 be entered to control what variables are solved for; the default
 is 0 for all of the local option values.
 -OutputLocalFile File name
 Output file for transformations for local alignments
 -TargetPatchSizeXandY Two integers
 Target for the size of local patches in X and Y in which to
 obtain a solution from the fiducials located in that patch. The
 number of patches will be set so that patches smaller or up to
 5% larger than this size and overlapping by a fixed amount will
 fill the range occupied by fiducials (not the image area). The
 patches on the edges should not have to expand as much as when
 the patch centers are set up to fill the image area. If this
 option is entered, NumberOfLocalPatchesXandY must not be
 entered, and MinSizeOrOverlapXandY must specify an overlap
 instead of a size.
 -NumberOfLocalPatchesXandY Two integers
 Number of local patches in X and in Y in which to obtain a solu-
 tion from the fiducials located in that patch. For command
 files created by IMOD 5.0.1 or later, these values would apply
 if the X and Y fiducial coordinates cover the full range in X
 and in Y, and proportionally fewer patches will be used if the
 fiducial range is smaller. Similarly to when TargetPatch-
 SizeXandY is entered, patches will fill just the range occupied
 by fiducials, and MinSizeOrOverlapXandY must specify an overlap
 instead of a size. For older command files (specifically, for
 ones not having the CreatedDayStamp option with a value of at
 least 1658), overlapping patches will be set up that fill the
 image area; ones outside the range of fiducials, if any, will
 have to expand considerably to contain the required number of
 points.
 -MinSizeOrOverlapXandY Two floats
 Either the minimum fractional overlap between patches (values <
 1) or the minimum size of each patch in X and Y (enter values >
 1). The latter is allowed only for command files created before
 IMOD 5.0.1 and only when NumberOfLocalPatchesXandY is entered.
 The default is an overlap of 0.5.
 -MinFidsTotalAndEachSurface Two integers
 Minimum total number of fiducials, and minimum number present on
 each surface if two surfaces were assumed in the analysis of
 surfaces. A patch will be expanded about its center until it
 contains enough points to meet both of these criteria.
 -FixXYZCoordinates
 Fix the X-Y-Z coordinates of the fiducials at their values from
 the global solution; the default is to solve for them indepen-
 dently in each local area. For more on the implications of this
 option, see the note above in the section on local alignments.
 -LocalOutputOptions Three integers
 These three entries control the output of results for each local
 alignment:
 1 to output the values of the parameters for each view or 0
 not to;
 1 to output the X-Y-Z coordinates of fiducials or 0 not to;
 and
 1 to output points with high residuals, or 0 not to
 LOCAL VARIABLE SELECTION OPTIONS
 These options specify the variables to be included in the local
 alignment fits and information about them, such as group sizes.
 -LocalRotOption Integer
 Type of local rotation solution:
 0 for local rotations fixed,
 1 for each view having an independent rotation,
 2 to enter general mapping of variables,
 3 or 4 for automapping of rotation variables (3 for linearly
 changing values or 4 for values all the same within a
 group), or
 -1 to solve for a single rotation variable.
 -LocalRotDefaultGrouping Integer
 Default group size when automapping local rotation variables.
 -LocalRotNondefaultGroup Three integers
 Starting and ending view numbers and group size for a set of
 views whose local rotation variables should be grouped differ-
 ently from the default. (Successive entries accumulate)
 -LocalTiltOption Integer
 Type of local tilt angle solution; values 0-8 have same meaning
 as for global solution.
 -LocalTiltFixedView Integer
 Number of view at which to fix the tilt angle in the local solu-
 tion (required with LocalTiltOption 1, 3, 7, or 8)
 -LocalTiltSecondFixedView Integer
 Number of second view at which to fix the tilt angle in the
 local solution (required with LocalTiltOption 7 or 8)
 -LocalTiltDefaultGrouping Integer
 Average default group size when automapping local tilt variables
 -LocalTiltNondefaultGroup Three integers
 Starting and ending view numbers and group size for a set of
 views whose local tilt variables should be grouped differently
 from the default. (Successive entries accumulate)
 -LocalMagReferenceView Integer
 Number of reference view whose local magnification will be fixed
 at 1.0. The default is the view at minimum tilt.
 -LocalMagOption Integer
 Type of local magnification solution; values 0-3 have same mean-
 ing as for global solution.
 -LocalMagDefaultGrouping Integer
 Default group size when automapping local magnification vari-
 ables
 -LocalMagNondefaultGroup Three integers
 Starting and ending view numbers and group size for a set of
 views whose local magnification variables should be grouped dif-
 ferently from the default. (Successive entries accumulate)
 -LocalXStretchOption Integer
 Type of local X-stretch solution; values 0-3 have same meaning
 as for global solution.
 -LocalXStretchDefaultGrouping Integer
 Default average group size when automapping local X stretch
 variables
 -LocalXStretchNondefaultGroup Three integers
 Starting and ending view numbers and group size for a set of
 views whose local X stretch variables should be grouped differ-
 ently from the default. (Successive entries accumulate)
 -LocalSkewOption Integer
 Type of local skew solution; values 0-3 have same meaning as for
 global solution.
 -LocalSkewDefaultGrouping Integer
 Default group size when automapping local skew variables
 -LocalSkewNondefaultGroup Three integers
 Starting and ending view numbers and group size for a set of
 views whose local skew variables should be grouped differently
 from the default. (Successive entries accumulate)
 -LocalXTiltOption Integer
 Type of local X-axis tilt solution; values 0-3 have same meaning
 as for global solution.
 -LocalXTiltDefaultGrouping Integer
 Default group size when automapping local X-axis tilt variables
 -LocalXTiltNondefaultGroup Three integers
 Starting and ending view numbers and group size for a set of
 views whose local X-axis tilt variables should be grouped dif-
 ferently from the default. (Successive entries accumulate)
 MAPPING OPTIONS
 These are obsolete options for ultimate control of variable mapping.
 -RotMapping Multiple integers
 If RotOption is 2, this option must be used to enter a rotation
 variable number for each view. These variable numbers can be
 completely arbitrary, e.g. 1,1,1,3,3,3,5,5,5. The numbers are
 used to define block grouping. (Successive entries accumulate)
 -LocalRotMapping Multiple integers
 If LocalRotOption is 2, this option must be used to enter a
 local rotation variable number for each view. (Successive
 entries accumulate)
 -TiltMapping Multiple integers
 If TiltOption is 2, this option must be used to enter a tilt
 variable number for each view. (Successive entries accumulate)
 -LocalTiltMapping Multiple integers
 If LocalTiltOption is 4, this option must be used to enter a
 local tilt variable number for each view. (Successive entries
 accumulate)
 -MagMapping Multiple integers
 If MagOption is 2, this option must be used to enter a magnifi-
 cation variable number for each view. (Successive entries accu-
 mulate)
 -LocalMagMapping Multiple integers
 If LocalMagOption is 2, this option must be used to enter a
 local magnification variable number for each view. (Successive
 entries accumulate)
 -CompMapping Multiple integers
 If CompOption is 2, this option must be used to enter a compres-
 sion variable number for each view. (Successive entries accumu-
 late)
 -XStretchMapping Multiple integers
 If XStretchOption is 2, this option must be used to enter an X
 stretch variable number for each view. (Successive entries
 accumulate)
 -LocalXStretchMapping Multiple integers
 If LocalXStretchOption is 2, this option must be used to enter a
 local X stretch variable number for each view. (Successive
 entries accumulate)
 -SkewMapping Multiple integers
 If SkewOption is 2, this option must be used to enter a skew
 variable number for each view. (Successive entries accumulate)
 -LocalSkewMapping Multiple integers
 If LocalSkewOption is 2, this option must be used to enter a
 local skew variable number for each view. (Successive entries
 accumulate)
 -XTiltMapping Multiple integers
 If XTiltOption is 2, this option must be used to enter an X-axis
 tilt variable number for each view. (Successive entries accumu-
 late)
 -LocalXTiltMapping Multiple integers
 If LocalXTiltOption is 2, this option must be used to enter a
 local X-axis tilt variable number for each view. (Successive
 entries accumulate)
 OTHER OPTIONS
 -CreatedDayStamp Integer
 A value indicating when the command file was created, so that
 the program can determine whether to use old or new behavior for
 some options. Copytomocoms sets this with the number of days
 since January 1, 2020.
 -param (-p) OR -ParameterFile Parameter file
 Read parameter entries as keyword-value pairs from a parameter
 file.
 -help (-h) OR -usage
 Print help output
 -StandardInput
 Read parameter entries from standard input.
 Note: when compression is solved for, the program prints both the abso-
 lute and the incremental compression for each view. When no compres-
 sion is solved for, the program prints instead two additional columns:
 "deltilt" is the difference between the solved and original tilt
 angles, and "mean resid" is the mean residual error for each view.
FILES
 Files generated by Tiltalign for use by other programs have the follow-
 ing formats:
 The file with alignment transforms (option OutputTransformFile) con-
 tains one line per view, each with a linear transformation specified by
 six numbers:
 A11 A12 A21 A22 DX DY
 where the coordinate (X, Y) is transformed to (X', Y') by:
 X' = A11 * X + A12 * Y + DX
 Y' = A21 * X + A22 * Y + DY
 The file with solved tilt angles (option OutputTiltFile) has the angle
 in degrees for each view, one per line.
 The file with X-axis tilt angles (option OutputXAxisTiltFile) has the
 angle in degrees for each view, one per line.
 The file with Z factors (option OutputZFactorFile) has two numbers on
 one line for each view, the displacement in X and the displacement in Y
 per pixels of deviation in Z from the midplane.
 The file with all residuals (option OutputResidualFile) starts with a
 line with the number of residuals to follow, then has five values per
 line for each residual:
 X Y Z X_residual Y_residual
 It can be converted to a model by running Patch2imod with no special
 options.
 The file with solved X-Y-Z coordinates (option OutputFidXYZFile) has
 one line per 3D point:
 fiducial_# X Y Z object_# contour_#
 The first line has, after these values, the pixel size and the size of
 the image file that the alignment was run with:
 Pix: pixel_in_Angstroms Dim: X_size Y_Size
 The file of local alignments (option OutputLocalFile) has a header line
 with:
 #_X #_Y X_start Y_start dX dY if_Xtilts pixel_Angstroms if_Zfactors
 where #_X and #_Y are number of patches in X and Y, X/Y_start are the
 centers of the first patches in X and Y, dX and Y are the spacing
 between patches in X and Y, if_Xtilts is 1 if there are X-axis tilts,
 pixel_Angstroms is the pixel size of the image file, and if_Zfactors is
 1 if there are Z factors.
 Following the header is a block of data for each local area, where
 areas progress in X then in Y. The data are all expressed as incre-
 ments to the global alignment information. The elements in each block
 are:
 Tilt angles, one per view, many per line
 X-axis tilt angles if they are included, one per view, many per line
 Z factors if they are included, a pair of X and Y factors for each
 view, several pairs per line
 Refinement transformations for each view in the same format as above,
 one per line
HISTORY
 Written by David Mastronarde, March 1989, based on programs ALIGN and
 ALIGNXYZ (Mike Lawrence, 1982) obtained from R.A. Crowther at the MRC
 5/19/89 added model output, changed format of output table
 6/21/89 added mean residual output to find_surfaces, changed to
 get recommendation on maximum FIXED tilt angle
 4/9/93 allow full mapping of compression variables
 10/30/95 added distortion, automapping, point & angle output.
 10/17/98 added linear combinations to automapping
 2/12/98 added local alignments; changed find_surfaces to find and
 recommend an X-axis tilt.
BUGS
 Email bug reports to mast at colorado dot edu.
IMOD 5.2.0 tiltalign(1)