0
EMBL Hamburg Biological
Small Angle Scattering
BioSAXS

SUPALM manual

supalm

Written by P.V. Konarev, M.V. Petoukhov and D.I. Svergun
Post all your questions about SUPALM to the ATSAS Forum.

© ATSAS Team, 2006-2016

Table of Contents

Manual

The following sections shortly describe the method implemented in SUPALM, how to run SUPALM from the command-line on any of the supported platforms, describe the required input and the produced output files .

If you use results from SUPALM in your own publication, please cite:

P.V.Konarev, M.V.Petoukhov and D.I.Svergun (2016) Rapid automated superposition of shapes and macromolecular models using spherical harmonics. J Appl Cryst. 49, 953-960.

Introduction

SUPALM, is a program to superimpose one 3D structure onto another using spherical harmonics representation. These structures can be low-resolution bead models and/or high resolution NMR or x-ray crystal structures. Supalm supprots also the input of electron microscopy density (EMD) maps (similar to EM2DAM) and multiphase ab initio (MONSA) models, they can be overlapped with pdb structures. The alignment of shape models (ie. *.flm files) is not supported.

The program uses the algorithm for a fast matching of large macromolecular models in Fourier space. It is based on the spherical harmonics representation of the scattering amplitudes and uses a Normalized Correlation Coefficient (NCC) of the scattering amplitudes calculated by CRYSOL or DAM2ALM as a proximity measure between 3D objects. The program maximizes this coefficient (NCC) to find the best alignment of two models.

The performance of the proposed algorithm is tested on a number of high and low-resolution models, and the aligned configurations are in a good agreement with SUPCOMB results. The computing time of SUPALM is comparable to that of SUPCOMB for protein models with molecular weights lower than 100 kDa (represented by about 103 atoms). For large (e.g. 1 MDa, about 105 atoms) macromolecular complexes SUPALM performs ten times faster than SUPCOMB.

For ideally superimposed similar objects, NCC tends to 1; it decreases towards 0 if the objects systematically differ from one another.

The normalized correlation coefficient (NCC) is calculated as follows:

NCC(A,B) = \frac{\int_0^{Sm} [ A_{lm}(s) B_{lm}^{*} + A_lm(s)^(*) B_lm ] (s) s^2 \mathrm{d}s}{2 \left( \int_0^{Sm} I_{A}(s) s^2 \mathrm{d}s \right)^{\frac{1}{2}} \left( \int_0^{Sm} I_{B}(s) s^2 \mathrm{d}s \right)^{\frac{1}{2}} }

where A and B correspond to model A and model B, Alm(s) and Blm(s) are the scattering amplitudes of model A and model B, IA(s) and IB(s) are the scattering intensities from model A and model B.

Running supalm

Usage:

$ supalm [OPTIONS] <FILE> <FILE>

SUPALM accepts absolute as well as relative paths to the template and target PDB files.

SUPALM does not provide an interactive mode but is completely configurable through its command line options. The OPTIONS known by SUPALM are described in the next section.

Command-Line Arguments and Options

SUPALM requires the following command line arguments:

ArgumentDescription
FILE The template PDB file. PDB file, ab initio envelop (DAMMIN/F or MONSA model) or EMD map are supproted.
FILE The structure to superimpose onto the template. PDB file, ab initio envelop (DAMMIN/F or MONSA model) or EMD map are supproted.

SUPALM recognizes the following command-line options.

Short OptionLong OptionDescription
-m --mode=<ALL|BACKBONE> Selection of atoms to superimpose. Either only the BACKBONE atoms, or ALL (the default).
-e -enantiomorphs=<YES|NO> Enable/disable the search of enantiomorphs, i.e. either one of a pair of molecules that are mirror images of each other but are not identical. By default this is enabled.
-prog1 --prog1=<CRYSOL|DAM2ALM> Selection of the program to calculate the scattering amplitudes for the template PDB model. Either crysol (the default) or dam2alm.
-prog2 --prog2=<DAM2ALM|CRYSOL> Selection of the program to calculate the scattering amplitudes for the superimposed target PDB model. Either dam2alm (the default) or crysol.
-phase1 --phase1=<FILE> If the template PDB model is obtained by MONSA (for each atom it should contain information about the phase assignment), one can specify the densities of each phase for MONSA template model. The information is provided in a file with special format. If it is not specified, MONSA model will be treated as a normal homogeneous ab initio model.
-phase2 --phase2=<FILE> If the superimposed PDB model is obtained by MONSA (for each atom it should contain information about the phase assignment), one can specify the densities of each phase for MONSA superimposed model. The information is provided in a file with special format. If it is not specified, MONSA model will be treated as a normal homogeneous ab initio model.
-lm --lm=<NN> Maximum order of harmonics (min = 1, max = 20) used for the calculation of scattering amplitudes. Default value (lm=5) should be sufficient in most of the cases. For large particles high orders could improve the results, but more CPU time is required. Fractional values are not allowed. Default value is set to 5.
-ns --ns=<NN> Number of points for the s-axis of the scattering amplitudes (max = 5000). Default value is 51.
-sm --sm=<VALUE> Maximum scattering vector in reverse Angstroms (max = 1.0 Å-1) for calculating the scattering amplitudes up to sm. Default value is automatically defined as 7*PI/Dmax, that corresponds to seven Shannon channels, where Dmax is the maximum size of the template particle (in Angstroems). Default value should be sufficient in most of the cases, however the user can explicitly set the value for sm.
-norient --norient=<NN> Number of orientations to test. Default value is automatically determined from the alignment along principal axes or can be explicitly defined by the user. Maximum number of orientations is 8 if enantiomorphs are allowed (4 if enantiomorhps are disabled).
-t --t=<VALUE> The threshold density value for electron microscopy density (EMD) maps. Default value is calculated as the average between the minimum and maximum density values read from the EMD file. The coordinates that have the densities lower than the threshold value are discarded from the calculations.
-o -output=<FILE> Specify an output FILE where to write the moved and rotated model to. By default this corresponds to the basename of the second file plus r.pdb. See also below.
-v --version Print version information and exit.
-h -help Print a summary of arguments and options and exit.

