Name

sxmref_ali2d - Perform 2-D multi-reference alignment of an image series

Usage

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.

Typical usage

1. 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
2. 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
3. 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)

Input

stack

set of 2-D images in a stack file (format hdf or bdb), images have to be squares (nx=ny)

refim

set of initial reference 2-D images in a stack file (format hdf or bdb)

maskfile

optional maskfile to be used in the alignment

The parameters preceded with -- are optional and default values are given in parenthesis.

inner_radius

inner radius for rotational correlation > 0 (set to 1)

outer_radius

outer radius for rotational correlation < nx/2-1 (set to nx/2-2, should be set to the radius of the particle)

ring_step

step between rings in rotational correlation >0 (set to 1)

x_range

range for translation search in x direction, search is +/xr (set to zero, which corresponds to rotational alignment only)

y_range

range for translation search in y direction, search is +/yr (set to zero, which corresponds to rotational alignment only)

translation_step

step of translation search in both directions (set to 1, larger value increase the speed, but decrease the accuracy)

center

0 - if you do not want the average to be centered, 1 - center the average (default=1)

maxit

maximum number of iterations the program will perform (set to 10)

CTF

if this flag is set, the program will use CTF information provided in file headers (for details see I_O).

snr

signal-to-noise ratio of the data (default SNR=1.0)

user_function_name

name of the reference preparation function

rand_seed

the seed used for generating random numbers (set to 1000)

MPI

whether to use MPI version

Output

output_directory

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).

header

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.

Description

• 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.

Method

Will describe one of these days....

Reference

Penczek 1992

Author / Maintainer

Pawel A. Penczek

Keywords

category 1

APPLICATIONS

category 2

FOURIER

Files

sparx/bin/sxali2d_m.py, applications.py

See also

sxlocal_ali2d, sxali2d, sxtransform2d, sxk_means, sxk_means_groups

Maturity

beta

works for author, often works for others.

Bugs

The centering may fail. It will also fail if the images are not very similar to each other, say circles and rectangles.