Differences between revisions 47 and 48
Revision 47 as of 2015-07-28 23:45:32
Size: 7167
Editor: penczek
Comment:
Revision 48 as of 2015-07-28 23:48:34
Size: 7277
Editor: penczek
Comment:
Deletions are marked like this. Additions are marked like this.
Line 77: Line 77:
In the example below, RVIPER found in the third iteration (main003) a set of 3 reconstructed volumes whose projections show stable angle assignment. In the example below, RVIPER found in the third iteration (main003) a set of 3 reconstructed volumes whose projections show stable angle assignment. The program generates "average_volume.hdf" and "variance_volume.hdf" based on the three reconstructed volumes.

sxrviper - Validated ab initio 3D structure determination, aka Reproducible VIPER

Usage

usage in command line

sxrviper.py stack output_directory --ir=inner_radius --ou=outer_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 --L2threshold=0.1 --CTF --snr=SNR --ref_a=S --sym=c1 --function=user_function --moon_elimination --criterion_name --outlier_index_threshold_method --use_latest_master_directory

Typical usage

  1. sxrviper.py --outlier_percentile=95 --fl=0.1 --ou=30 --xr=2 --center=0 --n_shc_runs=4 --n_rv_runs=4 --moon_elimination=750,4.84
  2. sxrviper.py --outlier_percentile=95 --fl=0.1 --ou=30 --xr='4 2 2 1' --ts='1.0 1.0 0.5 0.25' --ts='1.0 1.0 0.5 0.25' --delta='10 6 4 2' --center=0 --n_shc_runs=4 --n_rv_runs=4 --moon_elimination=750,4.84
    • Notice: xr , ts, delta, and an should have the same number of entries

Input

stack

set of 2-D images in a stack file (format hdf), images have to be squares (nx=ny, nx, ny denotes the image size)

initial_volume
initial reference volume
output_directory
directory name into which the results will be written (if it does not exist, it will be created, if it does exist, the results will be written possibly overwriting previous results)
  • The parameters preceded with -- are optional and default values are given in parenthesis. Note ir, ou, rs, xr, yr, ts are in pixels while delta, an are in degrees.

  • ir

    inner radius for rotational correlation > 0 (default 1)

    ou

    outer radius for rotational correlation <int(nx/2)-1 (set to int(nx/2)-2, should be set to the radius of the particle)

    rs

    steps between rings in rotational correlation >0 (default 1)

    xr
    range for translation search in x direction in each iteration, search is +/xr (default is zero, which corresponds to rotational alignment only)
    yr
    range for translation search in y direction in each iteration, search is +/yr (by defalut it is the same as xr)
    ts
    step size of the translation search in both directions, search is -xr, -xr+ts, 0, xr-ts, xr, can be fractional
    delta
    angular step for the reference projections in respective iterations
    an
    angular neighborhood for local searches (default '-1', i.e., perform exhaustive searches)
    center

    -1 - average center method, 0 - if you do not want the average to be centered, 1 - center the average (default=-1. Note: do not use anything but default unless absolutely necessary.)

    maxit1
    maximum number of iterations performed for the GA part (set to 400)
    maxit2
    maximum number of iterations performed for the finishing up part (set to 30)
    L2threshold
    Stopping criterion of GA given as a maximum relative dispersion of L2 norms (set to 0.05)
    CTF
    if the flag is present, program will use the CTF information stored in file headers
    snr
    signal noise ratio used in the 3D reconstruction, by default it is set as 1.0
    ref_a
    method for creating quasi-uniform distribution of the projection directions of reference projections: "S" - spiral, "P" - equal steps of theta (default="S")
    sym
    symmetry of the refined structure (default c1)
    function

    name of the user-supplied-function that prepares reference image for each iteration (default ref_ali3d)

    n_shc_runs
    number of quasi-independent runs (shc) (default=3)
    n_rv_runs
    number of r_viper runs (default 10)
    n_v_runs
    number of viper runs for each r_viper cycle (default=3)
    doga
    do GA when fraction of orientation changes less than 1.0 degrees is at least doga (default=0.3)
    npad
    Padding size for 3D reconstruction, by default it is set to 2
    outlier_percentile
    percentile above which outliers are removed every iteration (default=95)
    iteration_start
    starting iteration for rviper, 0 means go to the most recent one (default=0)
    moon_elimination
    mass in KDa and resolution in px/A separated by comma, no space (default=none)
    criterion_name
    default: "80th percentile", other options:"fastest increase in the last quartile"
    outlier_index_threshold_method
    default: discontinuity_in_derivative, other options:"percentile","angle_measure"
    use_latest_master_directory
    when active, the program looks for the latest directory that starts with the word "master"

    Output

    output_directory:: 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 continue executing from where it stopped (if it did not already reach the end). The "--use_latest_master_directory" option can be used to choose the most recent directory that starts with "master. The directory structure generated by sxrviper is shown in the figure below. Each "runXXX" directory contains the output of running the VIPER algorithm. It contains the reconstructed volume of stage1, refvolf2.hdf, and parameters into refparams2.txt. After stage 2, the final volume and parameters will be written to volf.hdf and params.txt. Other output files are log.txt and previousmax.txt. Each mainXXX directory contains the output of "n_v_runs" viper runs. The number of mainXXX directories is given by "n_rv_runs".

    tree.png

    Description

    • This program uses multiple VIPER runs to determine unstable projections, eliminate them and rerun again until all projections are stable. Since the VIPER program is used as a building block all requirements from VIPER must be satisfied. Attributes xform.projection have to be set in the header of each file. If their values are not known, all should be set to zero.
    • Determining whether projections are stable is done using one of the following criteria shown in the figures below.

    criterion01.png criterion02_1.png

    • The first criterion, called "80th percentile" (left image) is satisfied when the 80th percentile is less or equal to 20% of the maximum.
    • The second criterion, called "fastest increase in the last quartile" is satisfied when the last quartile has a length greater than 20% of the maximum.
    • If finishing criterion is not met after executing 10 VIPER runs, then the program stops.

    Example of RVIPER output

    In the example below, RVIPER found in the third iteration (main003) a set of 3 reconstructed volumes whose projections show stable angle assignment. The program generates "average_volume.hdf" and "variance_volume.hdf" based on the three reconstructed volumes.

    error_curve05.png

    Reference

    Penczek 1994, "The ribosome at improved resolution: new techniques for merging and orientation refinement in 3D cryo-electron microscopy of biological particles", Ultramicroscopy 53, 251-270.

    Author / Maintainer

    Pawel A. Penczek

    Keywords

    category 1
    APPLICATIONS
    category 3
    GRIDDING

    Files

    sparx/bin/sxviper.py

    See also

    sxlocal_ali3d

    Maturity

    beta
    works for author, often works for others.

    Bugs

    Did not discover any yet.

    sxrviper (last edited 2017-10-27 16:01:18 by penczek)