SIMPLE banner

Manuals for SIMPLE 2.1

simple2.1manual.pdf

command_line_dictionary.pdf

File formats

SIMPLE 2.1 supports both SPIDER (*.spi) and MRC (*.mrc) formats for image stacks and volumes. The MRC file handling classes are shared with the Frealix program for helical reconstruction. Relion uses the convention that MRC stacks have the suffix *.mrcs and volumes the suffix *.mrc. This is to overcome the annoyance that it is not possible to tell from an MRC file header whether a MRC file is a volume or a stack. With SIMPLE you can select to use either the *.mrcs or *.mrc suffix for stacks. The way that we keep track of whether a file is a volume or stack is via the command line key value. The key value pairs vol1=rec.mrc and vol2=rec2.mrc refer to volumes whereas the key value pairs stk=ptcls.mrc and stk2=ptcls2.mrc refer to stacks. Another notable change is the text file format used to write per-particle information to disk. The SIMPLE text files used for parameter input/output now use a key=value syntax of the form

    e1=80. e2=100. e3=5.5 x=1.23 y=4.25 dfx=2.56 dfy=2.54 angast=30.5 state=1
to represent per-particle information. Internally, the orientation information is stored in a dynamic hash data structure, which gives the file format high flexibility. Therefore, writing conversion scripts to allow interchange of parameters between SIMPLE and other packages is trivial. SIMPLE uses the same conventions as Frealign to represent orientations and CTF parameters. The CTF parameterization obtained by CTFFIND can be directly plugged into SIMPLE, for example by creating a file deftab.txt, looking like:
    dfx=2.56 dfy=2.76 angast=30.5
    dfx=3.50 dfy=3.33 angast=60.0
    dfx=1.98 dfy=2.02 angast=120.5
    ...
and adding deftab=deftab.txt and ctf=yes to the PRIME command line (if the images are phase-flipped, this should be indicated by ctf=flip). The SIMPLE/scripts folder contains a perl script (convert_frealign2simple.pl) to convert a Frealign parameter file to a SIMPLE parameter file. This is easy, since both software internally use the SPIDER Euler angle convention. Other packages may use other conventions.

   Installation

System requirements

Hardware

    CPU
  • Linux (fully supported Debian-based distributions: Mint-17.1, Ubuntu (14.10, 15.04, 15.10, 16.04 LTS)), SUSE-13.2 (earlier SUSE versions are also supported but not tested)
  • MacOSX (Yosemite and El Capitan, i.e. 10.10 and above)

Sofware
    CPU
  • GNU tool chain 4.9 and above
  • The linear algebra packages: Lapack and BLAS
  • FFTW-3 (The Fastest Fourier Transform in the West library)

Compiling from source on a Linux PC

Here we will compile SIMPLE2.1 from source on a Linux PC. The manual states that SIMPLE2.1 requires the GNU toolchain version 4.9.1 or later (see above). Although SIMPLE supports all newer versions of the GNU toolchain, it is safest to use version 4.9.X because later versions are currently incompatible with the CUDA7 compiler. GPU accelerated code is planned for SIMPLE v3 and it may not be supported unless 4.9.X is used. To check the compiler versions, we execute

    $ gfortran --version
    GNU Fortran (GCC) 4.9.1
    Copyright (C) 2014 Free Software Foundation, Inc.
To confirm that the gcc and g++ compilers are of the same version, we execute
    $ gcc --version
    gcc (GCC) 4.9.1
    Copyright (C) 2014 Free Software Foundation, Inc.
    This is free software; see the source for copying conditions.  There is NO
    warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    $ g++ --version
    g++ (GCC) 4.9.1
    Copyright (C) 2014 Free Software Foundation, Inc.
    This is free software; see the source for copying conditions.  There is NO
    warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
To check whether lapack is installed, we open the package manager installed on our system (in our case Synaptic but other systems may have others, such as YaST, apt etc.) and search for lapack and conclude that liblapack3 is installed on the system. We also search for fftw and conclude that the libfftw3-single-3 is installed on the system. We cd to the directory where we have our software installed (<my software location>) and copy the tar ball there
    $ cd <my software location>
    $ cp ~/Downloads/simple2.1.tar.gz .
Next, we unpack the tar ball and cd to the simple directory
    $ gunzip simple2.1.tar.gz
    $ tar -xvf simple2.1.tar
    $ cd simple2.1/
To check which Linux distribution we are running, we execute
    $ lsb_release -a
    No LSB modules are available.
    Distributor ID: Ubuntu
    Description:    Ubuntu 15.10
    Release:    15.10
    Codename:   wily
Now we try to identify the configuration template file most suitable for our system by executing
    $ ls -1 scripts/Template_*
    scripts/Template_FEDORA_21x64_CPU_simple_user_input.pm
    scripts/Template_MacOSX_10.9.5x64_CPU_simple_user_input.pm
    scripts/Template_MacOSXFINK_10.11.4x64_CPU_simple_user_input.pm
    scripts/Template_MASSIVE_CPU_simple_user_input.pm
    scripts/Template_Mint_17.1x64_CPU_simple_user_input.pm
    scripts/Template_OXFORD_CPU_simple_user_input.pm
    scripts/Template_SUSE_13.2x64_CPU_simple_user_input.pm
    scripts/Template_Ubuntu_14.10x64_CPU_simple_user_input.pm
    scripts/Template_Ubuntu_15.10x64_CPU_simple_user_input.pm
    scripts/Template_Ubuntu_16.XXx64_CPU_simple_user_input.pm

For this system, it looks like the Template_Ubuntu_15.10x64_CPU_simple_user_input.pm is the best fit, so we copy it to the root of the SIMPLE directory and rename it by executing

    $ cp ./scripts/Template_Ubuntu_15.10x64_CPU_simple_user_input.pm
    simple_user_input.pm