Runtime Output

On runtime, the following lines of output will be generated for each target structure t02.pdb to superimpose on the template t01.pdb:

$  supalm t01.pdb t02.pdb -e YES -m ALL -lm 15 -ns 51 -sm 0.5 -norient 8 -o t02moved.pdb
 Read file ...............................................: t01.pdb
 Number of atoms read ................................... : 338
 Fineness of the template ............................... : 3.798
 Read file ...............................................: t02.pdb
 Number of atoms read ................................... : 577
 Fineness of the superimposed structure ................. : 4.341

  Principal axes orientation table

    Distance                       Orientation

   1.1768204423733173                1          -1          -1
   1.2345581133369878               -1          -1          -1
   1.2689868820531531               -1          -1           1
   1.2898764965376450                1          -1           1
   1.4664773466136298               -1           1          -1
 ---------------------------------------------
   1.4938459912827819                1           1           1
   1.5012877562245708                1           1          -1
   1.5239802046821627               -1           1           1
 Calculating amplitudes from t01.pdb
 Calculating amplitudes from t02.pdb
                                Initial       Final
              Orientation   Correlation Correlation
              1    -1    -1     0.56258     0.63237
             -1    -1    -1     0.49287     0.59316
             -1    -1     1     0.52195     0.62380
              1    -1     1     0.51471     0.61430
             -1     1    -1     0.41334     0.57261
              1     1     1     0.45890     0.59264
              1     1    -1     0.41398     0.61490
             -1     1     1     0.45944     0.52881
 Final distance (NSD) =    1.1591346523465229
 Wrote file ..........:    t02moved.pdb

Here, Initial and Final normalized correlation coefficients are the NCC values before and after the minimization. The final distance (normalized spatial discrepancy) NSD is given. The transformation matrix (written in the header of the output file) gives the final rotation and translation of the second input file onto the template.

supalm Input Files

SUPALM requires two PDB files as input. A template structure and a target structure for alignment/superposition. The use of absolute and relative paths to the template and target PDB files is supported. In the case of MONSA models, the densities of each phase can be specified in a separate con file with the following format:

4
1.0 2.0 1.0 2.0

First line means the number of phases in MONSA model, the second line contains the density values for each phase. An example above is made for 4-phase 70S ribosome MONSA model where phases 1 and 3 correspond to protein parts of the ribosome, and phases 2 and 4 - to RNA parts.

supalm Output Files

Following a successful superposition, SUPALM creates a single output file for the superimposed target structure. By default the output filename is taken from the input target structure but is appended with 'r', eg.

$ supalm file1.pdb file2.pdb

yields file2r.pdb as output. A different filename can be specified with the -output option.

Examples

Command-line execution

Use SUPALM to obtain an alignment/superposition of a dummy atom model on a crystal structure, using options to select the atom reading mode (backbones only) and allow the use of enantiomorphs:

$ supalm --mode=backbone --enantiomorphs=yes 6lyz.pdb ly01-1.pdb

Running supalm with EMD maps

Use SUPALM to obtain an alignment/superposition of EMD map with the pdb structure, the threshold density value for EMD map can be set explicitly using '-t' option.

$ supalm 4UIS.pdb EMD-2974.map -t 0.04

Running supalm with multiphase abinitio MONSA models

Use SUPALM to obtain an alignment/superposition of a multiphase MONSA model with the pdb structure. The densities for each phase of the MONSA model can be set explicitly using '-phase2' option.

$ supalm 4V4W.pdb ribosome_monsa.pdb --phase2=monsa2.con

Running supalm Multiple Times

To superimpose 10 structures onto a single template, on linux, in bash syntax:

$ for i in `seq 1 10` ; do supalm template.pdb file-$i.pdb; done

If one has unnumbered files to superimpose, on linux, in bash syntax:

$ for file in  "a.pdb b.pdb c.pdb d.pdb" ; do supalm template.pdb $file; done

where template.pdb is the reference/template structure.

Note that when one has a large collection of structures for superposition, the program DAMAVER is optimised for a fast superposition of multiple structures, automatically choosing the most representative structure.


  Last modified: October 5, 2015

© BioSAXS group 2015