Frame Alignment Parameters Dialog

This dialog allows you to set parameters to control alignment of frames taken from a K2 camera in Dose Fractionation mode, or from a Falcon camera. 

With a K2 camera, the alignment can be done in three different ways: with the native alignment procedures in DigitalMicrograph, with the 'framealign' module in SerialEM's plugin to DM, or independently of SerialEM with the Alignframes program in IMOD, which incorporates the same 'framealign' module and thus uses the same parameters.  In the latter case, all that the plugin to DM does is write a command file for running the alignment in IMOD after all of the frames have been saved.  The Framewatcher program in IMOD can be used to process these command files as soon as they appear.

With a Falcon camera, the alignment can generally be done in two or three similar ways: with the FEI software that aligns frames from Falcon 3 camera, with the 'framealign' module incorporated into SerialEM, or with the Alignframes program in IMOD.  Again, in the latter case all that SerialEM does is write a command file.  The availability of the different forms of alignment and how data are processed depends on the details of the system.  Specifically:

 

Aligning in DigitalMicrograph or FEI Software

For a K2, the alignment in DM has only one parameter, the filter that is used in the alignment procedure.  The combo box should show the same set of filters that are available in DM; if not, the SerialEMproperties file needs to be modified to list the correct filters.

For Falcon 3, alignment with the FEI software has no parameters but does require a certain minimum exposure time per frame.

 

Aligning in the SerialEMCCD Plugin or SerialEM

Alignment with the 'framealign' module has many more parameters.  Virtually all of the ones shown in this dialog correspond exactly to an Alignframes option, so the man page for that program can be consulted for more details about any particular option, as well as for general instructions and advice.  The reason that there are so many parameters is that different settings are needed to obtain optimal results in fundamentally different situations.  Still, it should be possible to set up a small selection of parameter sets that will work for your own data.  SerialEM can store multiple parameter sets, and this dialog allows you to chose among them.  The selection is stored as part of the individual camera parameter set.  If you have no previously defined parameter sets, the program will add two sets suitable for use with counting mode and super-resolution frames.

The dialog gives a choice among several alignment strategies.  Which one is appropriate depends on the kind of data being taken and its noise level.  One basic strategy is to find shifts for individual frames by fitting to measurements of shifts between many pairs of frames (the approach of the 'motioncorr' program from UCSF). This method uses comparable amounts of information for all of the frames.  The implementation here has two important features: 1) the fits can be done to pairwise shifts measured for subsets of frames, thus giving the benefits of the approach without requiring as many measurements; and 2) the fitting is done with 'robust regression', which weights measurements less the more they deviate from the fitted solution used, so that a few bad correlations can be effectively ignored.   The different options in the dialog allow the fits to be done to a fixed number of frames, half the frames, or all the frames.  The other basic strategy involves correlating each frame to a sum of previously aligned frames; this is not as reliable in general because it uses less information for finding the shift of the first few frames, and is more susceptible to fixed pattern noise. 

