scipion logo

Scipion GUI

This page aims to introduce you in the usage of Scipion GUI. To start image processing in Scipion we need to run scipion from the command line. At first projects manager is displayed and we can create a new project or select one previously registered (Fig. 1).

Create a new project

Fig. 1 Figure 1. Create a new project

Once a project has been selected or a new one is created, a window will open with its content. In case of being a new one, a window will be displayed as shown in the following figure.

New project window

Fig. 2 Figure 2. New project window

At this point we will begin to build our processing workflow based on the protocols provided by Scipion.

Adding a protocol

To the left panel, different reconstruction tasks related to Single Particle Analysis (SPA) are listed. The tree menu is loaded from a configuration file where protocols are grouped according to base classes, e.g.: Micrographs Preprocess category displays ProtPreprocessMicrographs protocols. A protocol is a processing task that involves the execution of several steps and can be associated to different workflows, e.g.: SPA or Random Conical Tilt (RCT).

To add a protocol, you would just search for it within the tree and double-click on it. When you do this, a form will appear with the parameters that will need to be configured for the protocol execution. The following figure shows the protocol form Import Particles.

Import particles protocol

Fig. 3 Figure 3. Import particles protocol

Once all its parameters have been configured, we would proceed to its execution by pressing the Execute button. After this, the protocol will be shown as a box in the right panel (Fig 4.).

Executed import particles protocol

Fig. 4 Figure 4. Executing a protocol

To the right the sequence of protocols executed by the user and its state (running, finished, aborted) is listed. We can visualize it using list or tree views. Starting from Scipion version 1.1 it is possible to create labels associated with different protocols. You can find more details about labels here.

Due to the large number of protocols that exist in Scipion, searching the tree in the left pane is a bit difficult. Another way to add a protocol to our workflow is by using the protocol browser which is accessed by pressing Ctrl-F. It would only be enough to write a pattern of the protocol that we want to insert, and the browser will filter for all the protocols installed in Scipion (Fig. 5). After that, it would only be enough to select the protocol we are looking for.

Scipion protocol browser

Fig. 5 Figure 5. Scipion protocol browser

Copying a protocol

We can create copies of one or more protocols(to rerun its) that are in our workflow. It would only be enough to mark with a click or several protocols with Ctrl-click and choose the Copy option from the task bar that is located above the right panel(Fig. 4). If only one protocol is selected, when making the copy, its form will open which we can execute or just save. In case of selecting more than one protocol, when doing Copy, all the selected protocols will be copied and they will be shown in Save state (Fig 6).

Saving a protocol

Fig. 6 Figure 6. Saving a protocol

Removing a protocol

Also we can delete one or more protocols from de workflow. It would only be enough to select the protocols to delete and choose the delete option from the taskbar. Before executing this action, Scipion will ask for a confirmation of the operation (Fig. 7).

Removing a protocol

Fig. 7 Figure 7. Removing a protocol


These options and others can also be found by right-click on a protocol (Fig. 8).

Protocol options

Fig. 8 Figure 8. Protocol options

Analyzing Results

Some graphical viewers allow the visualization of the results of the protocols for later analysis. Bottom right panel displays information for the selected run, such as inputs and outputs, execution logs or documentation. To visualize the outputs of a protocol, Scipion provides the Analyze Results button. Once it is clicked on, the corresponding viewer for the output object will open (Fig. 9). This example shows a set of particles.

Analize Results

Fig. 9 Figure 9. Analize Results

Another way to view a protocol output is by Right-click on it. The capable viewers of opening the type of object in question will then appear. All you have to do is choose one of them and that output will be displayed (Fig. 10).

Viewer list

Fig. 10 Figure 10. Viewer list

Schedule protocol

Sometimes we need a protocol to finish its execution to be able to launch another protocol. Scipion protocol forms have a parameter called “Schedule protocol after” (Fig. 11) in which you can specify one or more protocols (protocols IDs separated by a comma).This protocol starts after the input protocols in the list are finished. This function will allow you to “schedule” many runs that will be executed after each other.

Prerequisites parameter

Fig. 11 Figure 10. Prerequisites parameter

To better familiarize ourselves with the Scipion GUI, we will use two more complex projects. More specifically, for this tutorial we registered projects TestSpiderWorkflow and TestXmippWorkflow for illustrative purposes (running scipion tests tests.em.workflows.test_workflow_spiderMDA and pyworkflow.tests.em.workflows.test_workflow_xmipp).