We open the simple_user_input.pm file in our favourite text editor (vim) and replace on line 30 our$SIMPLE_PATH "/mysimplepath/"
with
our$SIMPLE_PATH "/mysoftwarelocation/simple2.1/"
This is the path in which the software will be installed. We close vim and execute

    $ ./Makefile_genAll.pl
    SIMPLE library has finished compilation in dir:
    /mysoftwarelocation/simple2.1/
    *********************************************************
    * Compilation and linkage is complete for Simple-v2.1   *
    * You may run all simple checks  --- List check options *
    * > make check                   --- > make check_help  *
    *                                --- > make check_cpu   *
    * Cleaners: --- > make {clean,cleanall,clean_check_cpu} *
    * New Rel.: --- > make checknews                        *
    * Lne Cntr: --- > make wc                               *
    *********************************************************

Compilation was succesful and we see that a new directory /bin has been created in the simple directory in addition to two text files add2.bashrc and add2.tcshrc

    $ cat add2.bashrc
    export SIMPLEPATH=/mysoftwarelocation/simple2.1/
    export PATH=${SIMPLEPATH}/scripts:${SIMPLEPATH}/$PATH
    $ cat add2.tcshrc
    setenv SIMPLEPATH /mysoftwarelocation/simple2.1/
    set path=(${SIMPLEPATH}/scripts ${SIMPLEPATH}/bin $path)

On this machine we use the bash shell, so we add the lines in add2.bashrc to the .bashrc file and when a new terminal window is opened we have access to all the simple_* programs.

Compiling from source on MacOSX

This procedure is virtually identical to the one described for Linux above but we need to select the correct configuration file. If the fink package manager was used to install the GNU toolchain and the FFTW library, try the configuration file:

    scripts/Template_MacOSXFINK_10.11.4x64_CPU_simple_user_input.pm
Otherwise, try the file:
    scripts/Template_MacOSX_10.9.5x64_CPU_simple_user_input.pm
Compilation troubleshooting

FFTW

If not installed, the FFTW-3 library needs to be installed. Most Linux package managers YaST, Synaptic, apt-get etc. provide the FFTW-3 library. On a Mac system the Fink and Macports package managers provide the FFTW-3 library or it can be obtained from: http://www.fftw.org/install/mac.html. SIMPLE relies on the single-precision FFTW library. Typically we will need to

    $ ./configure --enable-floats
    $ make
    $ sudo make install

The -enable floats directive is critical as the installer will otherwise only install the double-precision version of the library. We check that we have in the lib folder (typically: /usr/local/lib/):

    libfftw3.a libfftw3.la
    libfftw3f.a libfftw3f.la

Similarly the lapack3 and BLAS will need to be installed on the system. On MacOSX Lapack and BLAS are usually installed by default. Installation of the dependencies on a PC with a Debian operating system, such as Ubuntu or Mint, is done using the apt-get install command as a super user

    #the compilers
    $ sudo apt-get install gfortran gfortran-4.9 gcc-4.9 g++-4.9
    #libraries (Lapack and BLAS)
    $ sudo apt-get install scalapack-doc scalapack-mpi-test
    scalapack-pvm-test scalapack-test-common  libscalapack-pvm1
    libscalapack-pvm-dev libscalapack-openmpi1 libopenblas-base
    libopenblas-dev libmlpack-dev libblas-dev libblas3 liblapack-dev
    liblapack-doc liblapack-doc-man liblapack3 libopenmpi-dev
    libmeep-mpich2-dev
    #FFTW-3
    $ sudo apt-get install libfftw3-bin libfftw3-dbg libfftw3-dev
    libfftw3-doc libfftw3-double3 libfftw3-long3 libfftw3-quad3
    libfftw3-single3 cl-fftw3 fftw-dev fftw-docs libfftw3-3
    libfftw3-mpi-dev libfftw3-mpi3

Compilers

One possible cause of failing compilation may be that the compiler paths are not correctly set in the simple_user_input.pm file. A typical configuration on Ubuntu looks like

    our$CC_COMPILER = "gcc-4.9";
    our$GCC_COMPILER = "g++-4.9";
    our$MPI_F_COMPILER = "/usr/bin/mpif90";
    our$FCOMPILER = "gfortran-4.9";

A configuration on MacOSX could look like

    our$CC_COMPILER = "/usr/local/bin/gcc";
    our$GCC_COMPILER = "/usr/local/bin/g++";
    our$MPI_F_COMPILER = "/usr/local/bin/mpif90";
    our$FCOMPILER = "/usr/local/bin/gfortran";

If we used the Fink package manager to install the GNU toolchain on MacOSX, the configuration will typically look like:

    our$CC_COMPILER = "/sw/bin/gcc-fsf-5";
    our$GCC_COMPILER = "/sw/bin/g++-fsf-5";
    our$MPI_F_COMPILER = "/sw/bin/mpif90";
    our$FCOMPILER = "/sw/bin/gfortran";

If we are on MacOSX and used the MacPorts package manager to install the GNU toolchain, the configuration will typically look like:

    our$CC_COMPILER = "/opt/local/bin/gcc";
    our$GCC_COMPILER = "/opt/local/bin/g++";
    our$MPI_F_COMPILER = "/opt/local/bin/mpif90";
    our$FCOMPILER = "/opt/local/bin/gfortran";

On MacOSX it is required that the correct Command Line Tools for Xcode are installed. If we use the package managers Fink or MacPorts this is taken care of as part of the installation procedure. The gfortran-5, gcc-5 and g++-5 compilers can be installed via the apt-get, Synaptic or YaST package managers on Linux systems. Beware that Apple have their own gcc compiler (for objective-C) which is different than the GNU one and will generate errors upon compilation.

    $ gcc --version 
    Configured with: --prefix=/Applications/Xcode.app/Contents/Developer/usr
    --with-gxx-include-dir=/usr/include/c++/4.2.1
    Apple LLVM version 6.0 (clang-600.0.54) (based on LLVM 3.5svn)
    Target: x86_64-apple-darwin13.4.0
    Thread model: posix

