SUPALM manual

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
  • Introduction
  • Running supalm
    • Command-Line Arguments and Options
    • Runtime Output
  • supalm Input Files
  • supalm Ouput Files
• Examples
  • Command-line execution
  • Running supalm multiple times

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 10³ atoms). For large (e.g. 1 MDa, about 10⁵ 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:

where A and B correspond to model A and model B, A_lm(s) and B_lm(s) are the scattering amplitudes of model A and model B, I_A(s) and I_B(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:

SUPALM recognizes the following command-line options.

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.