Name

sxviper - Initial 3D Model - VIPER: ab initio 3D structure determination using Validation of Individual Parameter Reproducibility (VIPER). Designed to determine a validated initial model using a small set of class averages produced by ISAC.

Usage

usage in command line

sxviper.py stack directory --ir=inner_radius --radius=outer_radius --rs=ring_step --xr=x_range --yr=y_range --mask3D=mask3D --moon_elimination=moon_elimination --ts=translational_search_step --delta=angular_step --center=center_type --maxit1=max_iter1 --maxit2=max_iter2 --L2threshold=0.1 --ref_a=S --sym=c1 --nruns=nruns --doga=doga --fl=fl --aa=aa --pwreference=pwreference --debug

Typical usage

sxviper exists only in MPI version.

mpirun --npernode 16 -np 24 --host node1,node2 sxviper.py stack output_directory --fl=0.25 --radius=30 --xr=2 --moon_elimination=750,4.84

A fast track option, that can be used to choose parameters in the appropriate ranges (for example, obtaining adequate spatial frequency filtering '--fl') is provided below. Since it employs extreme values for some parameters this command can be used only for parameter tuning for the VIPER algorithm.

mpirun --npernode 16 -np 16 --host node1 sxviper.py stack output_directory --fl=0.25 --radius=30 --xr=1 --nruns=2 --L2threshold=1.0e300 --doga=-1

The VIPER program needs MPI environment to work properly. Number of used MPI processes MUST BE a multiple of --nruns (default = 6).

Since VIPER makes use of group of processors working together, it is important from a time efficiency point of view to have processors within a group being allocated on the same node. This way any data exchange within the group does not use network traffic. The "--npernode" option of mpirun is useful in accomplishing this goal. As shown in the example below when "--npernode" is used mpi allocates the ranks of the processors sequentially, not moving to the next node until the current one is filled. If "--npernode" is not used then processors are allocated in a round robin fashion (i.e. jumping to the next node with each allocation). Since in VIPER, groups contain consecutively ranked processors, it is important to provide "--npernode XX" where XX is the number of processors per node.

Input

stack: Input images stack: The images must be square. (default required string)
radius: Particle radius [Pixels]: has to be less than half the box size. (default required int)
sym: Point-group symmetry: (default c1)
xr: X search range [Pixels]: The translational search range in the x direction will take place in a +/xr range. (default '0')
yr: Y search range [Pixels]: The translational search range in the y direction. If omitted it will be xr. (default '0')
mask3D: 3D mask: (default sphere)
moon_elimination: Eliminate disconnected regions: Used to removed disconnected pieces from the model. It requires as argument a comma separated string with the mass in KDa and the pixel size. (default none)
ir: Inner rotational search radius [Pixles]: (default 1)
rs: Ring step size: Step between rings used for the rotational search. (default 1)
ts: Translational search step [Pixels]: The search will be performed in -xr, -xr+ts, 0, xr-ts, xr, can be fractional. (default '1.0')
delta: Projection angular step [Degree]: (default '2.0')
center: Center 3D template: 0: no centering; 1: center of gravity (default -1.0)
maxit1: Maximum iterations - GA step: (default 400)
maxit2: Maximum iterations - Finish step: (default 50)
L2threshold: GA stop threshold: Defines the maximum relative dispersion of volumes' L2 norms. (default 0.03)
ref_a: Projection generation method: Method for generating the quasi-uniformly distributed projection directions. S- Saff algorithm, or P - Penczek 1994 algorithm. (default S)
nruns: GA population size: This defines the number of quasi-independent volumes generated. (default 6)
doga: Threshold to start GA: Do GA when the fraction of orientation that changes less than 1.0 degrees is at least this fraction. (default 0.1)
fl: Low-pass filter frequency [1/Pixel]: Using a hyperbolic tangent low-pass filter. (default 0.25)
aa: Low-pass filter fall-off: Fall-off of for the hyperbolic tangent low-pass filter. (default 0.1)
pwreference: Power spectrum reference: Text file containing a 1D reference power spectrum. (default none)
debug: Verbose: Print debug info. (default False)

Output

directory: Output directory: The directory will be automatically created and the results will be written here. If the directory already exists, results will be written there, possibly overwriting previous runs. (default required string)

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

Author / Maintainer

Pawel A. Penczek

Keywords

category 1: APPLICATIONS

Files

sparx/bin/sxviper.py

Maturity

beta: works for author, often works for others.

Bugs

Did not discover any yet.