The compilation needs to be using the GNU compiler and not the Apple one. Otherwise the compilation will not work. Make sure that the paths in simple_user_input.pm are pointing to the correct location

    $SIMPLE_PATH= {path where simple will be installed}
    $CC_COMPILER = {path to the gcc compiler on MacOSX,
                     default: /usr/local/bin/gcc}
    $GCC_COMPILER = {path to the g++ compiler on MacOSX,
                     default: /usr/local/bin/g++}
    $MPI_F_COMPILER = {path to the mpif90 compiler on MacOSX, 
                       default:/usr/local/bin/mpif90}
    $FCOMPILER = {path to the gfortran or ifort compiler on MacOSX,
                   default: /usr/local/bin/gfortran}

    $MPI_DIR={path to the mpi directory, default:/usr}
    $MPI_DIR_INCLUDE="/usr/include/mpi";
    $FFTW_LIB={path for to the FFTW lib, default: /usr/local/lib}
    $FFTW_INC={path to the include for the FFTW, default:
    /usr/local/fftw/3.3.4-gcc/include/} cluster dependent

    $OBJDIR={path to the object compiled files, default: obj/GFORTgpu}
    $MODDIR={path to the .mod files, default: obj/GFORTgpu}
All of the compilers must originate from the same version of the GNU toolchain.


Installation on a Linux cluster

Installation on a Linux cluster is essentially the same as on a Linux workstation with the exception that the appropriate modules need to be loaded before installation and execution. On a typical SLURM cluster

    $ module load fftw/3.3.4-gcc
    $ module load gcc/4.9.1
    $ module load lapack/3.4.2

The instructions for how to execute SIMPLE in distributed environments (clusters or workstations with more than one CPU socket) are described here.

Pre-compiled binaries for MacOSX

We also provide a script for automatic installation of pre-compiled binaries on MacOSX. Download the tar ball and untar it in the directory of your choice

    $ tar -xvzf Install_Simple_MacOSX_binaries.tar.gz
Change directory
    $ cd <path to>/Install_Simple_MacOSX_binaries
This installation route requires administration rights, since the script will install GNU compilers version 4.9 and the FFTW library (v3.4.4) in /usr/local/bin and /usr/local/lib respectively. Don't use this script if you have other GNU compiler versions installed in these folders that you do not wish to have overwritten. To proceed with the installation specify the absolute path of the target location for the installation.
    $ sudo csh install_MacOSX_binaries_prod.csh /Users/<username>/Simple
Enter your admin user password and wait. This may take a while because the fftw-3.4.4 library needs to be compiled for the most commonly used precisions. The scripts installs and checks for the correctness of the installed compilers (i.e. gcc, g++ and gfortran) in the /usr/local/bin folder. It should look like
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-                       Checking installation ...                       -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-                                                                       -
-                      fftw-3.3.4 library ...                           -
-                                                                       -
libfftw3.a	    libfftw3f.a	         libfftw3l.a	      libfftw3q.a
libfftw3.la	    libfftw3f.la	 libfftw3l.la	      libfftw3q.la
libfftw3_omp.a	    libfftw3f_omp.a	 libfftw3l_omp.a      libfftw3q_omp.a
libfftw3_omp.la	    libfftw3f_omp.la     libfftw3l_omp.la     libfftw3q_omp.la
libfftw3_threads.a  libfftw3f_threads.a  libfftw3l_threads.a  libfftw3q_threads.a
libfftw3_threads.la libfftw3f_threads.la libfftw3l_threads.la libfftw3q_threads.la
-                                                                       -
-    GNU compilers /usr/local/bin/{gcc-4.9,g++-4.9, gfortran-4.9} ...   -
-                                                                       -
g++	gcc	gfortran {... plus other files ...}

gcc (GCC) 4.9.2 20141029 (prerelease)
Copyright (C) 2014 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

g++ (GCC) 4.9.2 20141029 (prerelease)
Copyright (C) 2014 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

GNU Fortran (GCC) 4.9.2 20141029 (prerelease)
Copyright (C) 2014 Free Software Foundation, Inc.

GNU Fortran comes with NO WARRANTY, to the extent permitted by law.
You may redistribute copies of GNU Fortran
under the terms of the GNU General Public License.
For more information about these matters, see the file named COPYING
A successful completion of script provides the final steps for successful installation and should show:
    ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !
    !                                                                       !
    !            You now need to add the environment variable in            !
    !                your ~/.bashrc or shell rc:                            !
    !                                                                       !
                                 in bash                                     
    export SIMPLEPATH=/Users/<username>/Simple/MacOSX_binaries 
    export PATH=${SIMPLEPATH}/scripts:${SIMPLEPATH}/bin:$PATH        
                                                                                                                 
                         in shell or cshell or tshell                        
                                           
    setenv SIMPLEPATH /Users/<username>/Simple/MacOSX_binaries
    set path=(${SIMPLEPATH}/scripts ${SIMPLEPATH}/bin $path)
    !                                                                       !
        Check ownership of installation path: /Users/<username>/Simple                   
             if it has root and not <username> then change it by:                 
    !                                                                       !
                    sudo chown -R <username> /Users/<username>/Simple                         
    !                                                                       !
    !          You may now start using SIMPLE from command line             !
          and go to: /Users/<username>/Simple/MacOSX_binaries                            
    !                       to launch the checks                             
    !                                                                       !
                            csh launch_checks.csh                            
    !                                                                       !
    ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !
