SUPCOMB manual

Written by M.B. Kozin.
Post all your questions about SUPCOMB to the ATSAS Forum.

© ATSAS Team, 2000-2009

Table of Contents

• Manual
  • Introduction
  • Running supcomb
    • Command-Line Arguments and Options
    • Interactive Configuration
    • Runtime Output
  • supcomb Input Files
  • supcomb Ouput Files
• Examples
  • Command-line execution
  • Running supcomb multiple times

Manual

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

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

M.Kozin & D.Svergun (2000) Automated matching of high- and low-resolution structural models J Appl Cryst. 34, 33-41.

Introduction

SUPCOMB, is a program to superimpose one 3D structure onto another. These structures can be low-resolution bead models and/or high resolution NMR or x-ray crystal structures. The alignment of shape models (ie. *.flm files) is not supported. There are two versions, supcomb13 and supcomb20. Supcomb13, the original algorithm, is quite slow but generates highly accurate superposition/alignment of structures. Supcomb20 is a modification of supcomb13 providing a more rapid superposition/alignment of structures, at the expense of accuracy.

The program represents each input structure as an ensemble of points, then minimizes a normalized spatial discrepancy (NSD) to find the best alignment of two models. NSD is a measure of quantitative similarity between sets of three-dimensional points and is calculated in the following way:

Briefly, if two three-dimensional models are represented as a set of points, for every point in the first set (model 1), the minimum value among the distances between this point and all points in the second set (model 2) is found, and the same is done for the points in the second set. These distances are added and normalized against the average distances between the neighboring points for the two sets.

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

Please refer to the paper cited above for further details about the implemented algorithm.

Running supcomb

Usage:

$> supcomb13 [[file1.pdb] [file2.pdb] [OPTIONS]]

or

$> supcomb20 [[file1.pdb] [file2.pdb] [OPTIONS]]

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

OPTIONS known by supcomb13 and supcomb20 are described in the next section.

The options can be used in both the interactive prompt driven mode or specified as additional arguments on the command line. These options define the atoms used for superposition, the use of enantiomorphs and symmetry.

If no PDB files are given, the configuration is done in full interactive mode.

Command-Line Arguments and Options

SUPCOMB accepts the following command line arguments:

SUPCOMB13 recognizes the following command-line options.

SUPCOMB20 recognizes the following command-line options.

Interactive Configuration (Dialog mode)

Settings available through command-line arguments and options may also be configured interactively as shown in the table below. Otherwise these questions are skipped. Additional options such as specifying an output file name are only possible in the dialog mode.

SUPCOMB13 interactive prompt:

SUPCOMB20 interactive prompt:

Runtime Output

On runtime, the following lines of output will be generated for each target structure to superimpose on a template structure (shown here is the output from supcomb13):

 Symmetry: P1...19 or Pn2 (n=1,..,12)
 Number of atoms read ................................... : 466
 Fineness of the template ............................... : 1.376
 Number of atoms read ................................... : 461
 Fineness of the superimposed structure ................. : 1.376

  Principal axes orientation table

    Distance                       Orientation

   1.0264211519834452               -1          -1           1
   1.4283814285877037               -1           1           1
   1.5154308566171697               -1           1          -1
 ---------------------------------------------
   1.5406517702348419               -1          -1          -1
   1.5439152636084770                1           1           1
   1.5478430395599114                1           1          -1
   1.5555092696290600                1          -1           1
   1.5958197428534753                1          -1          -1
 Distance after inertia-axes alignment .................. : 1.026
 Distance after inertia-axes alignment .................. : 1.428
 Distance after inertia-axes alignment .................. : 1.515
 Distance after inertia-axes alignment .................. : 1.541
 Distance after inertia-axes alignment .................. : 1.544
 Distance after inertia-axes alignment .................. : 1.548
 Distance after inertia-axes alignment .................. : 1.556
 Distance after inertia-axes alignment .................. : 1.596

  Final results:
  ==============

 No.   Initial      Final        Orientation
  1    1.02642    0.95001    -1    -1     1
  2    1.42838    1.40437    -1     1     1
  3    1.51543    1.39922    -1     1    -1
  4    1.54065    1.51658    -1    -1    -1
  5    1.54392    1.46192     1     1     1
  6    1.54784    1.52985     1     1    -1
  7    1.55551    1.39574     1    -1     1
  8    1.59582    1.51903     1    -1    -1
  --- Transformation matrix ---
   0.846136  -0.476294  -0.239161  34.244589
   0.402205   0.865066  -0.299820   4.055922
   0.349692   0.157497   0.923531 -15.292198
   0.000000   0.000000   0.000000   1.000000

The above output can be interpreted as follows:

The output for running supcomb20 contains the same information, without symmetry and in a slightly different format.

supcomb Input Files

SUPCOMB 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 both command-line and dialog modes.

supcomb Output Files

Following a successful superposition, SUPCOMB 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. supcomb13 file1.pdb file2.pdb, yields file2r.pdb as output. There is no command-line option to generate an output file name, however, this can be specified in the dialog mode and a PDB file is generated with the given name.

Examples

Command-line execution

Use SUPCOMB to obtain an alignment/superposition of two 3D structures, using options to define the mode (all atoms:0, or backbone atoms only:1) and allow the use of enantiomorphs:

$> supcomb13  lyz.pdb bsa.pdb /m 1 /e y 

or

$> supcomb20  lyz.pdb bsa.pdb /e y 

Running supcomb Multiple Times

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

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

or

$> for i in `seq 1 10` ; do supcomb20 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 supcomb13 $file template.pdb; 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.