FRM alignment

Fast Rotational Matching alignment

Overview

This approach achieves basically the same task as stated here, but much faster and more accurate. Some other functionalities are also included, such as resolution determination according to gold-standard FSC and CTF correction using Wiener filter.

This is by no means a comprehensive document about the mathematical details. For that, please refer to the paper: Fast and accurate reference-free alignment of subtomograms, Y. Chen et al., JSB 2013.

If you are a advanced user and for some reason you want to integrate this fast algorithm into your own software, it is also possible and quite straight forward. Check out the underlying library SH Alignment here (written in C and Python) and follow the instruction described below.

Script description

Here we assume you already have the subtomograms to be aligned, either by template matching or any other means. What matters here is the subtomograms on disk and the corresponding particle list file describing all the relevant information (please check here if you already have the subtomograms and want to generate the particle list).

Depending on the purpose, there are four scripts that could be used for the alignment, which are all contained in the module pytom.frm. They can be classified into two categories: with-/without gold standard, with-/without Wiener filtering. You should choose one that fits to your problem. The ways to use all these scripts are similar and they are described below.

Script names and functionalities

	Non gold standard	Gold standard
Non Wiener filter	FRMAlignment.py	GFRMAlignment.py
Wiener filter	WienerFilterAlignment.py	GWienerFilterAlignment.py

Subtomogram alignment using FRMAlignment.py

This script is the most basic one, without gold standard FSC and CTF correction. If you just want to align the volumes and nothing more, this is the one you should use. The call of this script with MPI is:

mpirun --hostfile "pathToYourHostfile" -c "numberOfCPUs" pytom PathToPytom/frm/FRMAlignment.py -j job.xml -v

It requires a job description file: job.xml, which can be generated interactively using the script frm/createJob.py or any text editor if you are very familar with the XML format. An example of the job file would be:

<FRMJob Destination='.' BandwidthRange='[4, 64]' Frequency='10' MaxIterations='10' Binning='1' PeakOffset='10' AdaptiveResolution='0.1' FSC='0.5'>
  <Reference PreWedge="" File="YOUR_REFERENCE.em" Weighting="">
    <ParticleList Path="/"/>
  </Reference>
  <Mask Filename="YOUR_MASK.em" Binning="1" isSphere="True"/>
  <SampleInformation PixelSize="XX_ANGSTROM" ParticleDiameter="XX_ANGSTROM"/>
  <ParticleListLocation Path="PARTICLE_LIST1.xml"/>
  <ParticleListLocation Path="PARTICLE_LIST2.xml"/>
</FRMJob>

Note not all the fields in this file need to be set. There are quite some parameters that are unused and exist only for historical reasons or compatibility to other parts in Pytom. If frm/createJob.py is used, you would be only required to enter the relevant ones.

Here all the fields can be or need to be set are explained here:

• Frequency: the starting frequency (in pixel) at which the alignment procedure would start.
• MaxIterations: the maximal iterations the alignment procedure would run.
• PeakOffset: the maximal spatial range (radius, in pixel) that the subtomogram would be shifted. This is necessary to prevent shifting the volume out-of-frame and reduce the search space.
• FSC: the Fourier shell correlation (FSC) criterion, typical choice would be: 0.5, 0.3 or 0.143 for gold standard approach.
• binning: A binning factor can be supplied to speed up calculations (1 or greater).
• AdaptiveResolution: the additional resolution that would be considered in the next iteration. For example, if in iteration 5th the resolution (in band) determined is 10 according to the chosen FSC criterion, we then calculate the information within 10 ∗ (1 + 0.1) = 11 band in 6th iteration. This parameter is useful to alleviate the noise bias and still let the alignment "see" more information in each round so that the local minimum is avoided.
• Reference/File: the file name of the reference.
• Mask/Filename: the file name of the mask. This will be applied to the reference in real space.
• SampleInformation/PixelSize: pixel size in angstrom.
• ParticleListLocation/Path: the path(s) to the particle list(s) of subtomograms, can have mutiple entities.

Additionally, after version 0.97 it is possible to apply constraints in the rotational space. There are three types of angle constraints available now:

