Name

sxihrsr - 3D structure determination of helical filaments using single-particle method

Description

To run the program:

mpirun -np 32 sxihrsr.py bdb:stack ref_vol.hdf result --ou=152 --xr=1.0 --txs=0.5 --ynumber=8 --delta=1.5 --an=-1 --maxit=20 --snr=1 --MPI --nise=0 --dp=5.026 --ndp=4 --dp_step=0.0005 --dphi=-106.65 --ndphi=4 --dphi_step=0.005 --psi_max=7 --rmin=0 --rmax=34 --fract=0.67 --npad=2 --datasym=symdoc.dat --function=[.,nofunc,helical] --CTF

Depending on the dimension of ref_vol, the program will use different reconstruction and projection methods. If the ref_vol is cubic, the cubic reconstruction and projection method will be used. Otherwise, the rectangular reconstruction and projection method will be used. In order to reduce the computational time and save the memory, we recommended that user give rectangular volume as reference.

The attributes xform.projection (Transform object containing the projection orientation parameters of an image: three Euler angles and two in-plane shifts) have to be set in the header of each image in the input stack. If the projection orientations are not known, then set them to zero. For more information on how to set projection orientation parameters, see I_O and Euler_angles.

Guidelines to determine the alignment related parameters.

For effective alignment, the step sizes chosen for directional search in x and y (--txs and --ynumber, respectively) as well as the radial resolution (--delta) should match each other:

1) --txs should be determined first (based on whether filaments were pre-centered or not).

2) the step size chosen for y direction should be set to a similar setting as for --txs. However, y search range is dependent of helical symmetry parameters and y direction cannot be set directly. Instead, y step size corresponds to: tys = dp( Angstroms) /Pixel_size/ynumber. By selecting a proper even ynumber, we can make tys approach txs.

Example of a typical user function. 

# this user function simply applies low pass filteration to the input volume
# Note that the volume is symmetrized and helicised both prior and and after call to this function, which is meant to reduce filtration artifacts.
from EMAN2_cppwrap import *
from global_def import *
def helical3( ref_data ):
        from utilities      import print_msg
        from filter         import fit_tanh, filt_tanl
        from morphology     import threshold
        from utilities import sym_vol
        #  Input: list ref_data
        #   0 - raw volume
        #  Output: filtered, and masked reference image
        stat = Util.infomask(ref_data[0], None, True)
        volf = ref_data[0] - stat[0]
        fl = 0.3
        aa = 0.2
        volf = filt_tanl(volf, fl, aa)
        return  volf

Usage

Three typical cases ( mainly differentiated by with/without helical parameters searching, with/without out of plane tilt angle ) are decribed here; the corresponding example commands of each case are also given.

In case 1, we enforce the known helical parameters at all the iterations and don't consider the out of plane tilt of the micrograph.

In case 2, we enforce initial helical parameters during the first two iterations and then start to search for helical parameters. The out of plane tilt of the micrograph is ignored.

In case 3, we start to search the helical parameters after two iterations and consider the out of plane tilt of the micrograph.

In all the case, the maximum radius of helix is set to 30 ( --rmax=30), and the user function used is helical stored in nofunc.py of current directory.

Case 1

Helical rise dp = 27.6 Angstroms, helical angle dphi = -166.715

No out of plane tilt.

No searching for helical parameters ( nise = maxit ).

Angular step to generate the reference projection: delta = 1.5.

Pixel size is 1.84

How far rotation in plane can deviate from 90 or 270 degrees: psi_max=12.0

Command

mpirun -np 4 sxihrsr.py bdb:data ini.hdf result --ou=95 --apix=1.84 --xr=1.84 --ynumber=2 --txs=1.84 --maxit=10 --nise=10 --dp=27.6 --dphi=-166.715 --psi_max=12.0 --rmax=30 --npad=2 --datasym=symdoc.dat --function="[.,nofunc,helical]" --CTF --MPI

