sxmref_ali2d - Perform 2-D multi-reference alignment of an image series
Usage in command line:
sxmref_ali2d.py data_stack reference_stack outdir <maskfile> --ir=inner_radius --ou=outer_radius --rs=ring_step --xr=x_range --yr=y_range --ts=translation_step --center=center_type --maxit=max_iteration --CTF --snr=SNR --function=user_function_name --rand_seed=random_seed --MPI
Usage in Python programming:
mref_ali2d((stack, refim, outdir, maskfile=None, ir=1, ou=-1, rs=1, xrng=0, yrng=0, step=1, center=1, maxit=0, CTF=False, snr=1.0, user_func_name="ref_ali2d", rand_seed=1000, MPI=False)
- To use MPI version:
- mpirun -np 32 sxali2d.py ... --MPI
- The above example is for mympi.
Prepare stack file with initial averages. Normally, they would result from running the 2-D alignment sxali2d and K-means classification sxk_means. Set the particle radius, and x-y range for translational search:
- sxmref_ali2d.py input_stack.hdf ref_stack.hdf output_directory --ou=27 --xr=3 --yr=3 --maxit=6
- Continue the alignment from the previous result by replacing the ref_stack by the result of the previous run and using the same input_stack which has in the header previously obtained orientation paramters:
- sxmref_ali2d.py input_stack.hdf output_directory/aqm005.hdf next_output_directory --ou=27 --xr=3 --yr=3 --maxit=6
- The above command is written in python program as:
- mref_ali2d(input_stack.hdf, output_directory/aqm005.hdf, next_out_directory, ou=27, xr=3, yr=3, maxit=6)
set of 2-D images in a stack file (format hdf or bdb), images have to be squares (nx=ny)
- set of initial reference 2-D images in a stack file (format hdf or bdb)
- optional maskfile to be used in the alignment
The parameters preceded with -- are optional and default values are given in parenthesis.
inner radius for rotational correlation > 0 (set to 1)
outer radius for rotational correlation < nx/2-1 (set to nx/2-2, should be set to the radius of the particle)
step between rings in rotational correlation >0 (set to 1)
- range for translation search in x direction, search is +/xr (set to zero, which corresponds to rotational alignment only)
- range for translation search in y direction, search is +/yr (set to zero, which corresponds to rotational alignment only)
- step of translation search in both directions (set to 1, larger value increase the speed, but decrease the accuracy)
- 0 - if you do not want the average to be centered, 1 - center the average (default=1)
- maximum number of iterations the program will perform (set to 10)
if this flag is set, the program will use CTF information provided in file headers (for details see I_O).
- signal-to-noise ratio of the data (default SNR=1.0)
- name of the reference preparation function
- the seed used for generating random numbers (set to 1000)
- whether to use MPI version
- 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 kinds of files: averages of the aligned image series (aqm***.hdf, numbered by the iteration number) and the Fourier Resolution Criterion curve (drm*******, first three digits indicate iteration number, last four indicate the reference image number).
- the alignment parameters are stored in the headers of input files as 'xform.align2d'. In addition, attribute 'assign' indicates which reference the image was assigned to.
For the program to work, attributes 'xform.align2d' have to be set in the header of each file. If their values are not known, all should be set to zero, please refer to sxheader.
- The program will start alignment from the current alignment parameters 'xform.align2d' stored in file headers. To erase previous alignment result, set them all to zero.
- The program prints the value of the alignment criterion, which is of no consequence.
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.
Will describe one of these days....
Author / Maintainer
Pawel A. Penczek
- category 1
- category 2
- 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.