Real space alignment and averaging

Real space alignment and averaging GLocal

Overview

To obtain a coherent average from a set of subtomograms you have to iteratively determine the orientations and translations of all subtomograms ('alignment'). The alignment process can become time-consuming, depending on the number of subtomograms, their size, and the power of your computer setup (number of CPUs). Hence, subtomogram alignment is parallelized and typically performed on a CPU cluster.

Input parameters of ./bin/GLocalJob.py

The script bin/GLocalJob.py performs iterative quasi-expectation maximization alignment using constrained correlation. The rotational sampling is performed in real space (in contrast to FRM alignment!). A function call looks like this:

mpirun -n "numberOfCPUs" PathToPytom/bin/pytom PathToPytom/bin/GLocalJob.py -p MyParticleList.xml \
                         -r MyReference.em -m MyMask.em --SphericalMask --angleShells 3 \
                         --angleIncrement 3. --symmetry MyNSym --symmetryAngleZ -d ./ \
                         -n 10 -b 2 --pixelSize 2.7 --particleDiameter 250 

If you call the script without any arguments the following help will appear:

NAME
    GLocalJob.py
DESCRIPTION
    Create an GLocalSampling job. Documentation is available at
                          http://www.pytom.org/doc/pytom/alignment.html
OPTIONS
    -p, --particleList    Particle list : xml file storing information to all subvolumes (Is optional: No; Requires arguments: Yes)
    -r, --reference    Reference : the initial reference - if none provided average of particle list (Is optional: Yes; Requires arguments: Yes)
    -m, --mask    Mask : a mask  (Is optional: No; Requires arguments: Yes)
    --SphericalMask    Mask is spherical / speed up! (Is optional: Yes; Requires arguments: No)
    --angleShells    # angle shells used for angular refinement. Default= 3 (Is optional: Yes; Requires arguments: Yes)
    --angleIncrement    Angular increment for refinement. Default = 3 (Is optional: Yes; Requires arguments: Yes)
    --symmetry          PointSymmetry : specify n-fold symmetry (n) (Is optional: Yes; Requires arguments: Yes)
    --symmetryAngleZ    PointSymmetry axis tilt around Z axis (Is optional: Yes; Requires arguments: Yes)
    --symmetryAngleX    PointSymmetry axis tilt around X axis (Is optional: Yes; Requires arguments: Yes)
    -d, --destination    Destination : destination directory (Is optional: No; Requires arguments: Yes)
    -n, --numberIterations    Number of iterations (Is optional: No; Requires arguments: Yes)
    -b, --binning       Perform binning (downscale) of subvolumes by factor. Default=1. (Is optional: Yes; Requires arguments: Yes)
    --pixelSize         Pixelsize in Angstrom (Is optional: No; Requires arguments: Yes)
    --particleDiameter  Particle diameter in Angstrom (Is optional: No; Requires arguments: Yes)
    -w, --weighting     Weight particles by exp of CC (Is optional: Yes; Requires arguments: No)
    -c, --compound      Use compound weighting in Fourier space (Is optional: Yes; Requires arguments: No)
    -j, --jobName       Specify job.xml output filename (Is optional: No; Requires arguments: Yes)
    -g, --gpuID         Specify which gpu to use (Is optional: Yes; Requires arguments: Yes)
    -h, --help          Help. (Is optional: Yes; Requires arguments: No)
AUTHORS
    Friedrich Foerster

In more detail the options are the following:

• --particleList / -p. A particle list in XML format that points to all subtomograms. It contains the names of the subtomograms and other meta information, including their previously assigned orientations. In PyTom functions also exist to generate a particleList from a directory containing EM, MRC or CCP4 files that contains all subtomograms.
• --reference / -r. An initial reference. The reference may be an EM, MRC or CCP4 file. The reference can be the preleminary average from the roughly-aligned particles, an existing density or a density generated from a a PDB file. (For PDB files, you can use the pytom.basic.files.pdb2em function to obtain densities).
  The reference can also be omitted. The script will then use the average from the subtomograms using the translations and rotations specified in the particleList file.
