Name

sxmref_ali3d - perform 3-D multireference projection matching given initial reference volumes and image series

Usage

usage in command line:

sxmref_ali3d.py stack ref_vols outdir <mask> --ir=inner_radius --ou=outer_radius --rs=ring_step --xr=x_range --yr=y_range --ts=translational_searching_step --delta=angular_step --an=angular_neighborhood --center=1 --nassign=reassignment_number --nrefine=alignment_number --maxit=max_iter --stoprnct=percentage_to_stop --debug --fourvar=fourier_variance --CTF --snr=1.0 --ref_a=S --sym=c1 --function=user_function --MPI

usage in python programming:

mref_ali3d(stack, ref_vol, outdir, maskfile=None, maxit=1, ir=1, ou=-1, rs=1, xr = "4 2 2 1", yr = "-1", ts = "1 1 0.5 0.25", delta="10 6 4 4", an="-1", center = 1.0, nassign = 3, nrefine = 1, CTF = False, snr = 1.0, ref_a = "S", sym="c1", user_func_name="ref_ali3d", MPI=False, debug = False, fourvar=False, termprec = 0.0)

Typical usage

1. Four iterations of 3-D projection alignment with an angular step from 10 to 2, translation from 1 to 0.25, and 3 internal iterations at each angular step:

   • sxmref_ali3d.py input_stack.hdf ref_vol.hdf output_directory <mask.hdf> --ou=27 --rs=1 --xr='4 2 2 1' --translation_step='1.0 1.0 0.5 0.25' --delta='10 6 4 2' --an='20 20 10 5' --snr=1.0 --maxit=3 --ref_a=S --sym=c2

2. The above command is written in python code as:
   • mref_ali3d(input_stack.hdf, ref_vol.hdf, output_directory, maskfile, ou=27, rs=1, xr='4 2 2 1', translation_step='1.0 1.0 0.5 0.25', delta='10 6 4 2', an='20 20 10 5', snr=1.0, maxit=3, ref_a="S", sym="c2")
3. Notice: xr , translation_step, and delta should have the same number of entries

4. To use MPI || version:

5. 1. change the MPI flag in global_def.py to True
6. 2. mpirun -np 32 sxali3d_m.py and the remaining parameters
7. The above example is for mympi.

Input

input_stack.hdf

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

ref_vols

set of 3-D initial reference volumes

outdir

directory name into which the results will be written (if it does not exist, it will be created, if it does exists, the results will be written possibly overwriting previous results)

maskfile

filename used to create the mask

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 <int(nx/2)-1 (set to int(nx/2)-2, should be set to the radius of the particle)

rs

ring steps

xr

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

yr

range for translation search in y direction in each iteration, search is +/yr (by defalut it is the same as xr)

translation_step

step between rings in rotational correlation >0 (set to 1). It can be fractional.

delta

angular step for the reference projections in respective iterations

an

angular neighborhood for local searches (default '-1', i.e., perform exhaustive searches)

center

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

max_iter

maximum iterations at each angle step (set to 5)

CTF

if the flag is present, program will use the CTF information in stored in file headers

snr

signal noise ratio used in the 3D reconstruction, by default it is set as 1.0

ref_a

method for creating quasi-uniform distribution of the projection directions of reference projections: "S" - spiral, "P" - equal steps of theta (default="S")

sym

symmetry of the volume under reconstruction.

reassignment_number

number of reassignment iterations performed for each angular step (set to 3)

alignment_number

number of alignment iterations performed for each angular step (set to 1)

percentage_to_stop

Minimum percentage of assignment change to stop the program

fourier_variance

compute and use fourier variance

npad

padding size for 3D reconstruction, default is 2

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 the low-pass filtered reconstructed volume volf****.spi, and Fourier ring correlation text file resolution****.

header

the alignment parameters are stored in the headers of input files as xform.projection and assignment to reference volumes as group (it is an index ranging from zero to number of templates minus one).

Description

• This program uses a user defined projection angle and translation shift to perform 3D reconstruction. The translation shifts, and step are not limited to integer number. Under a given theta step, the program will perform maxit round refinement. So the final refinement iteration is maxit*number_of_theta_step.
• For the program to work, attribute xform.projection has 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 xform.projection stored in file headers.
• The program only change the alignment parameters in their header. The images in stack keep untouched. ( Neither rotated nor shifted. )

Method

Reference

Penczek 1994

Author / Maintainer

Pawel A. Penczek

Keywords

category 1

APPLICATIONS

category 3

GRIDDING

Files

sparx/bin/sxmref_ali3d.py

See also

sxlocal_ali3d

Maturity

beta

works for author, often works for others.

Bugs

Who knows?