# Name This page is a stub. 09/09/2013

sxheliconlocal - 3D structure determination of helical filaments using single-particle 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 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

## 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 *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)

- 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

- Behrmann, E., Tao, G., Stokes, D.L., Egelman, E.H., Raunser, S., and Penczek, P.A., 2012. Real-space processing of helical filaments in SPARX. J Struct Biol 177, 302-313.
- Egelman, E. H. (2000). A robust algorithm for the reconstruction of helical filaments using single-particle 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