To check the owner ship of the target location
    $ ls -al /Users/<username>/Simple
    total 0
    drwxr-xr-x   3 root       staff  102 20 May 12:48 .
    drwxr-xr-x+ 26 <username> staff  884 20 May 13:36 ..
    drwxr-xr-x   7 root       staff  238 20 May 14:03 MacOSX_binaries
We recommend changing ownership to <username> via
    $ sudo chown -R <username> /Users/<username>/Simple
and to confirm that the rights were changed, execute
    $ ls -al /Users/<username>/Simple
    total 0
    drwxr-xr-x   3 <username> staff  102 20 May 12:48 .
    drwxr-xr-x+ 26 <username> staff  884 20 May 13:36 ..
    drwxr-xr-x   7 <username> staff  238 20 May 14:03 MacOSX_binaries
Lastly, we need to add a few paths to our shell environment. This enables running simple commands from the prompt anywhere in the user directory structure and. If you are using the bash shell, add to your .bashrc
    export SIMPLEPATH=/Users/<username>/Simple/MacOSX_binaries
    export PATH=${SIMPLEPATH}/scripts:${SIMPLEPATH}/bin:$PATH
and if you are using the c-shell or the tc-shell, add to your .cshrc or .tcshrc
    setenv SIMPLEPATH /Users/<username>/Simple/MacOSX_binaries
    set path=(${SIMPLEPATH}/scripts ${SIMPLEPATH}/bin $path)
Do not forget to source the environment by typing
    #for bash
    $ source ~/.bashrc
    #for cshell
    $ source ~/.cshrc
Once this is done, launch the checks in /Simple/MacOSX_binaries:
    $ cd /Users//Simple/MacOSX_binaries
    $ csh launch_checks.csh
If the checks passes the installation is complete.

   2D alignment/clustering

simple_prime2D_init

simple_prime2D_init is a program for initialising prime2D. We use it to produce the initial random references when executing simple_prime2D in distributed mode using distr_simple.pl.

Usage:
>>>simple_prime2D_init stk=<stack.ext> smpd=<sampling distance(in A)> msk=<mask radius(in pixels)> ncls=<nr of clusters> [nthr=<nr of OpenMP threads{1}>] [oritab=<input doc>]

Comments:
The program assumes that the images have been phase-flipped, as no CTF correction by Wiener restoration is implemented yet. The random clustering and in-plane alignment will be printed in the file prime2D_startdoc.txt produced by the program. This file is used together with the initial references (startcavgsmsk.ext) to execute PRIME2D in distributed mode by distr_simple.pl.

simple_prime2D

simple_prime2D is a reference-free 2D alignment/clustering algorithm adopted from the prime3D probabilistic ab initio 3D reconstruction algorithm. It is assumed that the images are phase-flipped (phase flipping can be done with simple_stackops). Do not search the origin shifts initially, when the cluster centers are of low quality. If your images are far off centre, use simple_stackops with option shalgn=yes instead to shiftalign the images beforehand (the algorithm implemented is the same as EMAN's cenalignint program). Use distr_simple.pl for distributed PRIME2D execution.

Usage:
>>>simple_prime2D stk=<stack.ext> smpd=<sampling distance(in A)> msk=<mask radius(in pixels)> ncls=<nr of clusters> refs=<initial_references.ext> oritab=<previous clustering doc> [lp=<low-pass limit(in A){20}>] [trs=<origin shift(in pixels){0}>] [nthr=<nr of OpenMP threads{1}>] [startit=<start iteration>] [hp=<high-pass limit(in A)>] [srch_inpl=<yes|no{yes}>]
** less commonly used** [maxits=<max iterations{500}>] [inner=<inner mask radius(in pixels)>] [width=<pixels falloff inner mask(in pixels){10}>]

simple_rank_cavgs

simple_rank_cavgs is a program for ranking class averages by decreasing population, given the stack of class averages (stk argument) and the 2D orientations document (oritab) generated by simple_prime2D.

Usage:
>>>simple_rank_cavgs stk=<cavgs.ext> oritab=<2D clustering doc> [outstk=<ranked cavgs stack>]

simple_map2ptcls

simple_map2ptcls is a program for mapping parameters that have been obtained using class averages to the individual particle images. There are many functionalities present that will become critical in future releases. Right now we recommend using this program exclusively to exclude the particles corresponding to deselected class averages. See the workflows section of the manual for further info.

Usage:
>>>simple_map2ptcls stk=<particles.ext> stk2=<selected_cavgs.ext> stk3=<orig_cavgs.ext> oritab=<PRIME 2D doc> [oritab2=<prime3D shc doc>] [comlindoc=<shc_clustering_nclsX.txt>] [doclist=<list of oritabs for the different states>] [deftab=<text file defocus values>] [outfile=<output parameter file{mapped_ptcls_params.txt}>] [nthr=<nr of OpenMP threads{1}>]

simple_doc2cavgs

simple_doc2cavgs is a program for generating class averages. We use it to to re-generate class averages when simple_prime2D has been run on downscaled images. If the images processed with PRIME2D were downscaled from 200x200 to 100x00, set mul=2.

Usage:
>>>simple_doc2cavgs stk=<stack.ext> smpd=<sampling distance(in A)> msk=<mask radius(in pixels)> ncls=<nr of clusters> oritab=<previous clustering doc> which_iter=<iteration nr> [mul=<shift multiplication factor{1}>] [nthr=<nr of OpenMP threads{1}>]

Comments:
The program assumes that the images have been phase-flipped, as no CTF correction by Wiener restoration is implemented yet.

   Ab initio 3D reconstruction

simple_resrange

simple_resrange is a program for estimating the resolution range used in the heuristic resolution-stepping scheme in the PRIME3D initial model production procedure. The initial low-pass limit is set so that each image receives ten nonzero orientation weights. When quasi-convergence has been reached, the limit is updated one Fourier index at the time, until PRIME reaches the condition where six nonzero orientation weights are assigned to each image. FSC-based filtering is unfortunately not possible to do in the ab initio reconstruction step, because when the orientations are mostly random, the FSC overestimates the resolution. This program is used internally by distr_simple.pl when executing PRIME in distributed mode. We advise you to check the starting and stopping low-pass limits before executing PRIME3D using this program.

Usage:
>>>simple_resrange smpd=<sampling distance(in A)> [nspace=<nr of reference sections{1000}>] [pgrp=<cn|dn|t|o|i{c1}>] [box=<image size(in pixels)>] [moldiam=<molecular diameter(in A))>]