• Fixed Angle Constraint: constrain the angular search around a specific angle. To enable that, add the following line into your job xml file.
  <AngularConstraint Type="Fixed Angle" Phi="0" Psi="0" Theta="0" Nearby="10" />
• Fixed Axis Constraint: constrain the angular search around a specific axis. To enable that, add the following line into your job xml file.
  <AngularConstraint Type="Fixed Axis" X="0.267261241912" Y="0.534522483825" Z="0.801783725737" Nearby="10" />
• Adaptive Angle Constraint: constrain the angular search around the angle stored in each particle (local sampling). To enable that, add the following line into your job xml file.
  <AngularConstraint Type="Adaptive Angle" Nearby="10" />

For 'reference-free' alignment, i.e., alignment without using a external reference, a random assignment of angular assignments of the respective particles can be generated easily using ParticleList.createDeNovoReference. This function generates an average from the particles using random orientations.

Subtomogram alignment using GFRMAlignment.py

This is the version with gold standard FSC, which means the dataset is randomly split into two half sets and aligned independantly. The resoluton is then determined by FSC between the averages from the two half sets. Although in the single particle field the suggested FSC criterion is 0.143, For alignment in electron tomography it would be better to set to 0.3 or 0.5, because this can prevent the determined frequency to jump too further at a time. In the end, you can still use 0.143 criterion to determine the final resolution.

As you can see, nothing much is different except to tell the program to run two independant alignments on one dataset. So is the job description file:

<FRMJob ...>
            ...
  <Reference PreWedge="" File="YOUR_REFERENCE1.em" Weighting="">
  <Reference PreWedge="" File="YOUR_REFERENCE2.em" Weighting="">
            ...
</FRMJob>

You have to give two references in the job file instead of one. These two references could be the same, or not. The way to call this script is identical to the one above except for the script name:

mpirun --hostfile "pathToYourHostfile" -c "numberOfCPUs" pytom PathToPytom/frm/GFRMAlignment.py -j job.xml -v

Subtomogram alignment using WienerFilterAlignment.py

This is the version with CTF correction using Wiener filter. For that you have to prepare two sets of particles: the phase flipped volumes and the CTF convoluted volumes. Currently PyTom does not have the functionality to prepare them for you. It has to be done yourself using whatever software you like. For the Wiener filter equation, please refer to the paper.

The job description file is still similar and looks like this:

<FRMJob ...>
            ...
   <ParticleListSet>
     <ParticleListPair PhaseFlippedParticleList='PARTICLE_LIST1.xml' CTFConvolutedParticleList='CONVOLUTED_DIR' CTFSquared='CTF_SQUARED_VOLUME.em' SNR='10'/>
     <ParticleListPair PhaseFlippedParticleList='PARTICLE_LIST2.xml' CTFConvolutedParticleList='CONVOLUTED_DIR2' CTFSquared='CTF_SQUARED_VOLUME2.em' SNR='10'/>
   </ParticleListSet>
            ...
</FRMJob>

As you can see, the difference is in the particle list part:

• PhaseFlippedParticleList: the particle list with phase flipped volumes.
• CTFConvolutedParticleList: the particle directory containing the CTF convoluted volumes. Note the naming of the particles should correspond to the phase flipped particle list. The redundant information is avoided so the directory is the only field should be specified.
• CTFSquared: the volume containing the sum of the squared CTFs.
• SNR: the estimated SNR value in this specific particle list. Normally set it to 10, which corresponds to the Wiener constant 0.1.

The call of this script is the same and omitted here.

Subtomogram alignment using GWienerFilterAlignment.py

This is the version with gold standard FSC and CTF correction. Its job file can be set analogously to the above one but with one more reference field.

Low level library and advanced usage

If you want to integrate this fast alignment algorithm into your own software, you can check out the low level library written in C and Python at this page. But please do not forget to cite the paper!

It contains some documentations and examples to use to help you understand. It should be quite straight forward to comprehend and adapt to your purpose. Most importantly, pay attention to the python function frm_align at sh_alignment.frm module, and the swig wrapper of C functions: sh_alignment.swig_frm.frm_corr or sh_alignment.swig_frm.frm_fourier_corr. The former is for finding the best translation and rotation between two volumes. And the latter is for computing the cross correlation of two spherical functions (real or complex).

If you have further questions, please email to: [email protected].