1. The "section number" of a view is its physical location in the file, numbered from zero. It is used when referring to sections in SerialEM or Newstack.
2. The "Z value" of a view is what its section number would be in a file arranged in order; it is also numbered from zero. These are the Z values in a model of fiducial points.
3. The "view number" is the sequential number of the view in the tilt series, starting from 1. Beadtrack, Tiltalign and Tilt refer to views by "View number".

Yes, this presents endless possibilities for confusion. To reduce the confusion, I'll at least refer to them consistently as "section number", "Z value", and "view number".

1.5. Backup Files

If electron density appears as white in your images, Beadtrack will fail to track your fiducials properly with the default settings in track.com. Simply change the entry on the line ending in "0 for dark beads" from 0 to 1 in track.com.

2.3. Image File Header

Before you run Copytomocoms, you may need to decide how tilt angles will be entered to Beadtrack, Tiltalign, and Tiltxcorr. There are 3 ways to enter tilt angles: by giving a starting and increment angle, by entering the list of all tilt angles into each command file, or by placing the tilt angles in a separate file, one per line. Data acquired on the HVEM with SerialEM have tilt angles in the file header, which Copytomocoms will offer to extract into a separate file for you. Otherwise, if a tilt series does not deviate from regular increments, the first way is fine; otherwise you will have to decide between the other two ways. For extensive tilt series, it's easier to use a separate file; you can probably find a nearly correct file in $IMOD_DIR/com. A file with raw tilt values should be named "setname.rawtlt".

You will also need to make an entry for initial rotation angle. This is the angle from vertical to the tilt axis in the raw images (e.g., if the axis runs from top left to bottom right, the angle would be 45 degrees). If the tilt axis is already vertical, enter a 0. If the tilt axis is horizontal, enter 90 to have the aligned images be rotated clockwise from their current orientation, or -90 to have them rotated counterclockwise. This will determine the orientation of the resulting tomogram.

You will also need to enter information about the size of gold fiducials. You can enter the pixel size and size of gold particles in nanometers, or just the size of the particles in pixels.

For a single tilt series from film, you will get copies of 7 command files:

• track.com runs Beadtrack to generate a fiducial model
• newst.com runs Newstack to make a floated or aligned stack
• align.com runs Tiltalign to get the alignment
• tilt.com runs Tilt to generate a tomogram or slices thereof
• sample.com runs Newstack and the Tilt command file on three regions
• findsec.com runs Findsection to help find the section
• tomopitch.com runs Tomopitch to find the pitch of the section from models

If you have montaged files, you will get a blend.com instead of newst.com. This runs Blendmont, as will the sample.com. If the overlap between pieces was not very accurate when you digitized, you can choose to get a preblend.com to make an initial correction of these misalignments.

For a tilt series from a CCD camera, you will get two or three more files:

Finally, if you have montaged with SerialEM, you will get preblend.com instead of prenewst.com and blend.com instead of newst.com.

If you have a two-axis tilt series, you will get one copy for each series, with names ...a.com and ...b.com. For convenience, most command files will be referred to below by a name without an "a" or "b" (e.g., track.com), but in practice you will always be running an "a" or "b" version when you have a dual tilt series.

The man pages for the programs run by these command files give full details on their operation and on the meaning of the entries to each. Consult them for any questions on the options available in these programs.

Copytomocoms fetches the command files from $IMOD_DIR/com. If something goes wrong, you can copy files from there manually.

3.2. Using Temporary or Insecure Storage

1) If necessary, convert files from Digital Micrograph to a single MRC stack with Dm2mrc.

2) If there are extreme low or high values in your data file which ruin the contrast when you read the images into 3dmod, you should wipe them out with Ccderaser, which is run by eraser.com. See the man page for Ccderaser for details on how to specify the pixels to erase in a model file, which should be named "setname.erase". If the image stack is your only copy of the data, you might want to have Ccderaser make a new output file, and examine that file before replacing the original stack with the erased file. To do so, add a filename for such an output file in eraser.com.

3) Get a prealignment using cross-correlations. There is one option to decide on in xcorr.com. If your images are noisy and the camera did not do a good gain-normalization, then cross-correlation may find a spurious peak near zero instead of the real alignment. If this happens with your data, change the entry on the line "to exclude central peak due to fixed pattern noise" to 1. However, select this option only if you must, because with this option, the program will give an incorrect alignment for pairs of images that are already within a few pixels of being perfectly aligned.

4) Check the alignment by running prenewst.com and looking at the prealigned stack (setname.preali), or by running Midas and quickly looking at each pair of images in turn.

5) If there are serious alignment errors, which show up as a sudden jump in features positions when movieing through the prealigned stack, run Midas with the command:
midas setname.st setname.prexf
Go to each section pair that is not well lined up and shift the current section with the left mouse button to fix the alignment. You may need to fix only one section pair to bring your whole stack into alignment.