Comments:
The resolution range estimate depends on the molecular diameter, which is estimated based on the box size. If you want to override this estimate, set moldiam to the desired value (in A). This may be necessary if your images have a lot of background "padding". However, for starting model generation it is probably better to clip the images snugly around the particle, because smaller images equal less computation.

simple_prime3D_init

simple_prime3D_init is a program for generating a random initial model for initialisation of PRIME3D when executed in distributed mode. It is assumed that the images have been phase flipped. If the data set is large (>5000 images), generating a random model can be quite slow. To speedup, set nran to some smaller number, resulting in nran images selected randomly for reconstruction.

Usage:
>>>simple_prime3D_init stk=<stack.ext> smpd=<sampling distance(in A)> msk=<mask radius(in pixels)> [nspace=<nr reference sections{1000}>] [nran=<size of random sample>] [lp=<low-pass limit(in A)>] [nthr=<nr OpenMP threads{1}>]
** less commonly used** [pgrp=<cn|dn|t|o|i{c1}>] [npeaks=<nr nonzero orientation weights{1}>] [ctf=<yes|no|flip|mul{no}>] [kv=<acceleration voltage(in kV){300.}>] [fraca=<frac amp contrast{0.07}>] [cs=<spherical aberration constant(in mm){2.7}>] [deftab=<text file with defocus values>] [inner=<inner mask radius(in pixels)>] [width=<pixels falloff inner mask{10}>] [xfel=<yes|no{no}>]

simple_prime3D

