SUPCOMB manual

Written by M.B. Kozin., updated by D. Franke and P.Konarev
Post all your questions about SUPCOMB to the ATSAS Forum.

© ATSAS Team, 2000-2016

Table of Contents

• Manual
  • Introduction
  • Running supcomb
    • Command-Line Arguments and Options
    • 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 (2001) 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. Please note: there used to be two versions of SUPCOMB, named supcomb13 and supcomb20, implementing slightly different matching algorithms. The two separate programs got merged into a single SUPCOMB program.

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:

$ supcomb [OPTIONS] <FILE> <FILE>

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

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

Command-Line Arguments and Options

SUPCOMB requires the following command line arguments:

SUPCOMB 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:

$ supcomb --mode=slow --enantiomorphs=yes t01.pdb t02.pdb -o t02moved.pdb
 Read file .............................................. : t01.pdb
 Number of atoms ........................................ : 346
 Fineness of the structure .............................. : 2.888
 Read file .............................................. : t02.pdb
 Number of atoms ........................................ : 346
 Fineness of the structure .............................. : 2.654

                                Initial       Final
              Orientation      Distance    Distance
             1     1     1       1.8697      1.8068
             1     1    -1       1.8335      1.7153
             1    -1     1       2.0625      1.5156
             1    -1    -1       2.0227      1.5015
            -1     1     1       1.8634      1.7839
            -1     1    -1       1.8863      1.7393
            -1    -1     1       2.0400      1.4981
            -1    -1    -1       2.0712      1.5049

                   Transformation matrix
        -0.4293      0.2710     -0.8615     -1.1607
         0.8808      0.3366     -0.3330      0.0271
         0.1997     -0.9018     -0.3832      0.1303
         0.0000      0.0000      0.0000      1.0000

 Wrote file ............................................. : t02moved.pdb

Here, Initial and Final distances are the NSD values before and after the minimization. The transformation matrix gives the final rotation and translation of the second input file onto the template.

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.

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.

$ supcomb file1.pdb file2.pdb

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

Examples

Command-line execution

Use SUPCOMB to align a dummy atom model on a crystal structure, using options to select the superposition mode and allow the use of enantiomorphs:

$ supcomb --superposition=backbone --enantiomorphs=yes 6lyz.pdb ly01-1.pdb

Running supcomb Multiple Times

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

$ for i in `seq 1 10` ; do supcomb 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 supcomb 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.