Both methods can be followed by a refinement step in which each frame is correlated with the aligned sum of all other frames (this is similar to what is done in the unblur program from Grigorieff's group).  This step probably has no benefit if the errors from the initial fit are low.  The Alignframes man page describes how to evaluate whether one particular parameter selection is better than another.

The general advice about which approach to use is:

Some other main points about the parameters:

The plugin will do cross-correlations for each frame as soon as it available, and will do the final shift of a frame and its addition into the aligned sum as soon as allowed by the parameters. If the time taken for alignment is a consideration, then you should be aware of which options make it unable to do any final shifts until all frames are received: doing pairwise fits among ALL the frames; refining the initial alignment; doing spline smoothing of the estimated shifts; and testing more than one filter cutoff without selecting to use 'hybrid shifts', which are available before the end.  However, you will probably find that using these options costs less than 0.1 second per frame.

Frames can be acquired dark-subtracted or unprocessed instead of gain-normalized if they are also going to be saved as compressed TIFF files.  The data will be normalized by the framealign module before being aligned, and the aligned sum will thus be gain-normalized.

When an alignment is done, results may be printed to the log.  In their full form, they look like this:

Frame alignment results:          distance raw = 2.7 smoothed = 1.3
Weighted resid mean = 0.16  max max = 0.32  Mean unweighted max = 0.57
FRC crossings 0.5: 0.0335  0.25: 0.0468  0.125: 0.0898  is 0.1025 at 0.25/pix    
If there are not enough frames for robust fitting, the output will be somewhat simpler and reflect only actual residual errors, since no weighting is being done.  The number of lines of output can be set by the Set Frame Align Lines command in the Camera menu.  The default is to omit the FRC values since these are the most difficult to interpret and depend on the sample and dose.

Aligning in IMOD

The same parameter settings are presented when writing command files for aligning with Alignframes as for aligning in the plugin.  The principal difference is that one needs to select a folder where the command files will be written, and that one can align and stack an entire tilt series after completion.  The files will actually have extension '.pcm' instead of '.com'.

Time should not be an issue when doing alignments with this option, since the alignments are generally fast enough to be done well before the next set of frames needs aligning.  Thus you can use refinement, smoothing, or multiple filters routinely without worrying about whether they are actually helping.

K2 frames can be taken unnormalized in order to save efficiently in compressed TIFF files.  The command file will contain options to apply gain-normalization, plus defect correction for GMS 2.31 and higher.

Global Settings

The upper part of the dialog, down to the box for Parameter set name, allows one to set a few 'global' settings that apply to all alignments.  The list box on the right shows the available parameter sets, which can be selected by clicking on one.

Use the GPU

Select whether to use the GPU on an NVIDIA card for the frame alignment.  This setting is kept track of separately for aligning immediately versus aligning in IMOD, because the latter could be done by any computer with access to the frame data.  In fact, if there are two K2's, or a K2 and a Falcon, it is kept track of separately for each camera.  This option should be enabled if NVIDIA drivers are installed, and the files FrameGPU.dll, cudart64_41_28.dll and cufft64_41_28.dll are in the correct location: specifically, for a K2 camera, in C:\ProgramData\Gatan\Plugins along with the SEMCCD-GM2-64.dll plugin; and for a Falcon camera, in the same folder as the SerialEM executable.

Align only whole tilt series

This option is relevant when aligning in IMOD and only for a Record parameter set; when it is checked, a command file is not produced for individual Record images, only at the end of a tilt series.  That command file will align all of the frame files for the tilt series and construct a new stack with appropriate header entries, using a copy of the .mdoc file for the original tilt series stack.

Set Folder for Align Com Files

Press this button to select the folder where the command files will be written when aligning in IMOD.  This folder must be on the same drive as the frame files, because the command file needs to be written with relative paths that would be meaningful if processing on another machine.  If SerialEM is running on a microscope computer, then the folder name must be typed into the dialog box that comes up.  If it is running on the K2 computer, then a folder chooser will come up just as it does for selecting the frame folder.

Use same folder as frames

Select this option to have command files written into the same folder as the frames, thus overriding any entry that was made with the Set Folder button.

New Parameter Set

Press this button to create a new set of parameters that start out as a copy of the currently selected one.

Delete

Press this button to delete the currently selected set of parameters.  This is possible only when there is more than one set, because the program always needs at least one set. If any other camera parameter sets have selected this set, their selection will be changed to the adjacent set; and if any of those have frame alignment enabled, the program will warn you about this change.

Parameter set name

Here you can edit the name of the set that appears in the list box.

Restrictions on When to Use a Parameter Set

This group of check-boxes lets you control whether a parameter set is to be used only in under certain conditions.  Namely, you can specify that a set should be used only when Aligning in plugin or only when Aligning with IMOD, and independently whether it should be only for 4K (non super-resolution) frames or only for 8K (super-resolution) frames.  The restrictions are taken into account at several places in the program, where the currently selected parameters are tested for whether they meet the conditions.  If they do not, the program analyzes whether the conditions are met by no, one, or several other parameter sets, and acts in various ways:

The use of restrictions will work most conveniently if you have only one parameter set for each kind of situation, each one marked with different restrictions.  For a K2, if you have just the "4K default set" and "8K default set", simply restrict each one to the respective size of frames, and the parameter set will switch automatically when you switch between super-resolution and counting mode.

Basic Alignment Parameters

The parameters in the upper section are the ones most likely to need setting.

Truncate values above n electrons (K2 only)

Select this option and set the number of electron counts to have values above that number replaced by the local mean.  This is the number of electrons per acquired pixel, which cannot be higher than 15 for super-resolution frames. If your gain-normalized images have many extreme values, removing them from the frames may make the alignment more reliable, as well as making it easier to see the data in 3dmod.

Alignment strategy

Here one can choose among the options described above.  Here are a few points to note.  If the number of frames in the first option is set higher than the actual number of frames, it will have the same effect as fitting to ALL pairwise shifts.  The second option, to fit to pairwise shifts of HALF the frames, will actually fit to a minimum of 7 frames. If alignment to a cumulative reference is chosen, grouping of frames and testing of multiple filter cutoffs are not available.

Alignment binning

Binning, actually antialiased image reduction, is one of the two most important parameters because it affects processing time as well as the accuracy of the fits.  Binning should be set to bring images to a size of 1000 to 1250 pixels; thus 3 or 4 for ~4K images and 6 or 8 for ~8K images.

Filter cutoff

The filter cutoff is the most important parameter; it is expressed in cycles per pixel in the unbinned frame so that a value has about the same effect with different binnings.  Optimal values are generally in the range of 0.05 to 0.07.

Maximum shift between frames

This entry sets the maximum shift that will be detectable from one frame to the next, in unbinned pixels.  Larger shifts are allowed between more separated frames, but the shifts have to be in a range predicted by the relative shifts of the intervening frames.  This parameter should probably not be in the basic section.  The default in Alignframes is 20.

Group frames by n

Select the checkbox to have successive frames summed together (without alignment) for the initial correlations.  The spin box sets the number of frames to sum.  When frames are very noisy, grouping by 2 or 3 can bring the correlation peak out of the noise.  All possible sums of successive frames are formed, but correlations are done only between sums that do not overlap. This increases the number of frames required to use this approach, which is shown after the spin button.

Refine alignment with up to n iterations

Select the checkbox to add a refinement step after all the initial correlation have been done.  Even multiple iterations of refinement are relatively quick because all of the FFTs that need correlating are already available.  The spinner sets the maximum number of iterations that will be run, but refinements often stop after fewer iterations because the changes have fallen below a threshold.  Five iterations is generally sufficient unless refining with group sums.

Smooth shifts if at least n frames

Select this checkbox to apply spline smoothing to the shifts if there are at least as many frames as selected in the spinner.  This smoothing may have a very small benefit but should only be used if there are enough frames to give a good assessment of the smoothing that is needed.  The default in Alignframes is to smooth shifts when there are at least 15 frames, but this is left as a choice here because smoothing is one of the options that prevents any frames from being summed until all have been aligned.

Align subset of frames

Select this checkbox to align only a subset of the frames being saved, then fill in the starting and ending frames to align, numbered from 1.  The option is irrelevant when no frames are saved, because in that case a drift settling time can be set for K2 to discard initial frames after the exposure starts.  When frames are being aligned in the plugin to DM or in SerialEM, the image shown in SerialEM will be a sum of only the aligned frames.  When frames are aligned with IMOD, the command file will contain the -frames option to Alignframes with the given starting and ending frames.

More Advanced or Less Commonly Needed Parameters

Refine in groups

When frames are exceedingly noisy, correlations between a single frame and an aligned sum may not be reliable enough, so this option is available to do the refinement with groups of aligned frames instead of single frames.  The iterations for refinement should be set to 10 if this option is used.

Filter cutoff for refining

In this box, you can enter an alternative cutoff radius in cycles/pixel to use for the refinement step; otherwise the same cutoff will be used as for the initial alignment.  Large increases will impair the alignment, but an increase of ~25% might be beneficial.

Stop refining when changes are below n unbinned pixels

This entry sets the threshold change in shifts for continuing to iterate the refinement of the initial alignment.  The default in Alignframes is 0.1 unbinned pixel.

Other filter cutoffs

These two text boxes allow additional filter cutoffs to be tested at the same time as the main cutoff.

Use hybrid shifts

When multiple filters are being tested, the default is to accumulate all the alignment results, then pick one filter as best and apply the shifts from it to form the aligned sum.  If this option is checked, then a best filter will be picked after each individual fit to a set of pairwise shifts, and the shift implied by the fit with that filter will be used for the one image whose shift is being set after that fit.

Ratio of falloff sigma to filter cutoffs

The ratio in this text box is used to scale the sigma of the Gaussian falloff of the high-frequency filter proportionally to the cutoff.  Such scaling is done when using the '-vary' option in Alignframes, and the default ratio there (1/7) is based on the ratio of default values for cutoff and falloff.

Always process gain-normalized frames with full precision (K2 only)

This option is available only when aligning in the plugin and only for GMS 2.31 or higher.  It is only relevant there when acquiring a gain-normalized image with an 'early return'.  In all other cases, the plugin passes a gain-normalized image to the framealign module in its original floating point form, before possibly scaling it to integers.  With an early return, the plugin has to fetch frames from DM as fast as possible and store them in a local stack.  By default the stack is in a scaled form (byte for super-resolution, 2-byte integer for counting mode).  With this option checked, counting mode frames will be saved in their floating point form, and super-resolution frames will be multiplied by 4096 and saved as 2-byte integers, so the precision will be fully preserved, but the stack will occupy twice the memory.  Choosing this option may delay the early return unless there is enough memory.  However, this option is overridden by the option to scale saved frames by an additional factor of 100; if there is an early return and frames are being saved with such scaling, the scaled frames will be passed to the framealign module.

Output aligned sums as floating point

This option is available only when aligning in IMOD.  Select the checkbox to have aligned sums output as floating point instead of 2-byte integer, which will preserve a very small amount of precision in the sums.  The regular scaling will still be applied to them in this case.