Xmipp

xmipp_nma_alignment (v3.0)

Description

This is a method for iterative elastic 3D-to-2D alignment that computes elastic and rigid-body parameters of the alignment of single-particle images with a reference structure through reference-structure deformations along normal modes followed by its rigid-body alignment with images. The elastic parameters are deformation amplitudes along the normal modes and the rigid-body parameters are three Euler rotations and two in-plane shifts.

The reference structure can be of atomic resolution (e.g., solved by X-ray crystallography) or pseudo-atomic resolution (e.g., obtained by electron microscopy (EM) and converted into a network of Gaussian functions) and should be given in the PDB format.

The conversion from an EM volume into a network of Gaussian functions can be done either on the webserver 3DEM Loupe or with xmipp_volume_to_pseudoatoms ( 3DEM Loupe actually runs xmipp_volume_to_pseudoatoms, which provides the pseudo-atomic structure in the PDB format required by xmipp_nma_alignment and xmipp_mpi_nma_alignment).

The normal modes can be computed using the webserver ElNemo if the reference structure has an atomic resolution or using the webserver 3DEM Loupe if the reference structure is an EM volume.

By default, the rigid-body alignment is done using a combination of a “discrete” alignment (maximizing the cross-correlation between the experimental image and a discrete library of reference projections in wavelet space for a robustness to noise) and a “continuous” alignment (gradient-based optimization of the similarity between the experimental image and central slices of the reference structure in Fourier space, which is used for a fast refinement of an initial “discrete” alignment). The wavelet-space projection matching can optionally be replaced by a real-space projection matching.

Usage

Align images with an atomic or pseudo-atomic (from EM volume) structure by computing deformation amplitudes along normal modes, three Euler angles, and two in-plane shifts

Parameters

-i, --input <input_file>
Metadata with image filenames
--mode <mode=overwrite>
Metadata writing mode.
where <mode> can be:
  • overwrite Replace the content of the file with the Metadata
  • append Write the Metadata as a new block, removing the old one
--label <image_label=image>
Label to be used to read/write images.
-o, --output <output_file=>
Metadata with output Euler angles, shifts, and deformation amplitudes
--pdb <PDB_filename>
Reference atomic or pseudo-atomic structure in PDB format
--odir <outputDir.> =
Output directory
--resume
Resume processing

Generation of the deformed reference volumes

--modes <filename>
File with a list of mode filenames
--sampling_rate <Ts=1>
Pixel size in Angstroms
--filterVol <cutoff=15.>
Filter the volume after deforming. If this option is used, the default cut-off is 15 A.
--centerPDB
Center the PDB structure
--fixed_Gaussian <std=-1>
For pseudo-atoms fixed_Gaussian must be used. Default standard deviation is read from the PDB file.

Combined elastic and rigid-body alignment

--trustradius_scale <s=1>
Positive scaling factor to scale the initial trust region radius
--mask <m=>
2D masking of the projections of the deformed volume
--projMatch
Real-space instead of wavelet-space (default) projection matching (global matching) that is refined by local (Fourier central slice) projection matching Note that wavelet-based method needs the image size to be power of 2
--discrAngStep <ang=10>
Angular sampling step for computing the reference projections for global matching
--gaussian_Fourier <s=0.5>
Sigma of Gaussian weigthing in Fourier space (parameter of central-slice method)
--gaussian_Real <s=0.5>
Sigma of Gaussian weigthing in real space for spline interpolation in Fourier space (parameter of central-slice method)
--zerofreq_weight <s=0.>
Zero-frequency weight (parameter of central-slice method)

Using the command with atomic-resolution reference structure

This is an example of running the method on a series of images (listed in selimg.sel) using a reference structure in PDB format (reference.pdb) that is centered (--centerPDB), modes listed in modelist.txt, pixel size of 3 Angstroms (--sampling_rate 3), angular step of 10 (--discrAngStep 10) for computing a discrete library of reference projections, and writing the results in output.txt.

mpiexec.hydra -machinefile $XMIPP_MACHINEFILE -np 8 ~/xmipp/bin/xmipp_mpi_nma_alignment -i selimg.sel --pdb reference.pdb --modes modelist.txt  --sampling_rate 3 --discrAngStep 10 -o output.txt --centerPDB

In this example, we used MPI-parallelized version of the method to dispatch the jobs on 8 cores (-np 8) listed in the text file specified by the environment variable $XMIPP_MACHINEFILE (-machinefile $XMIPP_MACHINEFILE). Note that depending on your MPI version (e.g., if you use mpirun or mpiexec), you will have to adapt the first part of the command (mpiexec.hydra -machinefile $XMIPP_MACHINEFILE -np 8). Also, you have usually to provide the full path to the executable xmipp_mpi_nma_alignment (~/xmipp/bin/xmipp_mpi_nma_alignment). Here is how the required files should look like:

modelist.txt - List of text files containing the normal modes to be used (3-column text files). Here, we give an example of the file containing 2 modes:

# XMIPP_STAR_1 *
#
data_
loop_
 _NMAModefile
../../modes_columns/mod0011          1
../../modes_columns/mod0012          1

selimg.sel - List of images to analyze. Here, we give an example of the beginning of a file:

