13403
Comment:

← Revision 29 as of 20180109 22:26:16 ⇥
13434

Deletions are marked like this.  Additions are marked like this. 
Line 6:  Line 6: 
To run the program:  To run the program (it requires MPI installation): 
Name This page is a stub. 09/09/2013
sxheliconlocal  3D structure determination of helical filaments using singleparticle method
Description
To run the program (it requires MPI installation):
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 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 inplane 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 precentered 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
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
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
Note: the helical symmetry axis is oriented to coincide with zaxis of the coordinate system. This implies in 2D images the symmetry axis is along y axis.
Input
 stack
set of 2D 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/21 (set to nx/22, should be set to half of the segment length decreased by a significant margin 510%) (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 ydirection; 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 ydirection 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 outplane 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 90k*delta_theta , where k = 0, 1..,theta_number and theta_number = [(90initial_theta)/detla_theta].
 apix
 pixel size in Angstroms (required).
 sym
 pointgroup 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 [dpndp*dp_step, dp(ndp1)*dp_step, .., 0, ..,dp+(ndp1)*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 [dphindphi*dphi_step, dphi(ndphi1)*dphi_step, .., 0, ..,dphi+(ndphi1)*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 userprovided 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 lowpass filter the structure.
 psi_max
 maximum psi  how far rotation inplaneof 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)
 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
 signaltonoise 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
 Behrmann, E., Tao, G., Stokes, D.L., Egelman, E.H., Raunser, S., and Penczek, P.A., 2012. Realspace processing of helical filaments in SPARX. J Struct Biol 177, 302313.
 Egelman, E. H. (2000). A robust algorithm for the reconstruction of helical filaments using singleparticle methods. Ultramicroscopy, 85, 225–234.
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