= Name =
sxrsort3d - 3D Clustering - RSORT3D: Sort out 3D heterogeneity of 2D data whose 3D reconstruction parameters (xform.projection) have been determined already using 3D sorting.

= Usage =


'' usage in command line''

sxrsort3d.py  stack  outdir  mask  --previous_run1=run1_directory   --previous_run2=run2_directory  --focus=3Dmask  --ir=inner_radius  --radius=outer_radius  --maxit=max_iter  --rs=ring_step  --xr=xr  --yr=yr  --ts=ts  --delta=angular_step  --an=angular_neighborhood  --center=centring_method  --nassign=nassign  --nrefine=nrefine  --CTF  --stoprnct=stop_percent  --sym=c1  --independent=indenpendent_runs  --number_of_images_per_group=number_of_images_per_group  --low_pass_filter=low_pass_filter  --nxinit=nxinit  --unaccounted  --function=user_function  --seed=random_seed  --smallest_group=smallest_group  --group_size_for_unaccounted=group_size_for_unaccounted  --sausage  --chunkdir=chunkdir  --PWadjustment=PWadjustment  --protein_shape=protein_shape  --upscale=upscale  --wn=wn --interpolation=method


=== Typical usage ===

sxrsort3d.py exists only in MPI version

''' mpirun -np 176 --host n1,n5,n6,n8,n9,n10,n0,n4,n3,n7 sxrsort3d.py bdb:data rsort3d mask.hdf --previous_run1=sort3d1 --previous_run2=sort3d2 --radius=88 --maxit=25 --independent=3 --CTF --number_of_images_per_group=11000 --low_pass_filter=.20 --chunkdir=./ --sym=c4 --PWadjustment=pwrec.txt ''' 

=== Time and Memory ===
On lonestar cluster of TACC, using 264 cpus, it takes about 2 hours and 23 minutes to accomplish 95953 128x128 images for one sxsort3d.py independent run, 2 hours 24 minutes to accomplish one independent sxrsort3d.py run with number_of_images_per_group set as 30000. 

== Input ==
    stack:: Input images stack: (default required string)
    mask:: 3D mask: (default none)
    
    focus:: Focus 3D mask: Mask used for focused clustering (default none)
    radius:: Outer radius for rotational correlation [Pixels]: Must be smaller than half the box size. Please set to the radius of the particle. (default -1)
    delta:: Angular step for projections: (default '2')
    CTF:: Use CTF: Do a full CTF correction during the alignment. (default False) 
    sym:: Point-group symmetry: (default c1) 
    number_of_images_per_group:: Images per group: Critical number of images per group, defined by user. (default 1000) 
    nxinit:: Initial image size for sorting: (default 64)
    smallest_group:: Smallest group size: Minimum members for identified group. (default 500) 
    previous_run1:: Directory of first sxsort3d.py run: (default required string)
    previous_run2:: Directory of second sxsort3d.py run: (default required string)
    chunkdir:: Chunkdir: Used for computing margin of error. (default none)

    * The remaining parameters are optional and default values are given in parenthesis. There is rarely any need to modify them.
    ir:: Inner radius for rotational correlation [Pixels]: Must be bigger than 1. (default 1)
    maxit:: Maximum iterations: (default 25)
    rs:: Step between rings in rotational correlation: Must be bigger than 0. (default 1)
    xr:: X search range [Pixels]: The translational search range in the x direction will take place in a +/xr range. (default 1)
    yr:: Y search range [Pixels]: The translational search range in the y direction. If omitted it will be set as xr. (default -1)
    ts:: Translational search step [Pixels]: The search will be performed in -xr, -xr+ts, 0, xr-ts, xr, can be fractional. (default 0.25)
    an:: Local angular search width [Degrees]: This defines the neighbourhood where the local angular search will be performed. (default '-1')
    center:: Centering method: 0 - if you do not want the volume to be centered, 1 - center the volume using the center of gravity. (default 0)
    nassign:: Number of reassignment iterations: Performed for each angular step. (default 1)
    nrefine:: Number of alignment iterations: Performed for each angular step. (default 0)
    stoprnct:: Assignment convergence threshold [%]: Used to asses convergence of the run. It is the minimum percentage of assignment change required to stop the run.  (default 3.0) 
    function:: Reference preparation function: Function used to prepare the reference volume. (default do_volume_mrk02) 
    independent:: Number of independent runs: Number of independent equal-Kmeans(default 3) 
    low_pass_filter:: Low-pass filter frequency [1/Pixel]: Low-pass filter used for the 3D sorting on the original image size. (default -1.0)
    unaccounted:: Reconstruct unaccounted images: (default False) 
    seed:: Seed: Seed used for the initial random assignment for EQ Kmeans. The program generates a random integer by default. (default -1) 
    group_size_for_unaccounted:: Unaccounted particles group size: (default none) 
    sausage:: Use sausage filter: (default False)
    PWadjustment:: Power spectrum reference: Text file containing a 1D reference power spectrum. (default none) 
    protein_shape:: Protein Shape: It defines protein preferred orientation angles. "g" is for globular proteins and "f" is for filament proteins. (default 'g')
    upscale:: Power spectrum adjustment strength: This parameters adjusts how strongly the power spectrum of the volume should be modified to match the reference. A value of 1 brings the volume's power spectrum completely to the reference, while a value of 0 means no modification.  (default 0.5) 
    wn:: Target image size [Pixels]: If different than 0, then the images will be rescaled to fit this size. (default 0) 
    interpolation:: 3D interpolation method: Method interpolation in 3D. Options are tr1 or 4nn. (default '4nn')

== Output ==
    outdir:: Output directory: There is a log.txt that describes the sequences of computations in the program. (default required string)


= Description =
sxrsort3d.py finds out stable members by carrying out two-way comparison of two independent sxsort3d.py runs.

For small tested datasets (real and simulated ribosome data around 10K particles), it gives 70%-90% reproducibility. However, this rate also depends on the choice of number of images per group and number of particles in the smallest group.

= Method =
K-means, equal K-means, reproducibility, two-way comparison.

= Reference =
Not published yet.

= Author / Maintainer =
Zhong Huang

= Keywords =
    category 1:: APPLICATIONS

= Files =
applications.py

= See also =

[[http://sparx-em.org/sparxwiki/sxsort3d|sxsort3d]]

= Maturity =

    stable while under development:: works for most people, has been tested; test cases/examples available.

= Bugs =
None.  It is perfect.
