Relion

Overview

Relion is program that employs an empirical Bayesian approach to refinement of (multiple) 3D reconstructions or 2D class averages in electron cryo-microscopy (cryo-EM). It is developed in the group of Sjors Scheres at the MRC Laboratory of Molecular Biology.

Versions 1.3 and 1.4 are installed on the CSF. They have been compiled from source using the Intel v12.0.5 compilers and OpenMPI 1.6.

Restrictions on use

There are no restrictions on accessing this software on the CSF. The software is released under the GNU GPL v2 license. The authors request you cite the use of the software in your publications – please see the Relion website for details.

Set up procedure

To access the software you must first load one of the following modulefiles, according to whether you wish to run on Ethernet networked nodes (also if using single node SMP jobs) or InfiniBand networked nodes (faster networking for multi-node jobs):

# Multi-node job (using all cores on the nodes) with fast InfiniBand networking
module load apps/intel-12.0/relion/2.0.3-ib
module load apps/intel-12.0/relion/1.4-ib
module load apps/intel-12.0/relion/1.3-ib

# Single-node multicore job
module load apps/intel-12.0/relion/2.0.3
module load apps/intel-12.0/relion/1.4
module load apps/intel-12.0/relion/1.3

These modulefiles will load automatically the compiler and MPI modulefiles for you.

Running the application

Relion can be run with a GUI on the login node. This is mainly used to select input files and set up job parameters. The GUI will then submit your job to the batch queues.

Users must always run the main processing in batch (where the GUI permits submission to the batch system), never directly on the login node. This requires correct settings in the GUI, as instructed below.

Relion tools other than the GUI found running on the login node will be terminated without warning and access to the GUI may be withdrawn.

Please note, a tutorial on using Relion to process your data is beyong the scope of this page, which only describes how to run the application on the CSF. Please follow the Relion Turorial (pdf) on the Relion website if you are new to the software.

Running the GUI

Once the modulefile file is loaded you should navigate to your Relion project directory (this is important – it will usually contain a Micrographs subdirectory) and then run relion on the login node. For example:

cd ~/scratch/my_relion_project/
relion

It will display the following GUI (click on image to enlarge):

Various operations can be performed by selecting from the list on the left hand side (Micrograph inspection, CTF estimation and so on). These operations allow you to specify use of the batch system, as detailed below.

Note: To re-activate a greyed-out Run button, press Alt+R in the GUI.

Using the GUI to run in Batch

Each Relion processing operation (Micrograph inspection, CTF estimation etc) has a Running tab in its GUI page. There are three possible types of Running tab:

1. Greyed-out (e.g., select Micrograph inspection from the list). This operation does not require the batch system:
   
2. Active for MPI job (e.g., select CTF estimation from the list). This operation will generate a batch script and submit it:
   The options should be set as follows:
   • Number of MPI procs: 1 for serial jobs, 2-24 for single-node jobs (see Queue name below), 48-120 (in multiples of 24) for multi-node jobs. We recommend using 2-24 initially.
   • Submit to queue?: You must set this to Yes. If you fail to do this your job will run on the login node and will be killed by the sysadmins. Users found repeatedly forgetting to turn on the Submit to queue option will be banned from using this software.
   • Queue name: Use smp.pe for single node jobs (2-24 cores) or orte-24-ib.pe for multi-node jobs (48 or more cores and in multiples of 24, ensure you have loaded the relion -ib modulefile).
   • Queue submit command: leave as qsub
   • Standard submission script: leave as

     /opt/gridware/apps/intel-12.0/relion/version/bin/qsub.sh

   • Additional arguments: leave blank
3. Active for MPI+OpenMP job (e.g., select 2D classification from the list). This operation will generate a batch script and submit it:
   The options should be set as follows:
   • Number of MPI procs: 1 for serial jobs, 2-24 for single-node jobs (see Queue name below), 48-120 (in multiples of 24) for multi-node jobs (see Queue name below). We recommend using 2-24 initially.
   • Number of threads: leave as 1.
   • Available RAM (in Gb) per thread: leave as 4
   • Submit to queue?: You must set this to Yes. If you fail to do this your job will run on the login node and will be killed by the sysadmins. Users found repeatedly forgetting to turn on the Submit to queue option will be banned from using this software.
   • Queue name: Use smp.pe for single node jobs (2-24 cores) or orte-24-ib.pe for multi-node jobs (48 or more cores and in multiples of 24, ensure you have loaded the relion -ib modulefile).
   • Queue submit command: leave as qsub
   • Standard submission script: leave as

     /opt/gridware/apps/intel-12.0/relion/version/bin/qsub.sh

   • Additional arguments: leave blank

Submitting the Batch Job from the GUI