simple_prime3D is an ab inito reconstruction/refinement program based on probabilistic projection matching. PRIME is shorthand for PRobabilistic Initial 3D Model Generation for Single-Particle Cryo-Electron Microscopy. You should use phase-flipped images for initial model production with PRIME3D (phase flipping can be done with simple_stackops). Do not search the origin shifts initially, when the model is of very low quality. If your images are far off centre, use simple_stackops with option shalgn=yes instead to shiftalign the images beforehand (the algorithm implemented is the same as EMAN's cenalignint program). We recommend running the first round of PRIME with the default dynamic resolution stepping dynlp=yes. The dynlp option implements a heuristic resolution weighting/update scheme. The initial low-pass limit is set so that each image receives ten nonzero orientation weights. When quasi-convergence has been reached, the limit is updated one Fourier index at the time until PRIME reaches the condition where six nonzero orientation weights are assigned to each image. FSC-based filtering is unfortunately not possible to do in the ab initio reconstruction step, because when the orientations are mostly random, the FSC overestimates the resolution. Once the initial model has converged, we recommend start searching the shifts (by setting trs to some nonzero value), applying the FSC for resolution-weighting (by setting eo=yes). You should NOT give ctf=flip on the command line unless the model has converged. Giving ctf=flip on the command lines signal to PRIME that tou have obtain a reconstruction of decent resolution and you want to take it further by applying Wiener restoration by resolution-weighting the reocnstructed volume more accurately. In order to be able to use Wiener restoration you also need to input CTF parameters, for example via deftab=defocus_values.txt. Remember that the defocus values should be given in microns and the astigmatism angle in degrees (one row of the file defocus_values.txt may look like: dfx=3.5 dfy=3.3 angast=20.0).

Usage:
>>>simple_prime3D stk=<stack.ext> vol1=<invol.ext> [vol2=<refvol_2.ext> etc.] smpd=<sampling distance(in A)> msk=<mask radius(in pixels)> [oritab=<previous alignment doc>] [trs=<origin shift(in pixels){0}>] [lp=<low-pass limit{20}>] [dynlp=<yes|no{yes}>] [nstates=<nstates to reconstruct>] [frac=<fraction of ptcls to include{1}>] [mw=<molecular weight(in kD)>] [nthr=<nr of OpenMP threads{1}>] [startit=<start iteration>] [refine=<no|shc|neigh|shcneigh{no}>] [lpstop=<stay at this low-pass limit (in A)>] [deftab=<text file defocus values>] [nspace=<nr reference sections{1000}>] [eo=<yes|no{no}>] [amsklp=<automask low-pass limit(in A)>] [pgrp=<cn|dn|t|o|i{c1}>] [ctf=<yes|no|flip|mul{no}>] [kv=<acceleration voltage(in kV){300.}>] [cs=<spherical aberration constant(in mm){2.7}>] [fraca=<frac amp contrast{0.07}>] [hp=<high-pass limit(in A)>] [diversify=<yes|no{yes}>] [xfel=<yes|no{no}>]
** less commonly used** [maxits=<max iterations{100}>] [edge=<edge size for softening molecular envelope(in pixels){3}>] [noise=<yes|no{no}>] [npeaks=<number of nonzero orientation weights>] [dens=<density(e.g. 9.368 Da/A3 4 gold clusters){0.}>] [nvox=<nr of voxels in mask{0}>] [inner=<inner mask radius(in pixels)>] [width=<pixels falloff inner mask{10}>]

Comments:
Note that we do not assume any point-group symmetry in the initial runs. However, the simple_symsrch program can be used to align the reconstruction to its symmetry axis so that future searches can be restricted to the asymmetric unit in refinement. Less commonly used and less obvious input parameters are nspace, which controls the number of reference projections, amsklp, which controls the low-pass limit used in the automask routine, maxits, which controls the maximum number of iterations executed, pgrp, which controls the point-group symmetry, assuming that the starting volume is aligned to its principal symmetry axis, edge, which controls the size of the softening edge in the automask routine.

simple_symsrch

simple_symsrch is a program for searching for the principal symmetry axis of a volume reconstructed without assuming any point-group symmetry. Our philosophy is to start off without assuming any symmetry, and then analyzse the reconstructed volume to identify the correct point-group symmetry. simple_symsrch can be used for this purpose. The program takes as input the asymmetrical reconstruction (obtained with simple_prime3D), the alignment document for all the particle images that have gone into the reconstruction, and the desired point-group symmetry. It then projects the reconstruction in 20 (default option) even directions, uses common lines-based optimisation to identify the principal symmetry axis, applies the rotational transformation to the inputted orientations, and produces a new alignment document. Input this document to simple_recvol or simple_eo_recvol together with the images and the point-group symmetry to generate a symmetrised map. If you are unsure about the point-group, you should of course test many different point-groups and compare the asymmetric map with the symmetrised maps. SIMPLE now implements most point-groups: c- and d-groups, as well as tetrahedral, octahedral, and icosahedral groups.

Usage:
>>>simple_symsrch vol1=<vol.ext> smpd=<sampling distance(in A)> oritab=<input alignment doc> pgrp=<cn|dn|t|o|i{c1}> outfile=<output alignment doc> lp=<low-pass limit(in A)> [amsklp=<low-pass limit for centering mask(in A){50}>] [hp=<high-pass limit(in A)>] [nthr=<nr openMP threads{1}>] [nspace=<nr of projs{20}>]

Comments:
The state parameter allows you to apply symmetry for the given state.

simple_recvol

simple_recvol is a program for reconstructing volumes from MRC and SPIDER stacks, given input orientations and state assignments (obtained by program simple_prime3D). The algorithm is based on direct Fourier inversion with a Kaiser-Bessel (KB) interpolation kernel. This window function reduces the real-space ripple artifacts associated with direct moving windowed-sinc interpolation. The feature sought when implementing this algorithm was to enable quick, reliable reconstruction from aligned individual particle images.

Usage:
>>>simple_recvol stk=<ptcls.ext> smpd=<sampling distance(in A)> oritab=<algndoc.txt> msk=<mask radius(in pixels)> [lp=<low-pass limit{20}>] [frac=<fraction of ptcls to include{1.}>] [nthr=<nr of openMP threads{1}>] [pgrp=<cn|dn|t|o|i{c1}>]
** less commonly used** [mw=<molecular weight(in kD)>] [amsklp=<low-pass limit(in A){20}>] [mul=<shift multiplication factor{1}>] [ctf=<yes|no|flip|mul{no}>] [kv=<acceleration voltage(in kV){300.}>] [fraca=<frac amp contrast{0.07}>] [cs=<spherical aberration constant(in mm){2.7}>] [deftab=<text file defocus values>] [state=<state to reconstruct{all}>] [edge=<edge size for softening molecular envelope(in pixels){3}>] [dens=<density(e.g.9.368 Da/A3 4 gold clusters){0.}>] [inner=<inner mask radius(in pixels)>] [width=<pixels falloff inner mask{10}>] [mirr=<yes|no{no}>] [even=<yes|no{no}>] [odd=<yes|no{no}>]

Comments:
mul is used to scale the origin shifts if down-sampled were used for alignment and the original images are used for reconstruction. This program can be run in distributed mode using distr_simple.pl. ctf, kv, fraca, cs and deftab are used to communicate CTF information to the program. ctf=yes, ctf=flip or ctf=mul turns on the Wiener restoration. If the images were pre-multiplied with CTF set ctf=mul or if the images were phase-flipped set ctf=flip. amsklp, mw, and edge are parameters that control the solvent mask: the low-pass limit used to generate the envelope; the molecular weight of the molecule (protein assumed but it works reasonably well also for RNA; slight modification of mw might be needed). The inner parameter controls the radius of the soft-edged mask used to remove the unordered DNA/RNA core of spherical icosahedral viruses. The even and odd parameters allow you to reconstruct either the even or the odd pair.

simple_eo_recvol

simple_eo_recvol is a program for reconstructing volumes from MRC or SPIDER stacks, given input orientations and state assignments (obtained by program simple_prime3D). The algorithm is based on direct Fourier inversion with a Kaiser-Bessel (KB) interpolation kernel. This window function reduces the real-space ripple artefacts associated with direct moving windowed-sinc interpolation. The feature sought when implementing this algorithm was to enable quick, reliable reconstruction from aligned individual particle images. The even and odd pairs are automatically reconstructed, the FSC calculated, and the Wiener filter formalism used for image restoration (CTF correction). Use distr_simple.pl for distributed execution.

Usage:
>>>simple_eo_recvol stk=<ptcls.ext> msk=<mask radius(in pixels)> smpd=<sampling distance(in A)> oritab=<algndoc.txt> [frac=<fraction ptcls to include{1.}>] [nthr=<nr openMP threads{1}>] [pgrp=<cn|dn|t|o|i{c1}>]
** less commonly used** [mul=<shift multiplication factor{1}>] [ctf=<yes|no|flip|mul{no}>] [kv=<acceleration voltage(in kV){300.}>] [fraca=<frac amp contrast{0.07}>] [cs=<spherical aberration constant(in mm){2.7}>] [deftab=<text file defocus values>] [state=<state to reconstruct{all}>] [mw=<molecular weight(in kD)>] [amsklp=<low-pass limit(in A){20}>] [edge=<edge size softening molecular envelope(in pixels){3}>] [inner=<inner mask radius(in pixels)>] [width=<pixels falloff inner mask{10}>]

Comments:
mul is used to scale the origin shifts if down-sampled images were used for alignment and the original images are used for reconstruction. ctf, kv, fraca, cs and deftab are used to communicate CTF information to the program. ctf=yes, ctf=flip or ctf=mul turns on the Wiener restoration. If you input CTF info to the program, please ensure that the correct kV, Cs and fraca (fraction of amplitude contrast) parameters are inputted as well. If the images were pre-multiplied with the CTF, set ctf=mul or if the images were phase-flipped set ctf=flip. amsklp and mw parameters control the solvent mask: the low-pass limit used to generate the envelope; the molecular weight of the molecule (protein assumed but it works reasonably well also for RNA; slight modification of mw might be needed). The inner parameter controls the radius of the soft-edged mask used to remove the unordered DNA/RNA core of spherical icosahedral viruses.

   Standard image/volume operations (ops)

simple_automask

simple_automask is a program for solvent flattening of a volume (MRC or SPIDER). The algorithm for background removal is based on low-pass filtering and binarization. First, the volume is low-pass filtered to amsklp. A binary volume is then generated by assigning foreground pixels (=1) based on the volume calculated from the molecular weight, assuming a protein density of 1.43 g/mL. A real-space low-pass filter softens the edge of the resulting binary volume before multiplying it with the unmasked input volume to generate the flattened map.

Usage:
>>>simple_automask vol1=<invol.ext> [vol2=<invol2.ext> etc.] smpd=<sampling distance(in A)> [mw=<molecular weight(in kD)>] [amsklp=<low-pass limit(in A){20}>] [nthr=<nr of OpenMP threads{1}>]
** less commonly used** [edge=<edge size for softening molecular envelope(in pixels){3}>]

simple_converter

simple_converter is a program for converting between SPIDER and MRC formats.

Usage:
>>>simple_converter [stk=<input particle stack>] [vol1=<invol.ext>] [outstk=<output particle stack>] [outvol=<outvol.ext>]

simple_iminfo

simple_iminfo is a program for printing header information in MRC and SPIDER stacks and volumes

Usage:
>>>simple_iminfo [fname=<filename.ext>] [box=<box size(pixels)>] [smpd=<sampling distance(in A)>] [stats=<yes|no|print{no}>]

simple_stackops

simple_stackops is a program that provides standard single-particle image processing routines that are applied to MRC or SPIDER stacks.

Usage:
>>>simple_stackops [stk=<stack.ext>] [stk2=<stack2.ext>] [nptcls=<nr of imgs>] [smpd=<sampling distance(in A)>] [outstk=<outstk.ext>] [split=<nr of partitions to split the stack into>] [oritab=<SIMPLE alignment doc>] [hp=<high-pass limit(in A)>](in A)>] [shalgn=<yes|no{no}>] [mul=<shift multiplication factor{1}>] [trs=<origin shift halfwidth(in pixels){0}] [lp=<low-pass limit(in A){20}>] [state=<state to extract>] [frac=<fraction of ptcls to extract{1}>] [class=<cluster2extract>] [snr=<signal2noise ratio>] [msk=<mask radius(in pixels){box/2}>] [vis=<yes|no>] [bin=<binarize{no}>] [acf=<yes|no{no}>] [phrand=<yes|no{no}>] [fromp=<start ptcl>] [top=<stop ptcl>] [nran=<number of random images to select>] [newbox=<scaled box>] [scale=<scale factor{1}>] [hfun=<sigm|tanh|lin{sigm}>] [norm=<yes|no{no}>] [noise_norm=<yes|no>] [nthr=<nr of openMP threads{1}>] [avg=<yes|no>] [filetab=<filenames.txt>] [stats=<yes|no{yes}>] [ctf=<yes|no|flip|mul|abs{no}>] [kv=<acceleration voltage(in kV){300.}>] [fraca=<frac amp contrast{0.07}>] [cs=<spherical aberration constant(in mm){2.7}>] [deftab=<text file with defocus values>] [ft2img=<yes|no{no}>] [frameavg=<nr of frames to average{0}>] [clip=<clipped box size{box}>] [compare=<yes|no{no}>] [mirr=<no|x|y{no}>] [neg=<yes|no{no}>] [box=<image size(in pixels)>] [outfile=<output_params.txt>] [ctfsq=<yes|no{no}>] [masscen=<yes|no{no}>] [thres=<threshold4bin[0,1]{0.6}>] [inner=<inner mask radius(in pixels)>] [width=<pixels falloff inner mask{10}>] [append=<yes|no{no}>]