# XMIPP_STAR_1 *
#
data_noname
loop_
 _image
 _enabled
images_simulated/img_pop1_000001.xmp          1
images_simulated/img_pop1_000002.xmp          1
images_simulated/img_pop1_000003.xmp          1
images_simulated/img_pop1_000004.xmp          1
images_simulated/img_pop1_000005.xmp          1
…
…

Here is how the output file should look like:

output.txt – Columns before quotation marks: image name (1st), enabled (2nd), Euler angles (3rd-5th), in-plane shifts (6th-7th). In quotation marks: as many deformation amplitudes as the number of modes. Last column is the measure of the alignment quality. Here, we give an example of the beginning of a file from an experiment with 2 modes:

# XMIPP_STAR_1 *
#
data_noname
loop_
 _image
 _enabled
 _angleRot
 _angleTilt
 _anglePsi
 _shiftX
 _shiftY
 _nmaDisplacements
 _cost
images_simulated/img_pop1_000004.xmp          1   -16.630944   -50.722823    19.072670    -2.027733    -2.121395 '  -246.744000    54.542600 '     0.096851
images_simulated/img_pop1_000003.xmp          1    -5.324611   -13.784008    16.925189     2.256479    -1.727479 '   252.391000    53.157900 '     0.156012
images_simulated/img_pop1_000005.xmp          1    -1.604509    31.749473    -0.143788    -4.124537    -4.483128 '  -305.762000   293.316000 '     0.025739

Using the command with pseudoatomic reference structure

In case of a pseudo-atomic reference structure, the command to launch xmipp_mpi_nma_alignment differs from the one for an atomic-resolution structure only in using the flag --fixed_Gaussian (that was not used with the atomic reference structure) and in not using the flag --centerPDB. Here is an example of the command using the reference structure with Gaussian functions whose standard deviation is 2 (--fixed_Gaussian 2). The standard deviation of the Gaussian functions is given by the user at the time the volume is converted into Gaussian-type pseudo-atoms.

mpiexec.hydra -machinefile $XMIPP_MACHINEFILE -np 8 ~/xmipp/bin/xmipp_mpi_nma_alignment -i selimg.sel --pdb reference.pdb --modes modelist.txt  --sampling_rate 3 --discrAngStep 10 -o output.txt --fixed_Gaussian 2

The easiest is to compute the pseudo-atomic structure with the 3DEM Loupe webserver that runs the code of xmipp_volume_to_pseudoatoms, and at the same time allows computing the normal modes for the structure.

Here is how the pseudo-atomic PDB-format file should look like:

REMARK xmipp_convert_vol2pseudo
REMARK fixedGaussian 2.000000
REMARK intensityColumn Bfactor
ATOM      1 DENS DENS    1      36.000  33.000 -58.350     1  0.20      DENS
ATOM      2 DENS DENS    2     -91.350  22.500  49.650     1  0.26      DENS
ATOM      3 DENS DENS    3     -58.050   0.000 -81.000     1  0.19      DENS
ATOM      4 DENS DENS    4     -25.500  94.500  -7.500     1  0.17      DENS
ATOM      5 DENS DENS    5      13.650  34.500  10.500     1  0.29      DENS
ATOM      6 DENS DENS    6      82.650  34.650 -28.350     1  0.28      DENS
….
….

The remark “fixedGaussian 2.000000” means that the Gaussian functions have the standard deviation of 2. The remark “intensityColumn Bfactor” means that the amplitude of each Gaussian functions are written in the Bfactor column of the PDB-format file, which is mandatory for the elastic 3D-to-2D alignment method.

Note on the trust region radius of the powell trust-region method

The radius of the trust region is a typical distance between successive points at which the objective function is evaluated. The radius is reduced automatically as soon as the objective function stops decreasing. The method is initialized by specifying the initial deformation amplitudes (they are set to zero which corresponds to the non-deformed reference structure) and the initial trust region radius (set to 250) and the final trust region radius (set to 0.5). The initial trust region radius can be scaled by specifying the scaling factor on the command line using --trustradius_scale(a default value of the scaling factor is 1).

Here is an example of using the scaling factor of 1.5 for an atomic structure:

mpiexec.hydra -machinefile $XMIPP_MACHINEFILE -np 8 ~/xmipp/bin/xmipp_mpi_nma_alignment -i selimg.sel --pdb reference.pdb --modes modelist.txt  --sampling_rate 3 --discrAngStep 10 -o output.txt --trustradius_scale1.5 --centerPDB

and, for a pseudo-atomic structure:

mpiexec.hydra -machinefile $XMIPP_MACHINEFILE -np 8 ~/xmipp/bin/xmipp_mpi_nma_alignment -i selimg.sel --pdb reference.pdb --modes modelist.txt  --sampling_rate 3 --discrAngStep 10 -o output.txt --fixed_Gaussian 2 --trustradius_scale1.5

Examples and notes

xmipp_nma_alignment -i images.sel --pdb 2tbv.pdb --modes modelist.xmd --trustradius_scale 1.2 --sampling_rate 3.2 -o output.xmd --resume

User's comments

%COMMENT{type="tableappend"}%