Differences between revisions 69 and 70
Revision 69 as of 2015-07-29 18:33:26
Size: 8926
Editor: penczek
Comment:
Revision 70 as of 2015-07-29 18:49:05
Size: 8926
Editor: penczek
Comment:
Deletions are marked like this. Additions are marked like this.
Line 67: Line 67:
 * Determining whether the "n_v_runs" reconstructed volumes in the current RVIPER iteration have a core set of stable projections is done using one of the following criteria shown in the figures below. The y axis represents the error angle. For example, if a projection has the following assigned angles in three different reconstructed volumes 30,45 and 55 then the error associated with this image is abs(30-45) + abs(30-55) + abs(45-55))/3 = 16.6 . The x axis represent the image index of the sorted array of error angles.  * Determining whether the "n_v_runs" reconstructed volumes in the current RVIPER iteration have a core set of stable projections is done using one of the following criteria shown in the figures below. The y axis represents the error angle. For example, if a projection has the following assigned angles in three different reconstructed volumes 30,45 and 55 then the error associated with this image is abs(30-45) + abs(30-55) + abs(45-55))/3 = 16.6. The x axis represents the image index of the sorted array of error angles.

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
    particle 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"
    angle_threshold
    angle error above which projections are removed every iteration (default=30)

    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 (please see sxviper). The "runXXX" directory 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 find unstable projections. Based on user chosen criterion it eliminates the unstable projections and reruns 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 the "n_v_runs" reconstructed volumes in the current RVIPER iteration have a core set of stable projections is done using one of the following criteria shown in the figures below. The y axis represents the error angle. For example, if a projection has the following assigned angles in three different reconstructed volumes 30,45 and 55 then the error associated with this image is abs(30-45) + abs(30-55) + abs(45-55))/3 = 16.6. The x axis represents the image index of the sorted array of error angles.

    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, (the criterion fails for all combinations of "n_v_runs"(default=3) taken by 10 (120 in total)) then the program stops.
    • Once a criterion is met, a decision is made regarding which images to keep. Currently there are three options implemented:
      1. percentile (all images (sorted by their angle error), below "outlier_percentile" given in the command line are kept for the next iteration)
      2. angle_measure (all images that have angle error below "angle_threshold" given in the command line are kept for the next iteration)
      3. discontinuity_in_derivative (as shown in the figure below, two lines (green and red) are fitted together while their common point moves along the x axis between 80th percentile and "outlier_percentile" (provided in the command line) against the error curve (blue). The point on the x coordinate where the projections of the best fit lines meet is chosen as the outlier index threshold. All images before it are kept for the next iteration.

    discontinuity.png

    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

    Horatiu Voicu, 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)