Comments:
You can do many things with simple_stackops. Inputting two stacks of the same size results in the calculation of the joint Fourier Ring Correlation (FRC) between the images. Inputting no stacks, but setting nptcls, results in production of nptcls pure noise images, unless ctf=yes, then CTF images are produced. Filtering is controlled by the hp and lp arguments. If you input an alignment document (via oritab) shalgn=yes will produce a shift-aligned stack based on the inputted orientations, whereas if you do not input an alignment document, the alignment will be done in a reference-free manner (remember to set trs to some nonzero value). If you want to centre the images based on their centre of mass, set masscen=yes. If you want to extract a particular state, give an alignment document (oritab) and set state to the state that you want to extract. If you want to select the fraction of best particles (according to the goal function), input an alignment doc (oritab) and set frac. You can combine the state and frac options. If you want to apply noise to images, give the desired signal-to-noise ratio via snr. If you want to mask your images with a spherical mask with a soft falloff, set msk to the radius in pixels. If you want to binarize your images, set bin=yes. If thres is defined, the images are sigmoid normalised to and threshold binarized. If thres is not defined the foreground/background pixels are assigned by sort-means (a variant of the continuous k-means algorithm where the initial centres are obtained by sorting the real values). If you want to calculate the autocorrelation function of your images set acf=yes. If you want to randomise the phases of the Fourier transforms of your images, set phrand=yes and lp to the desired low-pass limit. If you want to extract a contiguous subset of particle images from the stack, set fromp and top. If you want to fish out a number of particle images from your stack at random, set nran to some nonzero integer number less than nptcls. If you want to resize your images, set the desired box to newbox or use the scale option. It is often convenient to use scale in rcombination with clip to resize images. If you want to normalise your images, set norm=yes. hfun controls the normalisation function. With avg=yes the global average of the inputted stack is calculated. With ctf=flip the contrast inversions due to the CTF are corrected by the infamous (but effective) phase-flipping heuristic. This requires additional input of CTF-related parameters (kv, fraca and cs) in addition to the defocus and astigmatism angle values, communicated either via oritab or via deftab. Even if you do initially phase-flip the images, which you should do for initial model production with PRIME, you can turn on the Wiener restoration later anyway, to accomplish correct weighting of information around the CTF zeroes and maximal noise reduction. ft2img=yes produces images of the square power spectrum of the images in stk. If you define frameavg to some integer number larger than one, averages with chunk sizes of frameavg are produced that may be useful for analysis of dose-fractionated image series. clip can be used to re-window or pad the images to a different box size. When compare=yes, the two inputted stacks are Fourier ring correlated. neg inverts the contrast of the images. ctfsq applies the squared CTF to the inputted images. inner is for applying an inner mask with fall-off width width. Finally, append is for appending stack stk2 with stack stk, so that the stk2 images occur last in the series and the stk name is preserved.