6) After fixing bad transforms with Midas, run prenewst.com.

3.4. Preliminary Steps with Montaged CCD Images

With montaged images, you should always check xcorr.log to see how well Blendmont was able to shift pieces into proper registration. For each section in the file, you will see a line giving the "mean, max error before ... after ...". These errors are the amounts of image displacement that Blendmont thinks are present in the overlap zones between adjacent pieces of the montage. The error before shifting the pieces around will generally be large. The error after pieces have been shifted into optimal registration should be small, less than 0.5 pixels. If it is large, then Blendmont was probably not able to measure one or more image displacements accurately enough. If this happens, you can adjust the measured image displacements by hand with Midas. You should definitely do this for a section whose maximum error exceeds 1, and consider it for sections with maximum errors greater than 0.5.

To fix displacements in Midas, enter:
midas -p setname.pl setname.st setname.ecd
Select the Interpolate toggle button to visualize sub-pixel shifts properly. Enter the section number of a section with a large error in the Current Section text box. The control panel has push-buttons for the four edges with the worst errors; use these to select the edge with the worst error. Toggle between the two pieces to visualize the registration in the overlap zone. If it looks bad, shift the Current piece into alignment (the Apply Leave-out Error button can be a useful shortcut if this is the only piece with an error -- see the Midas man page for explanation.) If the overlap looks fine, simply go on to another edge; you will probably find the error there. This potentially confusing situation may be quite frequent, because whenever a bad edge involves a corner piece of the montage, its error is spread equally between the two edges of that piece. It will thus look like there are two equally bad edges when only one is bad.

After you correct the displacement at an edge, the push-buttons will rearrange and show new maximum errors. Once the maximum error is down to 0.3, you can go on to another section. When you are done, save the edge correlation displacement file and exit. Your corrected displacements will automatically be used when Blendmont is run again. However, you should have Blendmont build new edge functions on its next run, because the edge functions depend partly on the displacements that you just modified. To do this, modify preblend.com by changing the 1 to a 0 on the line "0 build new/1 read old edge function files."

It is important to correct these displacements before building the prealigned stack and modeling fiducials on it. When displacements are changed, image positions in the blended image change as well. If you have already modeled fiducials before correcting displacements, you should check the positions of all model points on the sections that were fixed.

If you have a montage consisting of a single row or a single column, the reported errors are all zero, even if there are incorrect displacements. If you suspect that there is a problem with some overlaps (for example, at high tilt in a horizontal montage), your only recourse is to examine each edge in turn in Midas.

4. TRACKING FIDUCIALS

4.1. Getting a Fiducial Model

Beadtrack proceeds from one view to the next, tracking as many beads as possible on the new view. Once it has bead positions on enough views, it runs a simplified tilt alignment to get improved predictions of where beads should be and to reject erroneous positions. Thus, there are several entries to Beadtrack that are the same as ones needed for Tiltalign.

Most standard entries to Beadtrack should work well. The radius for determining the center of gravity of gold particles is set to the actual radius plus 1.5 pixels, based on the entries that you made to Copytomocoms. Make the following changes to track.com:

1. Enter a list of views to be skipped over. Skip over a view if there is a big mag change for that view only, or a particularly poor image for that view. Typically you would leave this entry blank on a first run and enter a Z value here for a second run if the program fails to track accurately through that view.
2. Specify the views that should be kept out of groupings with adjacent views ("reshoots" or other views that don't match the surrounding ones for some reason). Put the number of series of reshoots (typically 1) on the line "# of sets of reshoots", then put the list of VIEW NUMBERS for each series on a separate line.
3. If you have a sudden lurch in tilt angles or in magnification, you may need to change the grouping of tilt or mag variables to avoid having these variables grouped across the discontinuity.
4. If you have finer than 1.5 degree tilts, you may need to increase the minimum number of views for doing tilt alignment.
5. If you have partially tracked a bead in the seed model and left a gap because of ambiguity, you should set the entry for "fill in gaps" to 0.

Run the command file, track.com. You can examine the log file to see how well the tilt alignment did, but the program will end with a summary of which beads could not be tracked completely. To see this, use
tail -40 track.log
If several beads fail to track past a particular view, you might want to add that view to the list of views to be skipped and rerun the tracking.

At this point, read the new model into 3dmod and activate the Bead Fixer plugin under the "Special" menu. This will allow you to jump from one gap in the data to the next and fill in missing points if appropriate. It is acceptable for some of the points to be missing on some of the views. If too few of the points can be extended all the way to the first or last views, you can add some fiducials that are present only in higher tilt views. Just be sure to add them on a substantial number of views, not just on a few, so that their 3-D positions can be solved for accurately. If you do need to add several fiducials, you could put some "seeds" into your edited fiducial model and allow Beadtrack to track those beads as far as possible.

4.2. Getting Fiducials for a Second Axis

If Transferfid fails to work on the first attempt, you may need to set the translational and rotational alignment between the two series manually with Midas. Do this with the command:
transferfid -m setname
If the operation still fails, you can run 3dmod on both stacks at once and add some initial points to the second seed model in the same order that they occur in the first seed model. It is helpful to open one of the images in the Slicer window and rotate it by 90 degrees with the Z slider. You only need to make the first 5 beads correspond, or however many are needed to sample beads on both surfaces, if beads are on two surfaces. After that, you can add the rest in any order. If you do this, then when you prepare to combine the two tomograms, you would specify that only the first 5 beads correspond.

5. GETTING THE FINAL ALIGNMENT

5.1. Running Tiltalign

You should first run Tiltalign with all tilt angles variable and no distortion; this will reveal bad fiducials, check for switched views and reveal some sudden changes in alignment that may need to be taken into account when grouping views together. After fixing fiducials, include distortion and group the tilt angles as appropriate.

For your first run, modify the align.com file as follows:

1. Put in the lists of reshoots or views to be treated separately, if any. Put the number of series of reshoots (typically 1) on the line "# of separate sets for automapping", then put the list of VIEW NUMBERS for each series on a separate line.
2. Set "the # of the reference view..." to the number of the view that was shot first on the microscope. Be sure not to have a reshoot as the reference view.
3. Change the entry for surface analysis to 1 or 2 if there are beads on one or two surfaces.

Run align.com and examine the results in the log file. The program Alignlog can be used to extract particular sections of the lengthy log file. For example, to see the solved parameters for each view, you can enter "alignlog -s" for a single axis data set or "alignlog -s a" or "alignlog -s b" for a dual-axis set. You may want to look at some of the fiducials with the largest errors, particularly ones with errors greater than 2 pixels ("alignlog -r"). Adjust point positions in the model, if appropriate. The Bead Fixer plugin allows you to look easily at the points with the greatest error.

Every time you run Tiltalign, it will analyze the bead positions and recommend a change in tilt angles that would make the beads lie in a horizontal plane. This information is in a section starting with "SURFACE ANALYSIS" that you can extract with "alignlog -a". Make the recommended change at least after the first run of Tiltalign by taking the final value shown for "Total tilt angle change" and using it for the value of "amount to add to all angles" in align.com. It is not necessary to do this repeatedly because the final tilt angle change will be determined in a later processing step.

In the section of Tiltalign's output where it reports parameters for each view (use "alignlog -s" to see), the last column ("mean resid") shows the mean error (residual) in pixels for all of the points on each particular view. This information will reveal whether some views give a poorer fit than others.

5.2. Background on Grouping Variables and Solving for Distortion

Before you get into trying to solve for distortion and grouping variables, you should be aware of several points. First, the grouping of variables can be done in two different ways. In one way, the particular parameter will change linearly from the first view in one group to the first view in the next group, and will appear to change smoothly over the whole tilt series. This is referred to as linear grouping or linear mapping. In the other way, all of the views that are grouped will have exactly the same value for the particular parameter (except tilt angle, where the grouped views will differ from each other by fixed amounts). This is referred to as mapping in blocks. For every variable except stretch along the X-axis, linear mapping is now the "default", selected by the option number that you will find in the command file, because it gives a slightly better fit to typical data. In each case, mapping in blocks can be selected by increasing the option number by one (typically, from 3 to 4).

The second point concerns the nature of the distortion solution, a strange beast. Even if the only thing happening to the section is a stretch along the X-axis, solving for distortion will successfully account for these changes, but the resulting solution will not numerically reproduce the amount of stretch. The problem is that there is an infinity of equivalent solutions, which all account for the distortion equally well, but differ in the geometry of the resulting reconstruction. This geometric difference is a "strain", a shifting in Z proportional to the X value of a column of pixels. Without additional information about the section, there is no way to recover its true structure, and the actual amount of stretching that occurred. The program needs to pick one solution out of the equivalent ones, and it does so by eliminating one variable; thus you will notice a variable listed as "dummy" in the Tiltalign log file. Typically, this arbitrarily selected solution will change the most at high tilt angles, sometimes dramatically so, even though the actual changes in the section happen at a nearly constant rate through the series.

The distortion solution will also account for thinning when tilt angle is allowed to vary as well. The equations governing this situation dictate that the X-axis stretch change rapidly at the highest tilts, even if thinning occurs at a regular rate through the series. Thus, regardless of whether there is section distortion or thinning, or both, it is almost inevitable that the X-axis stretch will change most rapidly at high tilt.

The third point to be aware of is that group sizes will vary with tilt angle when using linear mapping. Group size for tilt angle will be proportional to the cosine of the angle, and will be set so that the average size equals the value that you specify for grouping. Because of the peculiar behavior of the X-axis stretch, its group size will change even more with tilt angle.

Finally, be aware that including distortion can lead the program into inappropriate solutions, in which the tilt angle and the X-axis stretch covary excessively. This can occur when there are too few fiducials, too great an imbalance between the number of fiducials on the two surfaces, substantial random errors in the locations of the model points, or a ratio of measurements to unknowns that is too low. The potential remedies are to increase group sizes, switch from linear grouping to grouping in blocks, solve only for skew angle, or give up on solving for distortion.

5.3. Solving for Distortion - Fiducials on Both Surfaces

1. Change the entry for "0 fixed, 1/2/3 all vary..." to 5 for automapping of tilt angle variables.
2. Uncomment the following line to specify the tilt angle grouping; for example, "10,0" will combine tilt angles for sets of 10 views at a time.
3. Change the entry for "distortion" to 2, to allow stretch and skew to be mapped differently.
4. Uncomment the lines for the stretch variable: 3 for automapping, then a default group size and 0 on the following line (use a group size of 5 to 10).
5. Uncomment the lines for the skew variable: 3 for automapping, then a default group size and 0 on the following line (use a group size of 7 to 15).

You would want to pick the low end of these ranges of group sizes if an alignment run reveals that one of the distortion variables changes especially quickly (but don't be fooled by big changes for reshoots). Conversely, if the ratio of measurements to unknowns is lower than 10-12, you would want to make the default group sizes large. Start with the values that come in the command file.

The stretch variable ("dmag") will typically range from 0.001 to 0.02 but can easily reach 0.05 at high tilts. If you get values larger than 0.05, or if you get changes in tilt angle ("deltilt") more than 2 degrees, you should increase the group size and see if the range of values decreases, particularly if you have only 3-5 fiducials on the surface with fewer fiducials. If the range decreases substantially, stick with the larger group size. You can also increase the grouping for skew and tilt angles to try to get a better-behaved solution. If a solution seems unreasonable, either abandon the attempt to solve for distortion, or solve for skew angle only, as described in a few paragraphs.

The skew is an angle in degrees and will typically range from 0 to 1 degrees. Values greater than about 0.2 degrees are worth correcting for, and a change of more than about 0.3 degrees from one group to the next would be a big change.

If you have discovered that there is some sudden change in alignment such that two views should not be grouped together, then you need to specify some "separate ranges" for each of these entries. Suppose there is a big change between views 20 and 21. Then, for automapping the tilt angles, you would use "10,1" to specify default grouping of 10 and 1 separate range, then you would add a line with "1,20,10", so that views from 1 to 20 would be grouped separately with a group size of 10. Make similar entries for the distortion variables.

A good alignment has a mean residual error of 0.25 to 0.5 pixels, or more for larger gold particles.

5.4. Solving for Distortion - Fiducials on Only One Surface

1. If skew is not significant (say, less than 0.25 degrees), then don't solve for distortion, and set the group size for tilt angles at 5-10.
2. If skew is significant, there are two options. One is to fix all tilt angles and continue to solve for distortion, perhaps reducing the group size accordingly. The other is to solve for tilt angles, and for skew angles, but not for stretch. This is done by setting the option for X-axis stretch to 4 instead of 3, and the group size for stretch to -200 (a number larger than the number of views, and negative so that reshoots will be fixed as well). You can then group tilt angle and skew by 5-10.

5.5. Using Local Alignments

1. Find a global solution using all of the fiducials, as described above. Because you have many fiducials, you can make the grouping of variables for tilt angles and distortion smaller than usual. Reduce group sizes accordingly but keep the ratio of measurements to unknowns fairly high (~15).
2. If you did not indicate that you might need to do local alignments when you ran Copytomocoms, then you need to add entries to your align.com. First add a line at the end specifying the file in which to place the local alignments, typically setnamelocal.xf. Then append the contents of the file $IMOD_DIR/com/localpart.com.
3. Change the entry from 0 to 1 on the line "0 to exit, or 1 to do local alignments".
4. Adjust the entries for number of local areas and area sizes so that there will be an overlap of about 40-50% between local areas. For data from film, a size of 500 pixels is appropriate, but a size of 750-800 pixels is probably better for unbinned data from the CCD camera. To have an overlap of 40%, allow 300 pixels per area for film, or 450 pixels for CCD data, and divide the total size in one dimension by 300 or 450 to obtain the desired number of areas in that dimension. For example, with 500-pixel areas, a 1500 by 2000 pixel data set should have 5 by 7 local areas.

Run align.com and examine the results. You can assess the results easily with:
grep Residual align.com
The typical result has been that a global mean residual of 0.75-1 is reduced to about 0.5 in the local alignments.

5.6. Excluding Views

5.7. Residual and 3D Model Outputs

Tiltalign also produces a text file with the residuals for each point, and Patch2imod converts this into a model of the residual vectors in a file named setname.resmod. You can load this model into 3dmod on top of the images, in place of the fiducial model, to look for patterns in the direction of the vectors. The vectors are exaggerated in length by a factor of 10. The start and end of a vector is marked by a green and a red cross, respectively.

6. POSITIONING AND GENERATING THE TOMOGRAM

6.1. Getting a Trial Aligned Stack and Tomogram

After you obtain and examine an aligned stack, modify the tilt.com file as follows:

1. Set the thickness to at least twice the expected thickness of the section in the tomogram.
2. Set the cutoff value and sigma value for the filter on the "RADIAL" line as appropriate for the resolution of your tomogram. These should be entered in reciprocal pixels (values from 0 to 0.5) so that the filter setting will not depend on the size of the image.
3. The entry on the LOG line should be 5000 times the approximate fog OD level for film, but must be 0 for images from CCD camera.
4. For extra speed, or if your aligned stack is bigger than 10 in Y, add a line "slice 1 5 1" to do just 5 slices.
5. If you excluded any views in align.com, add a line
   excludelist list_of_views
where list_of_views should be the same list of views excluded in align.com (be sure not to have any spaces in the list).

Examine the tomogram piece in cross-section with 3dmod. You will see that you need to shift the section up or down. If you can't see both surfaces of the section, either rerun Tilt with a bigger thickness, or make a large entry to "move the tilt axis in Z" in the align.com file (positive moves the section up in the tomogram). Then rerun Tiltalign, Newstack or Blendmont, and Tilt. Once you can see both surfaces of the section, estimate how much you would have to move the section to center it in the image. Set or change the "amount to move tilt axis in Z" in align.com. If the section looks appreciably tilted, you should also estimate the rotation needed to make it flat. A positive slope means that all tilt angles should be changed by a positive amount. Make this change in align.com and rerun this file.

6.2. Sampling 3 Areas of Tomogram and Positioning the Section Optimally

Check your tilt.com file before proceeding. Eliminate the "slice 1 5 1" statement if any. Make the thickness be about 40 pixels bigger than the estimated thickness of the section.

Now run the sample.com file. When it is finished, you will have 3 sample tomograms, bot.rec, mid.rec, and top.rec (or bota.rec, etc., for a dual-axis data set). You have two choices, automatically finding the section with Findsection, or modeling the edges of the section and computing angles with Tomopitch. Findsection is harder to use because it can give spurious results that need some judgement to filter out, so you may prefer to skip it completely and just use Tomopitch.

To use Tomopitch, first load all 3 sample tomograms into 3dmod with a command such as:
3dmod top.rec mid.rec bot.rec tomopitch.mod
(use tomopitcha.mod and topa.rec, etc., for the first axis of a dual-axis data set.) Model each edge of the section by drawing a line along the boundary in one of the slices for a tomogram sample. Just use two points, one on the left and one on the right side of the tomogram. Put the lines for the top and bottom edges in separate contours. Use the "1" and "2" keys to switch between samples, and model two contours in each sample in the same way. When you are done, the model should have one object with six contours (two per sample), and two points per contour. Save the model.

Next run tomopitch.com and examine the result. For each sample, there is an estimate of shift, rotation, and thickness, but your main interest is in the estimates based on all three samples. These appear at the end of the log file as four recommendations: the amount of tilt around the X axis, the amount to rotate the tilt angles, the amount to shift the tilt axis in Z, and the required thickness for the full tomogram. If the X-axis tilt is small (less than 0.4 degrees) and your tomogram is going to be small, don't bother with it, and use the recommendations before this tilt is taken into account. Otherwise, use the final recommendations. Note that there is one entry in tomopitch.com specifying the number of pixels to add to the tomogram beyond the surfaces defined by your lines. You may want to change this value in some special cases.

To use Findsection, run findsec.com and examine the result. There should be a thickness and location estimate for 5, 7 or 9 patches across each of the three sample tomograms. If a few patches have widely divergent thickness estimates, edit the findsec.com file to eliminate those patches from the final calculations and rerun the program. (If there are more than a few such patches, look at the 3 tomograms to see if there is some other problem.) The end of the log file has the same four recommendations just described for Tomopitch. (Use the results from the "edge-thicknesses" unless you are pressed for space or know better). If you have trouble with Findsection, drop back to using Tomopitch.

6.3. Doing Samples with X-axis Tilt or Local Alignments

With X-axis tilting, the first and last few slices in each sample may have incomplete data. You may need to increase the number of slices to get usable samples. To do so, edit sample.com and, for non-montaged data, increase the "-size" argument for all three "newst" commands. For montaged data, increase the "max Y coordinate" entered into each of the three runs of Blendmont.

6.4. The Final Runs

Modify your newst.com or blend.com to make a full-sized aligned stack by putting a ,, or the full image size for the "size" entry in newst.com or a / on the "Min and max X..." line in blend.com. Run this file to get the aligned stack. Check the aligned stack or a 100-pixel swatch of it.

Modify your tilt.com file to incorporate the recommended thickness, and the X-axis tilt, if you opt to use that. If you did local alignments, also add a line to the file with the name of your local alignment file, i.e., add
localfile setnamelocal.xf
Run tilt.com.

7. COMBINING TWO TOMOGRAMS

• Solvematch: Use the coordinates of the fiducials from tilt alignment to determine the 3-D rotation and distortion between the two tomograms.
• Matchshifts: Project a zero-degree view of each tomogram, rotate one, and use 2-D cross-correlation to find shifts in X and Y. Then extract a small volume from each tomogram (one of which is rotated) and use 3-D cross-correlation to find shifts in X, Y and Z. Extract an adjacent small volume to check whether it gives a similar correlation. These operations and the preceding one are run by solvematchshifts.com.
• Matchvol: Using this initial alignment, generate an initial matching volume from one of the tomograms. This operation is run by matchvol1.com
• Patchcrawl3d: Extract small patches from a regular 3-D array of positions in the two volumes (one original, one transformed to match), and use 3-D cross-correlation to determine the error (displacement) between the two volumes at each position. This operation is run by patchcorr.com.
• Matchorwarp: Analyze the displacements with Refinematch, and if they fit well enough to a single linear transformation, use Matchvol with this refining transformation to produce the final matching volume. If they do not, run Findwarp to find the best warping between the volumes automatically, then run Warpvol to produce a final matching volume with a series of linear transformations. Warping is done by solving for a series of local 3-D transformations and making a gradual transition from one to another in the plane of the section. All of these operations are run by matchorwarp.com.
• Match the density between the two volumes (Densmatch), then take Fourier transforms of each (Clip), combine the Fourier transforms (Combinefft), and back-transform. Larger volumes are broken into pieces (Taperoutvol) and recombined (Assemblevol), because it is much faster to take Fourier transforms of these pieces. All of these operations are run by volcombine.com.

7.1. Setting Up

1. Decide which tomogram will be transformed to match the other. Typically, the "b" set is matched to the "a" set. However, if the section is appreciably flatter in one tomogram, then the other one should be matched to that one.
2. Examine the tomogram being matched TO and determine the first and last slices that contain useful information for cross-correlating the tomograms (i.e., are inside the section over most of the area). Ignore the gold particles; there is too much empty space around them.
3. Try to determine if there are regions within the section that should not be used for correlating the tomograms because they are either empty of material or contain reconstruction of poor quality. You can exclude such areas from consideration in two ways. One way is to set more restrictive lower and upper limits in X and Y on the region from which patches will be extracted by Patchcrawl3d. Take note of the coordinates in X and Y beyond which the image is unreliable, and enter these coordinates to Setupcombine. The other way is to draw one or more model contours completely enclosing the patches that you want included in the analysis. See the man page for Refinematch for details. Do not worry about identifying regions in this tomogram that are outside the bounds of the other tomogram; Patchcrawl3d will take care of this limitation.
4. If you have fiducials on only one surface, note whether one tomogram is upside down relative to the other.
5. If your fiducial points are not in 1:1 correspondence between the two tomograms, be prepared to specify the correspondences that you are confident of. Solvematch can be given a small list of fiducials that are known to correspond and it will find the remaining correspondences. There are two restrictions on this ability: you must give it at least 4 correspondences to start with (5 is recommended); and if you have fiducials on both surfaces, you must include at least one from each surface. To specify correspondences to Setupcombine, you enter two lists of numbers. For example, if you are matching "b" to "a", first enter the list of points from "a" which have corresponding points in "b", then enter the list of corresponding points in "b". If you used Transferfid, enter the lists that it provided.
6. Decide what size patches to use in Patchcrawl3D. Ideally, this decision would be based on how much high frequency information is in the tomograms and on how well the two volumes seem to agree with each other, but these features are difficult to assess. Setupcombine provides three built-in sizes, small, medium, and large. Small patches should be adequate for relatively high-resolution tomograms from film, while the medium patches are more appropriate for data from a CCD camera. If the tomograms seem particularly fuzzy, go up one size in either case.

If you have a relatively thin sample, you should be aware that Setupcombine may decide to compute only one layer of patches, in which case the second stage of alignment will not stretch the data in the thickness dimension. This is generally appropriate, but you may wish to change this by editing patchcorr.com to specify two layers of patches. Adjust the size of the patches in the thickness dimension if necessary so that it is at least 30% smaller than the range allowed for the patches in that dimension. This dimension is referred to as Y in patchcorr.com.

7.2. Using Temporary Storage for Combining

7.3. Proceeding

Make sure that the "....tlt" and "...fid.xyz" files produced by Tiltalign are still present.

Check free disk space (df -k). Typically, you need 3 times as much free space as one tomogram occupies; Setupcombine provides a more accurate estimate. You may need to delete the aligned tilt series (and archive and delete raw tilt series) before proceeding.

Run combine.com. You can monitor the status of the combine operation by checking the combine.log file, or the log files for the individual steps. Once it starts running volcombine.com, you can check the progress easily by entering
grep STATUS volcombine.log


When the combining is done (or sooner, if the tomogram is large), check the matchorwarp.log file to see how good the registration between the two volumes is. After Patchcrawl3d runs, you will see Refinematch's report on the mean and maximum deviation at the various locations after applying a single linear transformation. Then there will be either a message that Matchvol is being run, or a message that warping is needed. In the latter case, Findwarp may run several times; just above a message that Warpvol is being run next will be a report on the mean and maximum of the mean residuals. If the mean is reasonable but the maximum is quite high (1 or more), you should look at the patch vector model (patch_vector.mod) and consider whether to take any of the remedial actions described below.

7.4. Initial Registration Problems in Combining

It is possible that Matchshifts will fail to find the proper shift between the two tomograms, if the displacement between them is particularly large. To check for this possibility, Matchshifts produces two small volumes just adjacent to the ones it used to determine 3D displacements, and uses cross-correlation to find the shift between them. If this shift is too high, the combine processing stops. You should then look at the two volumes with
3dmod -Y matchcheck.rec matchcheck.mat
to see whether the volumes differ in position by just a few pixels or are very different. If the position is close, edit combine.com to comment out the two lines referring to solvematchshift.com (the "echo" and "vmstocsh" lines) and rerun combine.com.

If the check volumes do not match up, then Matchshifts failed, and you have to make models of corresponding points by loading both tomograms into 3dmod with -Y. Make two models, "setnamea.matmod" and "setnameb.matmod", containing 3-5 corresponding points, as described in the man page for Solvematch. If you are marking gold particles, put the model point on the section with the strongest white side bands around the black bead. Edit combine.com to comment out the two lines referring to solvematchshift.com (the "echo" and "vmstocsh" lines), and uncomment the two corresponding lines referring to solvematchmod.com. Rerun combine.com.

7.5. Patch Correlation Problems in Combining

1) If there are many lines that do not fit the pattern of surrounding lines, scattered around the whole volume, then you should rerun Patchcrawl3d with larger patches. Modify the first three entries on the Patchcrawl3d command line in combine.com. A 25% increase in each dimension is recommended, as this will double the volume of the patches and substantially improve accuracy. Uncomment the "goto patchcorr" entry at the top of combine.com and rerun the command file.

2) If displacements generally look fairly regular but there are a large number of bad patches in well-defined regions, it may be easiest to make a model with contours enclosing the regions with good patches, or to modify such a model if you have already made one. To do this while looking at the patch vector model, you would have to load the tomogram being matched to into a separate 3dmod and make or edit the boundary contour model there, while trying to correlate positions between the tomogram and the patch vector model. If you do make a new model of boundary contours, add the entries "-modelfile" and the model filename right after the "matchorwarp" line in matchorwarp.com. With either a new or a modified model, uncomment and change the "goto" entry to be "goto matchorwarp" at the top of combine.com and rerun combine.com.