Once you have set the Running tab options as indicated above press the Run! button to submit an auto-generated jobscript to the batch system. It may appear that nothing has happened when you do this. However, you should check on the job using the usual qstat command by running it in a command-line window on the CSF. It will report whether your job is queued or running. If you see no output then you job has finished (either successfully or because an error occurred).

The auto-generated jobscript will be written to your current directory (your Relion project directory) and will be named similar to the operation being performed with a .script extension. For example:

run_ctffind_submit.script

The usual output and error output from the job will be written to files with .out and .err extensions respectively. You should check these for further information about your job. For example:

run_ctffind.out
run_ctffind.err

Summary

• Where the Running panel is active, ensure you set the Submit to Queue option to be Yes.
• Select the number of MPI procs to use.
• If available, set the number of threads to be 1.
• Set the Queue Name so be smp.pe or orte-24-ib.pe.
• If using orte-24-ib.pe ensure you have loaded the relion -ib version of the modulefile.
• Pressing the Run! button will submit an auto-generated jobscript to the batch system.
• Check on your job by running qstat in a terminal window on the CSF.

Advanced: Custom Batch Script Template

This section is for advanced users familiar with Relion and the CSF batch system. In most cases the default settings will work for you and you should not need to follow this section.

Relion auto-generates jobscripts by filling in place-holders in a qsub template file named qsub.sh. It is possible for you to take a copy of this file, modify it and have Relion use your new template each time you submit a job via the Relion GUI. The following steps are required:

1. Exit Relion if the GUI is currently running
2. Copy the system-wide template file (for example in to a directory in your home area):

   cp $RELION_QSUB_TEMPLATE ~/my_relion_project/
   

3. Edit the template (see below for more information):

   gedit ~/my_relion_project/qsub.sh
   

4. Update the environment setting indicating where the template file is:

   export RELION_QSUB_TEMPLATE=~/my_relion_project/qsub.sh
   

5. Restart Relion:

   relion
   

The default template file contains:

#!/bin/bash
#$ -pe XXXqueueXXX XXXmpinodesXXX
#$ -e XXXerrfileXXX
#$ -o XXXoutfileXXX
#$ -cwd
#$ -S /bin/bash
#$ -V

mpiexec -n XXXmpinodesXXX  XXXcommandXXX

The XXX.....XXX keywords are the place-holders that will be replaced with the settings you specify in the Relion GUI. You should leave the -pe setting as is. However, you may wish to add other CSF options such as

#$ -l twoday      # Run in two-day area of the CSF
#$ -m ea          # Email me when job ends or aborts

Alternatively you may want to add other commands to the jobscript, for example:

# Report the date before running
date
mpiexec -n XXXmpinodesXXX  XXXcommandXXX

Advanced: Hand-crafting Jobscripts

If you wish to submit a batch job manually from the command-line (using your own batch script) in the traditional CSF manner, then you can ask Relion to display the command it will use in its auto-generated jobscript.

Start the Relion GUI, select the operation to perform (e.g., 2D Classification), select the Running tab, make any changes to the settings then press the Print command button to display in your shell window what Relion uses in its jobscript.

For example, the following is displayed for the 2D Classification example above:

`which relion_refine_mpi` --o Class2D/run1 --i  --particle_diameter 200 \
--angpix 3.54 --ctf  --iter 25 --tau2_fudge 2 --K 1 --flatten_solvent  \
--zero_mask  --oversampling 1 --psi_step 10 --offset_range 5 --offset_step 2 \
--norm --scale  --j 1 --memory_per_thread 4 

Hence you can write your own jobscript to run this command. Ensure that you add the usual mpirun command and specify the correct number of cores. For example:

#!/bin/bash
#$ -S bash
#$ -cwd                  # Run from current directory
#$ -V                    # Inherit modulefile settings
#$ -pe smp.pe 8          # We'll use 8 cores (single-node)

# We must add the usual mpirun command as used in many CSF jobscripts

mpirun -n $NSLOTS `which relion_refine_mpi` --o Class2D/run1 --i  \
--particle_diameter 200 --angpix 3.54 --ctf  --iter 25 --tau2_fudge 2 --K 1 \
--flatten_solvent  --zero_mask  --oversampling 1 --psi_step 10 --offset_range 5 \
--offset_step 2 --norm --scale  --j 1 --memory_per_thread 4 

# We can add any other commands we wish to run from the jobscript. EG:
date

Notice that we have added mpirun -n $NSLOTS to the start of the command that Relion reported. Relion will automatically add this when it auto-generates a jobscript.

You should then submit your jobscript using the usual qsub command:

qsub myjobscript

where myjobscript is the name of your jobscript.

Further info

• Relion website

Updates

None.