[Top] [Contents] [Index] [ ? ]

gEMcrystal

This is a manual for gEMcrystal, a graphical user interface for gEMpicker.

The menu below presents a brief introduction to this program and lists its sections:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1. Introduction

This is the user manual for gEMcrystal, the graphical tool developed at Inria Nancy for picking particles in cryo-electron microscopy micrographs.

Cryo-electron microscopy has become a powerful technique in structural biology. It allows the observation of samples that have not been stained or fixed in any way, showing them in their natural environment. Since the electron doses used to collect micrographs of biological molecules are limited to avoid radiation damage, images of individual particles have a low signal-to-noise ratio. To overcome this, it is necessary to work with a large number of images and average them.

Consequently, the first step in processing the information consists in selecting particles from each micrograph. This is a very demanding process to be done manually, and so several programs have been created to perform this task automatically. Even though some of these can use multiple CPU cores, they are often still slow because calculating picking correlations is computationally expensive.

However, researchers at Inria Nancy have developed a new fast software for particle picking called gEMpicker. It uses the computational power of GPU, which drastically reduces the running time. It is described by its authors as a template-based highly parallel GPU-accelerated particle picking program. gEMpicker runs in multi-thread and multi-process mode to use all available CPU cores and GPUs in a single workstation or a multi-node cluster for the demanding 2D correlation computation. More information about gEMpicker can be found at http://gem.loria.fr/gEMpicker.html.

gEMpicker was created to be run from terminal, but now a graphical user interface named gEMcrystal has been developed for it, also at Inria Nancy. The original aim of gEMcrystal was to allow the user to access gEMpicker in a simple and fast way. However, many other functionalities have been added. The latest version of gEMcrystal allows the user to:

For a practical access to its functionalities, gEMcrystal is divided in four different modules: Viewer, Mask, Picker and Results. Each of them is focused on a specific set of tasks.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2. Installing gEMcrystal

gEMcrystal was developed to run on Linux systems in order to provide an interactive interface to gEMpicker. Therefore, the binaries for gEMcrystal also include gEMpicker, making the installation faster and easier. Also the system dependencies needed are included in the binaries, so it should work without having to install any extra ones.

Three different versions for 64-bits architectures are available:

The easiest way to install gEMcrystal is to download the self-installing script from the website http://gem.loria.fr and run the file. When launched, it will ask some questions about where the user wishes to install the program and whether he will let the script modify one of his shell start-up scripts in order to run the program from the command line. The installer will normally define an environment variable called GEM_ROOT, and it will add ${GEM_ROOT}/bin to your command path. It will also run a test to check if the installation was successful.

The self-installing script will ask for permission before starting the installation, so if the user prefers to do it manually just has to answer no. In that case he will find a folder named gem-tmp-1.0 in the directory where the gEMcrystal file is located. Inside that directory there is a .tar file with all the necessary binaries.

To run gEMcrystal, the user just has to type gEMcrystal in his shell and it will be launched. In addition, gEMpicker can also be accessed from terminal by typing gEMpicker.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3. Displaying Images

When launching gEMcrystal, the Viewer module is displayed.


captures/viewer_r

Figure 1. Viewer


It allows the user to display both .mrc and .tif images. To do that it presents four tools:



[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

4. Creating Masks

The Mask module allows the user to create new masks for target images. It also presents the same functionalities as Viewer.

It is possible both to open an image from Viewer and then go to Mask and to open it directly from Mask.

To develop a new mask two different shapes are available: ellipses and polygons. To create an ellipse select Create Ellipse on the right panel.


captures/mask2_r

Figure 3. Create Ellipse


Then, double click in the center of the desired object and without releasing the button drag until the desired size is reached.


captures/mask3_r

Figure 4. Build an ellipse


Once the ellipse is created, by clicking on it and dragging it can be moved. Also, if the user right-clicks on the figure a menu is displayed, giving the possibility to delete it.

To create a polygon select Create Polygon on the right panel.


captures/mask4_r

Figure 5. Create Polygon


Double-click to generate a new vertex. By clicking and dragging it can be moved and by right-clicking a menu with the possibility of deleting it is displayed.


captures/mask5_r

Figure 6. Set the vertices


Once all the vertices are set, press Build Polygon to create the polygon. It will be constructed by biding the vertices according to the order in which they were created, so they have to be set in order. Once the polygon is built it can not be either moved or deleted.

Only simple polygons are accepted, so if the vertices set do not belong to a simple one, they will be deleted and a message will be displayed.

Each time a new polygon is built the coordinates of its vertices are added to the display on the right panel. The content of the display can be saved in a .txt file with Save Coordinates to .txt File or erased with Clear coordinates.


captures/mask6_r

Figure 7. Build the polygon


Once all the objects are created, the mask can be saved to a .tif file by clicking Save Mask to .tif File. The name of the file will be nameOfTheMigrograph__msk_ref.tif. If a directory has already been set for Masks for target images, the file will be saved there, if not, a folder named msk_ref will be created in the same level that the folder containing the micrograph for that purpose.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

5. Running gEMpicker

The Picker module allows the user to access gEMpicker. It has a panel on the right side where the parameters are set.


captures/picker1_r

Figure 8. Picker


They can be set directly by loading them from a file, manually or combining both methods. In case of combining, first load the file and then finish setting them up, if not, the information obtained from the file will overwrite what was previously set. For more information about the parameters see section Parameters File.


captures/picker2_r

Figure 9. All parameters set


After all the parameters have been set press Run to execute gEMpicker. Its output will be displayed.


captures/picker3_r

Figure 10. Compute Correlation mode



captures/picker4_r

Figure 11. Perform Picking mode


There are four different tools for manipulating the output:


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

6. Analyzing Results

Through the Result module it is possible to access the results in an interactive way.


captures/result1_r

Figure 12. Result


The directories can be set directly by loading them from a file, manually or combining both methods. In case of combining, first load the file and the finish setting them up, if not, the information obtained from the file will overwrite what was previously set.


captures/result2_r

Figure 13


The default number of images per row is 6, but it can be changed by the user in order to get the desired size for displaying the picks images. In addition, it is possible to filter the picks by its correlation value. Any interval between -1 and 1 can be set. By default the minimum value is -1 and the maximum is 1. Once everything is set, press the Display button to visualize the picks.

On the display panel a list will appear with the name of all the micrographs in the Micrographs Directory and on top of it the name of the one which is being displayed (it pops up in a new window). The arrows allow the user to go to the previous or to the next micrograph, and it is also possible to go directly to any of the micrographs in the directory.


captures/result3_r

Figure 14. Results display


For each micrograph, all the particles which were picked by gEMpicker and which matched the user defined parameters are displayed with its corresponding correlation value.


captures/result4_r

Figure 15. Selected pick


When a pick is selected a blue square appears on the micrograph to show its position. The other way around for selecting is also available.


captures/result5_r

Figure 16. Selected pick


Once a pick is selected the user can choose the tick or the cross to indicate if the pick was correctly chosen or not. By default all the picks are considered correctly chosen.


captures/result6_r captures/result7_r

Figure 17. Right and Wrong


When Apply Changes is clicked, the pictures selected as wrong ones are erased, updating some files and deleting those which are not necessary any more.

Pressing Discard Changes will clear the selections made over the picks.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

7. Parameters File

Since many parameters are necessary to save the masks, run gEMpicker and see the results, the possibility of getting them directly from a file has been added to gEMcrystal. The user can choose between setting the parameters one by one, loading them from a file or a combination of both.

The file has to respect the template provided. To load it, the user has to go to the upper part of the screen, click on the Open File icon and select the file. Automatically all the parameters will be loaded. In case there were previous ones set, these will be updated. If some settings are missing from the parameters file, they will be left blank or set to the default value depending on the parameter.

In addition, once the parameters are set, the user can add or change settings from the parameter panel of each module.

Template

 
***** gEMcrystal Parameters File *****

*** required ***
target=

*** required ***
search=

*** optional ***
maskRef=

*** required ***
maskSch=

*** required ***
result=

*** required, 0 Compute Correlation, 1 Particle Picking ***   
mode=

*** required, 0 Negative Peaks, 1 Positive Peaks ***
micContrast=

*** required ***
rotAngle=

*** required ***
threshold=

*** optional ***
maxPiks=

*** optional ***
sizePiks=

*** optional ***
CPU=

*** optional ***
GPU=

• target: (required) directory of target images (*.mrc)

• search: (required) directory of search images (*.mrc)

• maskRef: directory of masks for target images (*.tif)

• maskSch: directory of masks for search images (*.tif)

• result: (required) directory for results

• mode: (required) running mode: 0 compute correlation, 1 perform picking

• micContrast: (required) micrograph contrast: 0 negative peaks, 1 positive peaks

• rotAngle: (required) in-plane rotating angle in degrees (0 = no rotation)

• threshold: threshold value for picking: (0, 1]

• maxPiks: maximum number of particles picked from each micrograph (0 = no limit)

• sizePiks: size of picked images (if not provided or = 0, use search image size)

• CPU: number of CPUs cores / process

• GPU: number of GPUs / process


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated by Lucia MARTIN-REIXACH on November 28, 2013 using texi2html 1.82.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ < ] Back Previous section in reading order 1.2.2
[ > ] Forward Next section in reading order 1.2.4
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ Up ] Up Up section 1.2
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated by Lucia MARTIN-REIXACH on November 28, 2013 using texi2html 1.82.