Name

sxali3d - Perform 3-D projection matching given initial reference volume and image series

Usage

usage in command line

sxali3d.py stack ref_vol outdir <maskfile> --ir=inner_radius --ou=outer_radius --rs=ring_step --xr=x_range --yr=y_range --ts=translational_search_step --delta=angular_step --an=angular_neighborhood --deltapsi=Delta_psi --startpsi=Start_psi --center=center_type --maxit=max_iter --CTF --snr=SNR --ref_a=S --sym=c1 --function=user_function --Fourvar=Fourier_variance --debug --MPI

usage in python programming

ali3d(stack, ref_vol, outdir, maskfile = None, 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, maxit = 5, CTF = False, snr = 1.0, ref_a = "S", sym = "c1", user_func_name = "ref_ali3d", fourvar = True, debug = False, MPI = False)

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:

   • sxali3d.py input_stack.hdf ref_vol.hdf output_directory mask.hdf --ou=27 --rs=1 --xr='4 2 2 1' --ts='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:

   • ali3d(input_stack.hdf, ref_vol.hdf, output_directory, maskfile, ou=27, rs=1, xr='4 2 2 1', ts='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 , ts, delta, and an should have the same number of entries

4. To use MPI version:
5. 1. add flag --MPI
6. 2. mpirun -np 32 sxali3d_d.py --MPI and the remaining parameters
7. The above example is for mympi.

Input

stack

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_vol

initial reference volume

outdir

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

maskfile

filename of the file containing 3D mask. If not provided, a 3D spherical mask will be created with radius equal to outer_radius. This mask is used to multiply the reference volume for calculation of reference projections.

The parameters preceded with -- are optional and default values are given in parenthesis. Note ir, ou, rs, xr, yr, ts are in pixels while delta, an are in degrees.

ir

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

ou

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

steps between rings in rotational correlation >0 (default 1).

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 )

ts

step size of the translation search in both directions, search is -xr, -xr+ts, 0, xr-ts, xr, 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

-1 - average center method, 0 - if you do not want the average to be centered, 1 - center the average (default=-1. Note: do not use anything but default unless absolutely necessary.)

max_iter

maximum iterations at each angle step (set to 5)

CTF

if the flag is present, program will use the CTF information 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 refined structure

function

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

MPI

if present use MPI version

npad

Padding size for 3D reconstruction, by default it is set to 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 files will be written to this directory. 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 Transform Object xform.projection

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. For a given delta, the program will perform maxit round refinement. So the final refinement iteration is maxit*(number of delta values)
• For the program to work, attributes xform.projection (Transform object containing three Euler angles and two in-plane shifts) 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 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, "The ribosome at improved resolution: new techniques for merging and orientation refinement in 3D cryo-electron microscopy of biological particles", Ultramicroscopy 53, 251-270.

Author / Maintainer

Pawel A. Penczek

Keywords

category 1

APPLICATIONS

category 3

GRIDDING

Files

sparx/bin/sxali3d.py

See also

sxlocal_ali3d

Maturity

beta

works for author, often works for others.

Bugs

Did not discover any yet.