Getting started with xmipp_protocols

Xmipp_protocols is a good way of getting started with Xmipp. It represents a collection of standardized protocols for its most popular tools and a new graphical user interface (GUI) makes their use very convenient and straightforward.

Getting Started

Use a separate directory for each data set/project (called the projectdir).
To launch the GUI you should always go to your projectdir and type:

If xmipp_protocols was never executed before in this directory, you will be asked
 + Xmipp_protocols was never executed before in this directory.
 + Make sure you run xmipp_protocols only in your project directory.
 + You are in directory: /home/bioinfo/scheres
 + Do you want to setup Xmipp protocols here? [y/n]:          
Just type y, and the master GUI will be launched. See the MasterGuiScreenShot. (If not, see below System requirements). Clicking on any of the ten available tasks will launch the GUI for the corresponding protocol. See the ProtocolGuiScreenShot. This GUI serves to modify the relevant parameters settings and to submit the job.

Please see the DetailedDescriptionOfAllProtocolsPage for help on the parameter settings for each protocol.

Note the following buttons:

  • Help (on the right) will give more detailed information on the corresponding parameter.
  • Show Expert Options (bottom row) will reveal additional options in yellow. See the ExpertOptionsScreenShot.
  • Save (bottom row) will save your parameter settings in the python script header (in the projectdir).
  • Save & Execute (bottom row) will save the parameter settings and submit the script for execution.
  • Load (bottom row) may be used to load the parameters setting you used in a previous run (just select the corresponding working directory).
  • Analyse Results (bottom row) will launch a GUI to visualize the results of a previous run. To visualize a different run, first use the Load button (see above) to load the corresponding protocol.

Also note that:

  • Clicking Save & Execute will launch a pop-up window asking whether to use a job queueing system. Many mainframes require job submission via such queues. If you click yes, you will be asked for the corresponding queue submission command. If you don't have a queueing system, just click no and the job will be executed directly. Note that interactive jobs (e.g. those launching graphical windows) should never be sent via job queueing systems.
  • For CPU-intensive protocols (ML2D & ML3D classification, projection matching and multi-resolution refinement) the protocols may be executed in parallel (using MPI). Just provide the number of processors to be used and (if relevant) the mpi-machinefile or its corresponding environment variable. The ParallelProtocolPage describes how to run these protocols in parallel on several multi-processor mainframes.
  • Each protocol will create a working directory for the output of each run. We recommend using TheSuggestedDirectoryHierarchy.
  • You may delete the working directory if it already exists to prevent mixing different runs together, but be careful with this option as it will delete your data from disc! In case of doubt, always create a new working directory.
  • The protocols make a logging of all executed commands in the Logs/ directory (inside the projectdir). A description of the logging file format is available on the LogFileFormatPage.

Software Design

The protocols have been implemented as executable python scripts that make system calls to the multitude of stand-alone Xmipp programs. The GUI has been written in python-tk, and is merely a single script (xmipp_protocol_gui.py) that parses the standardized headers of the protocol scripts. The GUI makes working with the protocols easier, but its use is not mandatory (see below: I don't like GUIs). The GUI automatically takes care of 3 tasks:
  • copy the python scripts from the installation directories to the projectdir
  • provide a convenient editor for their parameter definitions
  • execute the python scripts (either directly or via queueing systems)

System requirements

To run the protocols scripts, you will need to have python installed (version 2.3 or newer). To use the GUI you will also need the python-tk libraries. You may check these requirements by typing:
cumbia /home/scheres> python
Python 2.4 (#1, May 30 2005, 19:23:06)
[GCC 3.3.5 20050117 (prerelease) (SUSE Linux)] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import Tkinter
The python version number is given at the top and the import of Tkinter should not give an error message. If you don't have a valid python installation or if the tk libraries are not present, ask your system administrator to install them.

I don't like GUIs

No harm done! You may manually copy the python scripts from the installation directory to your project directory, edit the parameter settings in their header using your favorite editor and execute them from the command line. To find the python scripts, just type:
which xmipp_protocols
The protocols will be in a directory called protocols/, at the same depth as the bin/ directory where xmipp_protocols has been installed.

-- SjorsScheres - 27 Nov 2007