#Sparse Ensemble Selection (SES)

Sparse Ensemble Selection (SES) method is a computational method for recovering multiple conformations from a limited number of observations. SES is more general and accurate than previously published minimum-ensemble methods is applicable to any experimental observables that can be expressed as a weighted linear combination of data for individual states.

Instructions on using SES:

• Make sure you have Java 1.7+ installed
• Download and place the sesgeneral.jar file into a directory
• Unzip the "lib" zip file, and place the lib directory in the same directory as the SES jar file
• Open command prompt (in Windows go to start/run and type "cmd")
• Switch into the directory where SES is unzipped
• Type "java -jar sesgeneral-1.1.jar -help", help should appear.

You will probably need to increase java memory size to about 90% of system memory using "-Xms" flag, in order to run for large number of K.

Program flags: <program name> <flag> [<value>] <flag> [<value>]
ARMOR Version: 1.1, Build Time: 06/24/2014 12:53 PM
    Boolean flags do not contain a value key.
    Flag options are as follows:
        -K, default = 100000
            Number of top solutions to store per iteration of M-OMP.
        -align, default = "CA"
            Name of the atom type (ex. H, CA, etc) to use for alignment and RMSD computation during postprocess clustering. Set to * for any
        -best, default = false
            Output the best possible x>0 (NNLS) solution.
        -data, *required, 
            Experimental data size filename.
        -help, default = true
            Displays the help menu.
        -l0max, default = 2147483647
            Maximum ensemble size to compute.
        -matrix, *required, 
            File name of the data matrix file.
        -maxsum, default = Infinity
            Maximum possible sum of the column weights.
        -out, default = "solution"
            Output directory file name.
        -outalign, default = 0
            Type of alignment for models inside the output pdb file. 0) no alignment 1) align based on whole struct. 2) Align by first chain.
        -pdb, default = ""
            Directory of PDB files. Ignore, if not pdb files available.
        -precond, default = 1
            Preconditioning of the linear system before M-OMP: 0) None, 1) Rotation and Compression (cutoff=reltol*0.1).
        -reltol, default = 5.0E-4
            M-OMP solvers relative  error tolerance for termination.
        -rmsd, default = 4.0
            Cluster RMSD value for solution pdb files (see align, outalign options).
        -storejava, default = false
            Output the java object with all results. Can be used for parsing using ARMOR API.
        -top, default = 0.005
            Max relative error of top solutions relative to input. All output solutions have abs. error <= best sol abs. error + top*||(input vector)./(error vector)||_2.

REFERENCES

If you use the software please cite:

K. Berlin, C. A. Castaneda, D. Schneidman-Duhovny, A. Sali, A. Nava-Tudela, and D. Fushman, “Recovering a representative conformational ensemble from underdetermined macromolecular structural data,” Journal of the American Chemical Society, vol. 135, no. 44, pp. 16595–16609, 2013.

Example

• Step 1: Make an Lx2 text matrix file of the experimental data, "y_data.txt". The first column is the data, the second column is the associated error. The columns are separated by spaces, and the rows by return character.
• Step 2: Make an LxN text matrix of predicted data, A_data.txt. The ith column represents the predicted data for the ith conformer.
• Step 3: Make the directory "outputdir".
• Step 4: Run SES: java -Xmx<memory size> -jar sesgeneral-1.1.jar -out "outputdir" -matrix "A_data.txt" -data "y_data.txt"

Here <memory size> is the RAM memory size that you want to use for the Java virtual machine. Ex. -Xmx10g if you would like to give 10 GB of RAM to Java.

If you want to see more options, use the -help flag

java -jar sesgeneral-1.1.jar -help