3) If bad patches are fairly scattered and not too numerous, it is most appropriate to edit them out. To do this, position the mouse on an aberrant vector in the model view window and press the third mouse button to select this contour in the Zap window. If you have any doubt about which contour you selected, use the [ and ] hotkeys in the Zap window to examine the starting and ending points of the contour. The starting point will be at a regular position in the array, while the ending point should be displaced by an unusual amount. Delete the contour with the "D" hotkey in the Zap window; it will disappear from the model view window also. When finished, save the model and exit. Then run Imod2patch:
imod2patch patch_vector.mod patch.out
You may want to rename the existing patch.out before doing this. Uncomment and change the "goto" entry to be "goto matchorwarp" at the top of combine.com and rerun combine.com.

4) If the patch vector model indicates that bad patches are numerous near edges of the volume, next explore whether omitting a whole column or row of patches will give an acceptable fit to the remaining patches. To do this, run Matchorwarp in trial mode by editing matchorwarp.com and inserting the argument "-trial" on the "matchorwarp" command line. Also insert one or more arguments such as "-xlower 1," or "-zupper 2" to exclude one column of patches on the left or two rows of patches on the top. Be sure to place any added arguments before the continuation mark, "\". Run this command file with
subm matchorwarp
and examine results in matchorwarp.log. Do this repeatedly to assess different row or column exclusions. If you find an exclusion that gives a good fit, and the excluded area is not a critical area where you would expect a better fit, then proceed with this exclusion. Remove the "-trial" argument from matchorwarp.com, uncomment and change the "goto" entry to be "goto matchorwarp" at the top of combine.com and rerun combine.com.