• --mask / -m. A mask. The mask may be spherical or non-symmetrical. Default masks are spherical in PyTom. However, to focus alignment on a particular region, you may use a mask of aribtrary shape that will be rotated during alignment. A mask can be generated using PyTom following these instructions. Same formats as reference
• --SphericalMask. Switch for spherical masks. If set the alignment process is accelerated significantly.
• --angleShells. Number of angle shells used for angular refinement. Fig. 1 explains the angular sampling used for the orientation grid search. Default value is 3.
• --angleIncrement. Angular increment for refinement. of accuracy. For explanation of the sampling we refer to Fig. 1. Default value is 3.
  Note that the specified angleIncrement will be overruled by the increment determined by the adaptive sampling if this option is chosen. If you are not sure what increment to use for the alignment, you can estimate the increment with the angleFromResolution function. Type:

  $ipytom
  from pytom.basic.resolution import angleFromResolution
  
  print 0.1*angleFromResolution(30,250)
  

  Here, 30 is a hypothetical resolution in Angstrom and 250 is a particle diameter in Angstrom.
• --pixelSize. Pixelsize in Angstrom. If specified it will be used for resolution-dependent rotational sampling (see above for --angleIncrement.
• --particleDiameter. Particle diameter in Angstrom. If specified it will be used for resolution-dependent rotational sampling (see above for --angleIncrement.
• --destination / -d. Destination directory.
• , --numberIterations / -n. Number of iterations for alignment cycle.
• --symmetry. PointSymmetry. If specified n-fold rotational symmetry will be imposed on the average during the iterative alignment cycle.
• --symmetryAngleZ. PointSymmetry axis tilt around Z axis. If --symmetry is specified it will be applied along the Z-axis.
• --symmetryAngleX. PointSymmetry axis tilt around X axis. If --symmetry is specified it will be applied along the X-axis.
• --binning / -b. Perform binning (downscale) of subvolumes by factor. Binning > 1 greatly accelerates alignment, of course on the expense of accuracy. Default=1.
• --weighting / -w. Weight particles by exp of CC.
• --compound / -c. Use compound weighting in Fourier space. Makes most sense when parts of Fourier space are not sampled (non-isotropic particle distribution).
• --jobName / -j. Specify job.xml output filename.
• -g, --gpuID. index or indices of gpu's one wants to use. GLocal can run on multiple gpu's simultaneously. The indices of multiple gpu's are separated by a comma (no space). For example 0,2,3,4. Please note that the number of mpi cores should be one more than the number of GPUs you are using.

Fig. 1. Angular scanning. The angles Ψ (Z1) and Θ (X1) scanned around the old Ψ and Θ, whereby the old values act as a ‘pole’. Here the Angular Increment ΔΘ = 3 degrees and the Number of Shells N_shell = 2. That means the vector (Ψ, Θ) is rotated by ΔΘ = 3 two times (the visible rings). The increment along Ψ is chosen as ΔΨ = N_shell / sin(ΔΘ * i_shell), which accounts for the higher density of angles near the pole. The third Euler angle Φ (Z2) is scanned with a constant increment ΔΦ = ΔΘ from Φ_min = Φ_old - N_shell * ΔΘ to Φ_max = Φ_old + N_shell * ΔΘ.

Results of alignment

At this point the script is pretty talkative and writes out quite a lot for each iteration Iter:

• Iter-ParticleList.xml: Particle List containing the current translations and rotations, as well as the alignment score.
• Iter-ParticleListOdd.xml: Same for particles with odd indices.
• Iter-ParticleListEven.xml: Same for particles with even indices.
• Iter-FSC.dat: Fourier Shell Correlation between even and odd particles.
• Iter-Filter.dat: Radial filter derived from FSC.
• Iter-All.em: Current average from all particles.
• Iter-AllFiltered_XXX.em: Current average from all particles filtered with corresponding filter to XXX A resolution.
• Iter-Even.em: Average from even particles.
• Iter-EvenFiltered.em: Filtered average from even particles.
• Iter-EvenFiltered-PreWedge.em: Average from even particles before weighting according to Fourier sampling.
• Iter-EvenFiltered-WedgeSumUnscaled.em: Filter used for weighting even particles average.
• Iter-Odd.em: Average from odd particles.
• Iter-OddFiltered.em: Filtered average from odd particles.
• Iter-OddFiltered-PreWedge.em: Filtered average from odd particles.
• Iter-OddFiltered-WedgeSumUnscaled.em: Filter used for weighting odd particles average.
• Iter-GLocalAlignmentJob.xml: XML file for current alignment iteration