simple_volops

simple_volops provides standard single-particle image processing routines that are applied to MRC or SPIDER volumes.

Usage:
>>>simple_volops [vol1=<invol.ext>] [vol2=<invol2.ext>] [smpd=<sampling distance(in A)>] [outvol=<outvol.ext>] [nthr=<nr of openMP threads{1}>] [phrand=<yes|no{no}>] [msk=<mask radius(in pixels)>] [lp=<low-pass limit{20}>] [hp=<high-pass limit{100}>] [snr=<signal-to-noise ratio>] [center=<yes|no{no}>] [soften=<yes|no{no}>] [guinier=<yes|no{no}>] [bfac=<bfactor(in A**2){200.}>] [edge=<edge size for softening molecular envelope(in pixels){3}>] [mskfile=<mask.ext>] [countvox=<yes|no{no}>] [newbox=<scaled box>] [scale=<scale factor{1}>] [msktype=<hard|soft{soft}>] [inner=<inner mask radius(in pixels)>] [width=<pixels falloff inner mask{10}>] [cube=<side (in pixels){0}>] [e1=<1st Euler{0}>] [e2=<2nd Euler{0}>] [e3=<3d Euler{0}>] [corner=<corner size{0}>] [neg=<yes|no{no}>] [voltab=<file table>] [voltab2=<file table>] [bin=<yes|no{no}>] [nvox=<nr of voxels{0}>] [xsh=<x shift(pixels){0}>] [ysh=<y shift(pixels){0}>] [zsh=<z shift(pixels){0}>]

Comments:
If you input two volumes and the sampling distance, the FSC is calculated between the volumes. The FSC plot is written to STDOUT together with resolution estimates at in Fourier space. voltab and voltab2 are used to give text files with the names of volume files that are correlated and the nearest neighbour structure of the comparison is written to STDOUT.

   Utility programs

simple_print_fsc

simple_print_fsc is a program for printing the binary FSC files produced by PRIME3D

Usage:
>>>simple_print_fsc smpd=<sampling distance(in A)> box=<image size(in pixels)> fsc=<fsc_state1.bin>

simple_res

simple_res is a program for checking the low-pass resolution limit for a given Fourier index.

Usage:
>>>simple_res smpd=<sampling distance(in A)> find=<Fourier index> box=<box size (in pixels)>

simple_projvol

simple_projvol is a program for projecting a volume using interpolation in Fourier space. Input is a SPIDER or MRC volume. Output is a stack of projection images of the same format as the inputted volume.

Usage:
>>>simple_projvol vol1=<invol.ext> smpd=<sampling distance(in A)> [nspace=<nr of projs{1000}>] [outstk=<ouput stack>] [oritab=<SIMPLE alignment doc>] [nthr=<nr of openMP threads{1}>] [rnd=<yes|no{no}>] [trs=<origin shift(in pixels){0}>]
** less commonly used** [pgrp=<cn|dn|t|o|i{c1}>] [ctf=<yes|no|flip|mul{no}>] [kv=<acceleration voltage(in kV){300.}>] [fraca=<frac amp contrast{0.07}>] [cs=<spherical aberration constant(in mm){2.7}>] [defocus=<underfocus(in microns){3.}>] [bfac=<bfactor(in A**2){200.}>] [neg=<yes|no{no}>] [mirr=<yes|x|y|no{no}>] [top=<stop at this index>] [xfel=<yes|no{no}>]

Comments:
Projections are generated by extraction of central sections from the Fourier volume and back transformation of the 2D FTs. nspace controls the number of projection images generated with quasi-even projection directions. The oritab parameter allows you to input the orientations that you wish to have your volume projected in. If rnd=yes, random rather than quasi-even projections are generated, trs then controls the half-width of the random origin shift. Less commonly used parameters are pgrp, which controls the point-group symmetry c (rotational), d (dihedral), t (tetrahedral), o (octahedral) or i (icosahedral). The point-group symmetry is used to restrict the set of projections to within the asymmetric unit. ctf=yes allows you to apply CTF to the images, using constant defocus and no astigmatism. If you want to do this you need to define the parameters kv, fraca, cs, defocus and bfac. neg inverts the contrast of the projections. mirr=yes mirrors the projection by modifying the Euler angles. If mirr=x or mirr=y the projection is physically mirrored after it has been generated.

top