5) Sometimes the lowest mean residual that Findwarp is able to achieve (the last message in matchorwarp.log saying "Findward failed to find a warping with a mean residual below") is actually an acceptable value, just a bit higher than the highest acceptable mean residual specified in matchorwarp.com. If this is the case, just change the highest value in the "-warplimit" argument in matchorwarp.com to be higher than the value shown in this message. Uncomment and change the "goto" entry to be "goto matchorwarp" at the top of combine.com and rerun combine.com.

6) If all else fails, it may help to run Findwarp interactively. This will allow you to explore omitting columns or rows of patches as well as select the number of patches that will be used in each local fit. See the man page for Findwarp. When running the program, examine results with transformations based on various subsets of patches, but no fewer than 3 by 3 by 2 or 4 by 2 by 2. Try to retain all of the rows and columns if possible. Use the largest subset of patches that will give a mean residual error under about 0.2 pixels. Save the transformations in a file named warp.xf. Uncomment and change the "goto" entry to "goto warpvol" at the top of combine.com, uncomment the "vmstocsh" line that runs warpvol.com, and rerun combine.com.

8. POST-PROCESSING

8.1. Scaling and Trimming a Tomogram

First, load sum.rec into 3dmod with -Y and determine the starting and ending slices of a range that excludes features whose intensity can be saturated. Findcontrast will ignore areas within 10% of the edges of these slices. If you want to trim the volume, note the first and last section that you want to keep, as well as limiting coordinates near the left, right, bottom, and top edges if you want to trim the lateral size of the volume. All of these number can be 3dmod coordinates, numbered from 1. For no trimming, just enter
trimvol -s start,end sum.rec setname.rec
where start and end are the starting and ending slices for finding contrast. In the most general case, enter
trimvol -s start,end -x left,rt -y first,last -z bot,top sum.rec setname.rec
where first and last are the first and last sections, while left, rt, bot, and top are the limiting coordinates on the left, right, bottom, and top of a section in the flipped tomogram.