Spider Workflow

If we open TestSpiderWorkflow project GUI is loaded(Fig 9).

Project GUI in Protocols Mode

Fig. 12 Figure 12. Project GUI in Protocols Mode

If we switch to Data mode (top right), then left panel displays EM objects registered for each type and right panel displays project data tree, with protocol output objects as nodes and edges towards objects used as input. Bottom right panel displays information for the selected item, that can be opened using double click. This mode allows us to track image processing emphasizing on data handling.

Project GUI in Data Mode

Fig. 13 Figure 13. Project GUI in Data Mode

TestSpiderWorkflow project imports a set of particles, preprocess and aligns them to finally use it as input for different 2D classification algorithms. If we open filter particles protocol (using edit) the following form is displayed:

Filter Particles Protocol Form

Fig. 14 Figure 14. Filter Particles Protocol Form

Protocol provides cite references and help util to introduce user on the subject (Fig. 15-16). Form possess two sections: Run and Input. Run section is common to all protocols and allows the user to configure run label and comments (to personalize runs, Fig. 14); execution mode (restart or resume), host, and threads or MPI. Many image processing tasks are computer expensive so they need to be run on specific hosts, using queue system and parallel processing. Parallelization can be supported by underneath algorithm or enabled for protocols with independent steps.

Input section allows to specify input parameters for the task, like input particles or filter type. A brief description is provided for all of them (using help button) and for some a Search GUI to select input object (Fig. 14) or a wizard GUI (through eye button). Parameters are showed considering expert level selected (Normal, Advanced or Expert).

Protocol Cite

Fig. 15 Figure 15. Protocol Cite

Protocol Help

Fig. 16 Figure 16. Protocol Help

List of SetOfParticles objects registered

Fig. 17 Figure 17. List of SetOfParticles objects registered

We can visualize filtered particles using “Analyze Results” (Fig. 18). ShowJ viewer is the default viewer for most of Scipion objects, like images, volumes, sets of images, classes, etc. It can display data in gallery and table modes and navigate trough different blocks of data. Also load single images, create subsets, etc. See ShowJ for more detail. In this project we use it to refine output from a 2D classification algorithm.

ShowJ displaying filtered particles

Fig. 18 Figure 18. ShowJ displaying filtered particles

If we select 2D classification protocol spider-classify kmeans and open output classes, we can see representative particle for each class (Fig. 19). Third and fourth items seemed very similar so we can disable fourth item and create a subset containing only remaining classes. This operation registers a subset protocol with this classes as input and the set of classes with enabled items as output.

ShowJ displaying a SetOfClasses

Fig. 19 Figure 19. ShowJ displaying a SetOfClasses

Xmipp Workflow

If you open TestXmippWorkflow the following project GUI is displayed (Fig. 20):

TestXmippWorkflow Project GUI

Fig. 20 Figure 20. TestXmippWorkflow Project GUI

This project imports a set of micrographs (eg: Fig. 21), reduce its image size using downsample and estimates their CTF. Then, picks particles from micrographs and extracts particles to use it as input for alignment and classification algorithms like cl2d, ml2d, kendersom or rotational spectra. We use it to illustrate CTF and particle picking GUIs.

ShowJ displaying input micrograph with "gaussian blur" filter applied

Fig. 21 Figure 21. ShowJ displaying input micrograph with “gaussian blur” filter applied

ShowJ GUI for single images is displayed above (see Showj)

Screen micrographs produces this output:

CTF Recalculate Wizard

Fig. 22 Figure 22. CTF Recalculate Wizard

We can use CTF wizard to redefine input parameters to recalculate CTF on specific micrographs. Recalculate CTFs will register a new protocol that receives this SetOfCTF as input and creates an output set with CTFs updated.

Particle picking can be done in Scipion using Xmipp, Eman, Bsoft, etc. In this tutorial we chose Xmipp Particle Picker, see Fig. 23.

Xmipp Particle Picker GUI

Fig. 23 Figure 23. Xmipp Particle Picker GUI

The Xmipp picker allows us to iterate over the micrographs to pick particles, see Picker. After we have done some manual/supervised picking and feel confident with the results we register output coordinates into Scipion using Add Coordinates button.