Case 2

Initial helical rise dp = 27.5 Angstroms, initial helical angle dphi = -166.4.

Start to search helical parameters after two iterations ( nise = 2 ).

No out of plane tilt angle.

Angular step to generate the reference projection: delta = 1.5.

Point group symmetry: sym="c2".

Pixel size is 1.84

How far rotation in plane can deviate from 90 or 270 degrees: psi_max=12.0

Command

mpirun -np 4 sxihrsr.py bdb:data ini.hdf result --ou=95 --delta=1.5 --apix=1.84 --xr=1.84 --ynumber=2 --txs=1.84 --maxit=10 --nise=2 --dp=27.5 --ndp=12 --dp_step=0.1 --dphi=-166.4 --ndphi=12 --dphi_step=0.1 --psi_max=12.0 --rmax=30 --npad=2 --datasym=symdoc.dat --function="[.,nofunc,helical]" --sym="c2" --CTF --MPI

Case 3

Initial helical rise dp = 27.5 Angstroms, initial helical angle dphi = -166.4.

Start to search helical parameters after two iterations ( nise = 2 ).

With out of plane tilt angel up to 5 degree: initial_theta =85 and step of out of plane tilt: delta_theta = 1.0.

Angular step to generate the reference projection: delta = 1.5.

Point group symmetry: sym="c2".

Pixel size is 1.84

How far rotation in plane can deviate from 90 or 270 degrees: psi_max=12.0

Command

mpirun -np 4 sxihrsr.py bdb:data ini.hdf result --ou=95 --delta=1.5 --initial_theta=90.0 --delta_theta=1.0 --apix=1.84 --xr=1.84 --ynumber=2 --txs=1.84 --maxit=10 --nise=10 --dp=27.5 --ndp=12 --dp_step=0.1 --dphi=-166.4 --ndphi=12 --dphi_step=0.1 --psi_max=12.0 --rmax=30 --npad=2 --datasym=symdoc.dat --function="[.,nofunc,helical]" --sym="c2" --CTF --MPI

Note: the helical symmetry axis is oriented to coincide with z-axis of the coordinate system. This implies in 2D images the symmetry axis is along y axis.

Input

stack

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

ref_vol
the initial volume for helical refinement.
outdir
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 the directory and then restart the program . The output files will be written to this directory (see below).
ou

outer radius for rotational correlation in projection matching < nx/2-1 (set to nx/2-2, should be set to half of the segment length decreased by a significant margin 5-10%) (in Angstroms).

rs

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

xr
range for translation search in x direction, search is +/-xr (is set to "4 2 1 1", if set to "0" it corresponds to rotational alignment only) (in Angstroms).
txs
step of translation search in x direction, (set to "2 1 0.5 0.25", larger value increase the speed, but decrease the accuracy) (in Angstroms).
ynumber
number of search steps in y direction. The step size for translational search in the y direction is determined as dpp/ynumber, where dpp is the rise dp in pixels and is calculated internally as dp/pixelsize. ynumber should be even, and ynumber=0 with xr=0 corresponds to rotational alignment only. If ynumber=-1, then step size for translational search in y direction is set to the step size for translational search in x direction.
y_restrict
range for restricted translational search in y-direction; the search range is +/-y_restrict in Angstroms. This only applies to local search, i.e., when an is not -1. If y_restrict=-1, the default value, then there is no y search range restriction. The step size used for restricted translational search in y-direction is the same as unrestricted search, i.e., dpp/ynumber, where dpp is the rise in pixels.
delta

angular step of phi angle for generating reference projections. Unless initial_theta is set to a number lower than 90, only projections perpendicular to the symmetry axis z will be generated. Thus, delta=1 results in 180 reference projections.

an
angular neighborhood for local searches (default is -1, exhaustive search).
initial_theta
value used to generate reference projection with out-plane tilt angle. Default is 90. When given, theta angle will varies from initial_theta to 90 degree.
delta_theta

