sp_viper

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


Usage

Usage in command line

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


Typical usage

sp_rviper exists only in MPI version.

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

A faster version using restricted ranges of parameters.

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

The VIPER program exists only in MPI version. Number of MPI processes must be a multiple of --nruns (default = 6).

Since VIPER uses group of processors working together, it is important for efficient execution to have processors within a group allocated to the same node. This way any data exchange within the group does not involve network traffic. The --npernode option of mpirun accomplishes 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

Main Parameters

stack
Input images stack: A small subset of class averages produced by ISAC2. (default required string)
directory
Output directory: The automatically-created output directory will contain results. If the directory already exists, results will be written there, possibly overwriting previous runs. (default required string)
--radius
Particle radius [Pixels]: Use the same value as in ISAC2. It has to be less than half the box size. (default 29)
--sym
Point-group symmetry: Point-group symmetry of the particle. (default c1)
--moon_elimination
Eliminate disconnected regions: Used to removed disconnected pieces from the model. As an argument it requires a comma-separated string with the mass in KDa and the pixel size in [A]. (default none)


Advanced Parameters

--ir
Inner rotational search radius [Pixels]: Inner rotational search radius [Pixels]. (default 1)
--rs
Ring step size [Pixels]: Step between rings used for the rotational search. (default 1)
--xr
X search range [Pixels]: The translational search range in the x direction. Search will +/-xr range in steps of ts. (default '0')
--yr
Y search range [Pixels]: The translational search range in the y direction. If omitted it will be xr. (default '0')
--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 [Degrees]: Projection angular step. (default '2.0')
--center
Center 3D template: -1: center of coordinates, 0: no centering; 1: center of gravity (default -1.0)
--maxit1
Maximum iterations - GA step: Maximum number of iterations for GA step. (default 400)
--maxit2
Maximum iterations - Finish step: Maximum iterations number of for Finish step. (default 50)
--mask3D
3D mask: Path to 3D mask file. (default sphere)
--L2threshold
GA stop threshold: Defines the maximum relative dispersion of structures' 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 structures 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/Pixels]: Using a hyperbolic tangent low-pass filter. Specify with absolute frequency. (default 0.25)
--aa
Low-pass filter fall-off [1/Pixels]: Fall-off of for the hyperbolic tangent low-pass filter. Specify with absolute frequency. (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


Description

  • This program uses a Genetic Algorithm (GA) strategy to deliver a validated 3D ab initio structure. It will first compute simultaneously ab initio structures
  • whose number will be equal to the population size. Next, it will compare solutions and apply evolutionary operators (merge some of the solutions)
  • to produce their offsprings, which subsequently are used as initial structures for the next generation of GA processing.
  • By default, structures in the first generation are initialized randomly.
  • However, the program will start alignment from the alignment parameters xform.projection stored in file headers, if provided.
  • The program only change the alignment parameters in header. The images in stack are untouched. (Neither rotated nor shifted.)


Method


Reference


Developer Notes


Author / Maintainer

Pawel A. Penczek


Keywords

Category 1:: APPLICATIONS


Files

sparx/bin/sp_viper.py


See also

Maturity

Beta:: Under evaluation and testing. Please let us know if there are any bugs.


Bugs

There are no known bugs so far.