sxlocal_ali2d - Perform local refinement of 2-D alignment of an image series
Usage in command line:
sxlocal_ali2d.py stack output_directory <maskfile> --ou=outer_radius --br=brackets --center=center_type --eps=epsilon --maxit=max_iter --CTF --snr=SNR --function=user_function_name
Usage in Python programming:
local_ali2d(stack, outdir, maskfile = None, ou = -1, br = 1.75, center = 1, eps = 0.001, maxit = 10, CTF = False, snr = 1.0, user_func_name="ref_ali2d")
- Set the particle radius:
- sxlocal_ali2d.py input_stack.hdf output_directory --ou=27
- The above command can be written in python code as:
- local_ali2d(stack, outdir, ou = 27.)
Warning: should the program stop prematurely reporting a decrease of the criterion, it is recommended to increase the particle radius.
set of 2-D images in a stack file (format hdf), images have to be squares (nx=ny)
- optional mask file to use internally during alignment
The parameters preceded with -- are optional and default values are given in paranthesis.
outer radius for rotational correlation < int(nx/2)-1 (set to int(nx/2)-2, should be set to the radius of the particle)
- brackets for the search of orientation parameters (each parameter will be checked +/- bracket) (set to 1.75)
- 0 - if you do not want the average to be centered, 1 - center the average (default=1)
- stopping criterion, program will terminate when the relative increase of the criterion is less than epsilon (set to 0.001)
- maximum number of iterations the program will perform (set to 10)
if this flag is set, the program will use during the alignment CTF information provided in file headers (for details see I_O). (default no CTF)
- Signal-to-Noise Ratio of the data (default SNR=1.0)
name of the user-supplied function that prepares reference image for each iteration (default ref_ali2d)
- directory name into which the output files will be written. If it does not exist, the directory will be created. If it does exist, the program will crash and an error message will come up. Please change the name of directory and restart the program . The program will write two kind of files: the average of the aligned image series (aqe***.spi) and the Fourier Resolution Criterion curve (dre***). Both files are numbered by the iteration number.
- the alignment parameters are stored in the headers of input files as 'alpha', 'sx', 'sy', 'mirror'
- For the program to work, attributes 'alpha', 'sx', 'sy', and 'mirror' have to be set in the header of each file. If their values are not known, all should be set to zero.
- The program will start alignment from the current alignment parameters 'alpha', 'sx', 'sy', and 'mirror' stored in file headers. To erase previous alignment result, set them all to zero.
This program is meant to refine orientation parameters found by sxali2d and it should be run after sxali2d was run. It will not change the 'mirror' settings, the assumption is that they are already correct.
- The program prints the value of the alignment criterion (see the reference). If the program is started using results of the previous alignment, the initial value of the criterion may be slightly lower than that achieved at the end of the previous alignment - this is due to numerical accuracy and it is not a reason to be concerned. However, for the same reason, the alignment may slightly change during the second run.
Images are processed sequentially. Each image is subtracted from the total average, aligned to the average of the remaining images, and add back if new parameters result in the increased value of the criterion. After each iteration the images are centered using the phase approximation of the cetner of gravity phase_cog. Should this fail, the user is encourage to change the code.
The program will not change the input images, only the alignment parameters in their header. In order to apply the alignment parameters to the images, use program sxtransform2d.
Program uses simplex optimization method to refine for each image three orientation parameters (psi, sx, sy) such that the inner product between the image and the average of remaining images is maximized.
Author / Maintainer
Pawel A. Penczek
- category 1
- category 3
- works for author, often works for others.
The centering may fail. It will also fail if the images are not very similar to each other, say circles and rectangles.