angular step of theta angle. Default is 1. Theta angle forgenerating reference projection will be 90-k*delta_theta , where k = 0, 1..,theta_number and theta_number = [(90-initial_theta)/detla_theta].

apix
pixel size in Angstroms (required).
sym
point-group symmetry of the structure (default is c1).
dp
delta z - axial rise in Angstroms (first of the two parameters defining initial guess of the helical symmetry) and will be updated by the program in accordance with current estimate of helical symmetry.
dp_step
step size for delta z search and is determined by the user depending on the symmetry of the structure.
ndp
number of steps for searching for dp refinement, the possible search for dp is [dp-ndp*dp_step, dp-(ndp-1)*dp_step, .., 0, ..,dp+(ndp-1)*dp_step, dp+ndp*dp_step]
dphi

delta phi - azimuthal rotation per subunit in degrees (second of the two parameters defining initial guess of the helical symmetry) and will be updated by the program in accordance with current estimate of helical symmetry.

dphi_step

step size for angular search of phi, it is determined by the user depending on the symmetry of the structure.

ndphi
number of steps for searching for dphi refinement, the possible search for dphi is [dphi-ndphi*dphi_step, dphi-(ndphi-1)*dphi_step, .., 0, ..,dphi+(ndphi-1)*dphi_step, dphi+ndphi*dphi_step]
rmin

minimal radius for the helical symmetry search (in Angstroms) and for imposing helical symmetry. The volume will be set to zero outside of the hollow cylinder rmin<r<rmax.

rmax

maximal radius for the helical symmetry search (in Angstroms) and for imposing helical symmetry. The volume will be set to zero outside of the hollow cylinder rmin<r<rmax.

function
name of the user-provided reference volume preparation function. This function is invoked at each iteration to prepare the template structure for the next iteration. Most common use is to low-pass filter the structure.
psi_max
maximum psi - how far rotation in-planeof the input projection can can deviate from 90 or 270 degrees
fract
fraction of the volume used for helical search (reasonable number os 0.67)
nise

start refining helical symmetry after nise steps. During first nise steps, the program will enforce helical symmetry defined by parameters dp and dphi.

npad
padding size for 3D reconstruction (default npad=2).
maxit
maximum number of iterations the program will perform (default is 10)
CTF

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

MPI
use MPI version (default no MPI, but the non-MPI version is not operational)
datasym
text file where updated helical symmetry parameters are stored.
new
use rectangular recon and projection version (default is false).
WRAP
do helical wrapping if equal to 1 (default is 1)

Optional inputs that are better left as they are

maskfile
optional mask file to be used internally during alignment
snr
signal-to-noise ratio of the data (default SNR=1.0)
debug
if present, the program will output additional information.

Output

Output files are written to the output directory whose name is specified by the user.

datasym
symdoc - output ASCII file that contains symmetry parameters found for each iteration.
parameters
parameters_****_****.txt contains transformation parameters for each segment of micrograph. The file name is numbered by the step number and number of iterations at certain step. The transformation is xform.projection and contains three Euler angles and x, y shifts.
pixel errors
pixer_****-****.txt contains pixel errors for each projection image - they represent compound amount of change (angles and translation) in projection orientation between two consecutive iterations. The file name is numbered by the step number and number of iterations at certain step.
reconstructed volume
vol****.hdf, the 3D reconstructed volume got right after the reconstruction.
helicised volume after reconstruction
volf****.hdf, the 3D volume obtained by applying helical symmetry and user function on the reconstructed volume.

Method

Reference

Author / Maintainer

Pawel A. Penczek

Keywords

category 1
APPLICATIONS

Files

sparx/bin/sxihrsr.py, applications.py

See also

Maturity

beta
works for author, often works for others.

Bugs

sxihrsr (last edited 2015-05-28 20:15:15 by penczek)