Name

sxlocal_ali2d - Perform local refinement of 2-D alignment of an image series

Usage

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

Typical usage

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

Input

stack

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

maskfile

optional mask file to use internally during alignment

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

outer_radius

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

br

brackets for the search of orientation parameters (each parameter will be checked +/- bracket) (set to 1.75)

center_type

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

epsilon

stopping criterion, program will terminate when the relative increase of the criterion is less than epsilon (set to 0.001)

max_iter

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

CTF

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)

snr

Signal-to-Noise Ratio of the data (default SNR=1.0)

function

name of the user-supplied function that prepares reference image for each iteration (default ref_ali2d)

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

header

the alignment parameters are stored in the headers of input files as 'alpha', 'sx', 'sy', 'mirror'

Description

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

Method

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.

Reference

Author / Maintainer

Pawel A. Penczek

Keywords

category 1

APPLICATIONS

category 3

GRIDDING

Files

sparx/bin/sxali2d_e.py

See also

sxtransform2d

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.