EMBL Hamburg Biological
Small Angle Scattering

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


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.


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


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

FILE The template PDB file.
FILE The structure to superimpose onto the template.

SUPCOMB recognizes the following command-line options.

Short OptionLong OptionDescription
-m --mode=<MODE> Algorithm selection. MODE may be either slow (the default) or fast. Here, the slow mode correponds to the implementation of SUPCOMB13 while the fast mode correpsonds to SUPCOMB20.
--superposition=<S> 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.
-p --proximity=<NSD|VOL> This option specifies the metric for the proximity measure between two models. It can be the standard normalized spatial discrepancy ('NSD') metric or the overlapped volume ('VOL') metric. The latter metric can be applied for large macromolecular complexes (with MW about 1MDa or larger) in order to speed up the calculations (for details see the SUPALM article). By default the proximity metric is set to 'NSD'.
-f --fraction=<VALUE> This option specifies the part of the structure closer to the surface to take for calculations with the 'NSD' metric. It can be set between 0 and 1 (in the latter case the whole structure will be taken into account). The lower fraction can be applied for large macromolecular complexes (with MW about 1MDa or larger) in order to speed up the calculations (for details see the SUPALM article), but it is recommended to set it higher than 0.3. By default the fraction is set to 1.0.
-s --symmetry Specify the symmetry to enforce on the structures during superposition. All standard P-n-m symmetries are supported (Pn, n=1, ..., 19, Pn2, n=2, ..., 12) as well as P23, P432 and PICO (default: P1). Please note: symmetry constraints are only applied in slow mode.
-q --quiet If enabled, informational console output is suppressed. Only errors, if any, will be printed.
-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:

$ 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.


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.

  Last modified: April 11, 2013

© BioSAXS group 2013