stitchalign(1) General Commands Manual stitchalign(1)NAMEstitchalign - compute alignment for stitching montage of overlapping volumesSYNOPSISstitchalign [options] supermontage_info_fileDESCRIPTIONStitchalign computes an alignment between a montage of overlapping tomograms (referred to as a supermontage) so that they can be stitched into a single volume. It does this using information about the local displacements in the overlap zones between each pair of adjacent vol- umes, i.e., the patch vectors produced by Corrsearch3d. It also uses values for the overall displacements between the volumes computed by Edgepatches and stored in the supermontage info file. The first step is to compute a single rotation in the X/Y plane, and overall shifts of the volumes, that would bring their centers onto a regular rectangular grid. This rotation can compensate for the effects of the tilt axis not being perpendicular in the original images. Specifically, if the data were acquired on a regular grid of positions in the camera coordinate system, the reconstructions end up being stag- gered from one another by the rotation of the tilt axis to the verti- cal, and this rotation will correct for the staggering. If the value found is not appropriate, there is an option to supply a specific value instead. In addition, if the angle between the pieces is not related to this tilt axis effect, you might want to prevent rotation entirely. The next step is to compute a set of single transformations, one per volume, that best aligns the volumes. The parameters available for alignment are rotation about the three axes (referred to as alpha, beta, and gamma), an overall size change (referred to as magnifica- tion), stretch along one axis in the X/Y plane (expressed as stretch of the Y axis relative to the X axis and rotation of the Y axis relative to the X axis), and a thinning factor in the Z dimension. Any subset of the parameters can be selected; the rotations are included by default and there is one option to exclude one or more of them; there are three separate options for including the magnification, stretch, and thinning. The parameters are found using the same variable metric minimization routine used by Tiltalign. The program can do a single search that includes the parameters for all volumes at once, but this turns out not to work, apparently because of multiple minima produced by competing alignments between different pairs of valumes. Thus, the program will do a separate search for each pair of overlapping volumes, then resolve the relative alignment parameters between pairs of volumes into a set of parameters for the individual volumes. These single transformations may leave substantial misalignments in the overlap zones. The final step uses the remaining local displacements in the overlap zones to compute the amount that each volume needs to be displaced locally to bring it into alignment with an adjacent volume (which is also being displaced locally). The result is a set of patch vectors for each volume, which Findwarp can use to find a series of transformations for warping each volume into the final alignment. By default, these vectors are produced on a finer grid than the original patch vectors for the overlap zones. This oversampling may not be nec- essary if the original vectors are relatively finely spaced; it can be controlled by the -spacing option. Tomostitch takes this spacing factor into account when running Findwarp so that the local fits will require about the same amount of original data as if the spacing were unchanged. Within this program, there is no local fitting to patch vectors in order to determine the quality of fit and to identify aberrant dis- placements. Bad vectors in the input files will generally produce bad warping vectors that are hard to eliminate. It is thus critical to get as reliable a set of patch vectors from Edgepatches as possible, to use Fitpatches to assess the quality of fit and provide local fit- ting information for Stitchalign, and to manually remove aberrant vec- tors from patch models where necessary. Stitchalign will use the out- put from Fitpatches in several ways. It will read all available patch vector files for an overlap zone: the original patch vectors, the "reduced" patch vectors with correlation coefficients produced by removing the large linear component from the patch vectors, and the patch vectors that have been passed through Findwarp to obtain residual and outlier information. A vector will be eliminated from the analysis if it is not still present in all available patch files; thus, you can edit whichever patch model you prefer. A vector will be elimi- nated if the fraction of times it has been removed from Findwarp fits as an outlier exceeds a criterion. Vectors with high residuals can also be eliminated based on a criterion, but this does not happen by default because it is hard to set a default criterion. You can run the alignment on subsets of the data either for experimen- tation or if that subset is going to be stitched. Ultimately, all of the volumes to be stitched must be included in one run of the program - it is not possible to run one subset with one set of parameters and another subset with other parameters then combine those results into a single alignment. The size of the volumes to be stitched together by Tomostitch is set when Stitchalign is run. The default is the largest size of the input volumes, but it can be controlled with the -size parameter. If over- sized tomograms were generated to retain data that would otherwise be lost because of the tilt axis rotation, then this is the point at which a size close to that of the original data can be specified.OPTIONSStitchalign uses the PIP package for input exclusively (see the manual page for pip). The following options can be specified either as command line arguments (with the -) or one per line in a command file or parameter file (without the -). Options can be abbreviated to unique letters; the currently valid abbreviations for short names are shown in parentheses.-info(-i)OR-InfoFileFilenameName of autodoc-type file with information about the supermon- tage. If this option is not entered, the first non-option argu- ment will be taken as the name of the info file.-zvalues(-z)OR-ZvaluesToDoListofintegerrangesList of Z values at which to run the analysis (comma-separated ranges allowed). The default is to do all Z values.-rotation(-ro)OR-RotationInXYplaneFloatingpointAngle to rotate all volumes in the X/Y plane. If this option is not entered, the program will find the angle that brings the centers of the aligned volumes onto a rectangular grid. Enter an angle or zero to override this behavior.-size(-si)OR-SizeOfOutputFramesXandYTwointegersSize in X and Y of transformed files to be created by Matchvol or Warpvol. The default is the size of the largest input vol- ume.-mag(-ma)OR-FindMagnificationFind overall magnification factors-stretch(-st)OR-FindStretchFind in-plane stretch parameters, which are expressed as size change and rotation of the Y axis relative to the X axis.-thinning(-t)OR-FindThinningFind thinning factors, factors by which to change the thickness of the volumes.-angles(-an)OR-FindAnglesThreeintegersValues or 1 or 0 indicating whether to find rotations around X, Y, and Z, respectively. The default is 1,1,1, so this option would be used to turn off solutions for some angles.-metro(-me)OR-MetroFactorFloatingpointInitial step size or "metro factor" in the minimization proce- dure; the default is 0.24. Vary this value slightly if a mini- mization fails.-xrun(-x)OR-XRunStartEndTwointegersStarting and ending volumes in X to analyze, numbered from 1. The default is to do all volumes in X.-yrun(-y)OR-YRunStartEndTwointegersStarting and ending volumes in Y to analyze, numbered from 1. The default is to do all volumes in Y.-residual(-re)OR-WarpFitResidualCriterionFloatingpointCriterion residual from fits in Findwarp for excluding vec- tors; vectors with mean residual greater than or equal this to value will be excluded. The default value of 100 will generally not exclude any vectors. Use Fitpatches to produce an appro- priate patch file with residuals.-outlier(-o)OR-OutlierFractionCriterionFloatingpointCriterion fraction of times that a vector was excluded as an outlier from fits in Findwarp; vectors with an outlier frac- tion greater than or equal this to value will be excluded here. The default is 0.33. Use Fitpatches to produce an appropri- ate patch file with outlier fractions.-spacing(-sp)OR-VectorSpacingFactorFloatingpointThis factor makes the spacing of the vectors put out in the warping fields for each volume be less than the spacing of the patch vectors measured in the overlap zones. The default is 0.7, which makes the density of warping vectors be about three times higher than the density of the patch vectors.-all(-al)OR-AllTogetherAnalyze all volumes in a single minimization procedure. The default is to get a solution for each pair of overlapping vol- umes and resolve the results into a single solution. When parameters are searched for all volumes together, the results are poor, probably due to multiple minima.-param(-p)OR-ParameterFileParameterfileRead parameter entries as keyword-value pairs from a parameter file.-help(-h)OR-usagePrint help output-StandardInputRead parameter entries from standard input.FILESStitchalign produces two files for each volume included in the analy- sis: piecename.matxf File with single linear transformation piecename.patch File with patch vectors for computing a warping It also produces a file "sectionmame.ecdstub" with the displacements between pieces needed when blending.HISTORYWritten by David Mastronarde, April 2007BUGSEmail bug reports to mast at colorado dot edu. IMOD 4.10.22 stitchalign(1)