Table of Contents

Overview

ISAC (Iterative Stable Alignment and Clustering) is a 2D classification algorithm. It sorts a given stack of cryo-EM particles into different classes that share the same view of a target protein. ISAC is based around iterations of alternating equal size k-means clustering and repeated 2D alignment routines.

You can find the details of the ISAC algorithm in this paper. To cite ISAC, use the following: Yang, Z., Fang, J., Chittuluru, J., Asturias, F. J. and Penczek, P. A. (2012) Iterative stable alignment and clustering of 2D transmission electron microscope images. Structure 20, 237–247.

ISAC versions

Download & Installation

Before you start, please note the following system requirements
  • CUDA: These installation instructions assume that CUDA is already installed on your system. You can confirm this by running nvcc --version in your terminal; the resulting output should list the version of your installed CUDA compilation tools.
  • SPHIRE: In order to use GPU ISAC, SPHIRE needs to be installed. You can find the SPHIRE download and installation instructions here. You can confirm a working SPHIRE version by running which sphire in your terminal; the resulting output should give you the path to your SPHIRE installation (the path should indicate a version number of 1.3 or higher).

Download

Installation

Before you start, make sure your SPHIRE environment is activated.

How to activate your SPHIRE environment:

How to activate your SPHIRE environment:

  • During the SPHIRE installation, an Anaconda environment for SPHIRE was created. You can list your available Anaconda environments using:
conda env list
  • Look for your SPHIRE environment and activate it using either:
conda activate NAME_OF_YOUR_ENVIRONMENT

or 

source activate NAME_OF_YOUR_ENVIRONMENT

It will depend on your system and Anaconda installation which one of these you will have to use.

GPU ISAC comes with a handy installation script that can be used as follows:

  1. Extract the archive to your chosen GPU ISAC installation folder.
  2. Open a terminal and navigate to your installation folder.
  3. Run the installation script:
./install.sh

All done!

During installation GPU ISAC links itself to the SPHIRE GUI and can be called from there like any other SPHIRE program!

Running GPU ISAC

When calling GPU ISAC from the terminal, an example call looks as follows: 

mpirun python /path/to/sp_isac2_gpu.py bdb:path/to/stack path/to/output --CTF -–radius=160 --img_per_grp=100 --minimum_grp_size=60 --gpu_devices=0,1

Using the following mix of both mandatory and optional parameters (see below to learn which is which): 

mpirun python /path/to/sp_isac2_gpu.py
bdb:path/to/stack
path/to/output
--CTF
-–radius=160
--img_per_grp=100
--minimum_grp_size=60
--gpu_devices=0,1

[ ! ] - Mandatory parameters in the GPU ISAC call:

What GPUs do I have and what are their system id values?

What GPUs do I have and what are their system id values?

You can use nvidia-smi in your terminal to see what GPUs are available on your machine. This also lists their id values and sorts all entries by CUDA compute capability, where your most powerful GPU has id value 0 and your least powerful GPU has the highest id value:

Above: Example output of nvidia-smi. GPU system id values and GPU names marked in red. Among other things, this also lists your current driver version, marked in turquoise.

[?] - Optional parameters recommended to be used when running GPU ISAC:

  • An up to date list of all GPU ISAC parameters can always be printed by using the -h parameter (in this case you do not need to specify any other parameters):
mpirun python /path/to/sp_isac2_gpu.py -h

or simply 

python /path/to/sp_isac2_gpu.py -h
  • The online documentation of ISAC2 parameters can be found here.
  • Additional utilities that are helpful when using any version of ISAC can be found here.
  • More information about using ISAC for 2D classification can also be found in the ISAC chapter of the official SPHIRE tutorial (link to .pdf file).

Examples

EXAMPLE 01: Test run

This example is a test run that can be used to confirm GPU ISAC was installed successfully. It is a small stack that contains 64 artificial faces and is already included in the GPU ISAC installation package. You can process it using GPU ISAC as follows:

  1. In your terminal, navigate to your GPU ISAC installation folder:
cd /gpu/isac/installation/folder
  1. Run GPU ISAC:
mpirun python bin/sp_isac2_gpu.py 'bdb:examples/isac_dummy_data_64#faces' 'isac_out_test/' --radius=32 --img_per_grp=8 --minimum_grp_size=4 --gpu_devices=0

Note that we don't care about the quality of any produced averages here; this test is used to make sure there are no runtime issues before a more time consuming run is executed.

EXAMPLE 02: TcdA1 toxin data

This example uses the SPHIRE tutorial data set (link to .tar file) described in the SPHIRE tutorial (link to .pdf file). The data contains about 10,000 particles from 112 micrographs and was originally published here (Gatsogiannis et al, 2013).

After downloading the data you'll notice that the extracted folder contains a multitude of subfolders. For the purposes of this example we are only interested in the Particles/ folder that stores the original data as a .bdb file.

You can process this stack using GPU ISAC as follows:

  1. In your terminal, navigate to your GPU ISAC installation folder:
cd /gpu/isac/installation/folder
  1. Run GPU ISAC:
mpirun python bin/sp_isac2_gpu.py 'bdb:/your/path/to/Particles/#stack' 'isac_out_TcdA1' --CTF --radius=145 --img_per_grp=100 --minimum_grp_size=60 --gpu_devices=0

The final averages can then be found in isac_out_TcdA1/ordered_class_averages.hdf. You can look at them using e2display.py (or any other displaying program of your choice) and should see averages like these:

Above: 95 class averages produced when processing the above data set using GPU ISAC. The particle stack contains 11,003 particles and the averages were computed within 6 minutes (Intel i9-7020X CPU and 2x GeForce GTX 1080 GPUs).

Usage

Next to producing high quality 2D class averages, GPU ISAC is also an excellent tool to screen your data which allows you to:

Well, “suitable parameters” sounds great! How do I get those?

Well, “suitable parameters” sounds great! How do I get those?

Clustering cryo-EM data is a difficult problem that involves many different parameters and often it is unclear how these impact the resulting 2D class averages. In GPU ISAC the most relevant parameters to fiddle with are:

  • Class size: The class (or cluster) size --img_per_grp in ISAC determines how many particles are taken together in order to construct a new 2D class average. High values will mean cleaner averages, but might also lump together particles that should be sorted into different classes. If you are using GPU ISAC to screen a set of 20,000 to 40,000 particles, then '100' particles per class are a good starting value. Further, the minimun size of each class --minimum_grp_size should be around 60% of set class size.
  • Threshold error: The --thld_err parameter determines how similar subsequently produced averages have to be in order to be considered stable enough. A value of 0.7 is very stringent, while 1.4 is less so, and you should not need a higher value than 2.4.

Since GPU ISAC processes small stacks of about 10,000 to 20,000 particles fairly quickly, you can try several runs with different values for --img_per_group and --thld_err to see which combination gives you the best results. Once you are happy with the results, you can use these parameters for a full-sized run of (GPU) ISAC. Good luck! :)

GPU ISAC output files

GPU ISAC produces a multitude of output files that can be used to analyze the success of running the program, even while it is still ongoing. These include the following:

Release notes

GPU ISAC limitations

Known issues

GPU ISAC v2.3.4

GPU ISAC v2.3.3

GPU ISAC v2.3.1 & v2.3.2 (hotfix releases)

GPU ISAC v2.3

GPU ISAC v2.2

GPU ISAC “Chimera”