If the automatic contrast limits are unsatisfactory, you can determine contrast settings in 3dmod by moving both contrast (Black and White) sliders to the same position. While movieing through the data, adjust the positions of both sliders together until only the gold beads (and other irrelevant features) show up as black pixels; this slider value is the lower contrast limit. Then adjust both sliders so that only the overshoots around the beads show up as white pixels; this slider value is the upper contrast limit. Enter
trimvol -c black,white sum.rec setname.rec


Finally, you can also use the "-yz" flag to Trimvol to flip the tomogram, so that you no longer have to load it into 3dmod with -Y.

If your images were acquired on a CCD camera with limited spatial resolution, you may be able to reduce the size of the final volume considerably with no perceptible loss of image detail. The shell script Squeezevol provides an easy interface for scaling a volume down by interpolation using Matchvol. Since resolution is worse in the direction perpendicular to the plane of the section (the Y direction in an unflipped tomogram), it could be appropriate to squeeze the volume more in that dimension. For example, if the CCD camera provides no useful information above 0.8 of Nyquist, an overall reduction by 1.25 would be appropriate, and a reduction 1.3 times higher in the Y dimension would also be appropriate given the extra point-spread in that dimension in a tomographic reconstruction. The size of the volume can be reduced by a factor of 2.5 with:
squeezevol -f 1.25 -y 1.62 setname.rec setname.sqz
Note that if you have already flipped the volume, you would use "-z" instead of "-y". If you choose anistropic squeezing, you need to increase the Z-scale that you use for viewing models built on that volume by the amount of extra squeezing in that dimension. For example, if you usually have a Z-scale of 1.6, you would need a Z-scale of 2.07 after the squeezing operation shown above.

8.2. Cleaning Up

Once you are satisfied that your final tomogram is truly final, you can remove the following big files:

  sum*.rec
  setnamea.rec
  setnameb.rec
  setname*.mat

Finally, archive and delete the raw image stacks. The shell script Splitmrc can be used to divide a very large MRC file into pieces that will fit on multiple CDs; Recombine can be used later to put the pieces back together.