Structural Bioinformatics Library
Template C++ / Python API for developping structural bioinformatics applications.
User Manual

Authors: F. Cazals and T. Dreyfus


Goals: Interfaces and interactions within macro-molecular complexes

We consider a structure (molecule, complex) decomposed into units. A unit may be a polypeptide chain, a domain, a set of residues, etc. Our focus is on interactions between these units, and we ascribe such interactions to two categories, referred to as geometric interactions/interfaces and biochemical interactions/interfaces.

Geometric interactions/interfaces. Such interfaces typically correspond to non-covalent interactions between atoms ascribed to units. Typical cases where such interfaces are of interest are:

  • Given the asymmetric unit of a crystal structure, report the pairwise interfaces observed.
  • Given a protein complex, be it a homomer or a multimer, report the contact between the domains of the proteins involved.

For each geometric interface between two units, high level information is provided, including (i) the number of particles involved at each interface, (ii) tThe number of connected components i.e. patches of each interface. These pieces of information provide a first indication on the various contacts between the molecules in presence, e.g. to select interfaces to further investigate using the applications of Space_filling_model_interface from Space_filling_model_interface .

For protein - protein interfaces, the number of interface atoms contributed by a sub-unit strongly correlates with the interface area (measured by the buried surface area), each atom contributing on average 10 squared Angstroms [68].

Biochemical interactions/interfaces. The focus here is on more local interactions between units, such as disulfide bonds and ionic interactions–see the package Pointwise_interactions.

Applications provided. The applications $ \text{\bifEC} $ and $ \text{\bifED} $, for Binary Interfaces Finder.

Using BIF: analysis between chains of a molecule

This section presents the program $ \text{\bifEC} $, which deals with the case where one unit refers to one polypeptide chain.

Pre-requisites for geometric interfaces

Contacts. Consider a model in a PDB file, consisting of chains made of particles. We assume (details below), that each particle has been assigned a primitive label, as defined in the concept MolecularSystemLabelsTraits. For the program $ \text{\bifEC} $, there is one primitive label per chain, without any hierarchy.

Consider the $ \alpha $-complex of the solvent accessible representation of the particles of the model–see package Alpha_complex_of_molecular_model.

Our focus is on contacts, which are of two types, bicolor and mediated. In the sequel, we briefly recall the definitions of these concepts, and refer the reader to the package Space_filling_model_interface for more details.

An edge in the alpha complex defines a bicolor contact provided that its endpoints carry two different primitive labels. To define a mediated contact, consider a mediator particle sandwiched between two particles with different primitive labels (i.e, there is an edge from both partners' particles to the mediator's particle). Such a particle induces two mediated contacts, one with each particle carrying a primitive label – see Fig. fig-bif-mediated-contact.

Interfaces. The contacts between partners are edges of the $ \alpha $-complex: these edges have a dual face termed Voronoi tile in the associated Voronoi diagram called. The set of all Voronoi tiles involving only bicolor (resp. mediated) contacts is called the bicolor (resp. mediated) interface . The union of bicolor and mediated interfaces of two given partners defines the tricolor interface , plainly called interface if there is no ambiguity.

The program $ \text{\bifEC} $ collects all bicolor and mediated contacts in a molecular structure, and groups them by interface. For each interface, two parameters are reported: first, the number of particles involved, and second, the number of connected components.

Voronoi interfaces: bicolor and mediated.

This fictitious molecular structure involves two partners A (red) and B (blue) and two water molecules (gray). A and B make one bicolor contact; the water molecule $ w_1 $ makes two mediated contacts.

Input: Specifications and file types

Running $ \text{\bifEC} $ requires only one input file, that is the input PDB file. Note that $ \text{\bifEC} $ works with water molecules that are loaded by default: removing them is done using the options –no-water . The following command runs $ \text{\bifEC} $ over the immunoglobulin-antigen complex 1vfb :

sbl-bif-chainsW-atomic.exe -f data/1vfb.pdb --directory results --verbose --output-prefix --log
The main option of the program $ \text{\bifEC} $ is:
-f string: PDB file of the input molecule

Note that a default radius of $ 1.4 \AA $ is added to all atoms to define the Solvent Accessible Model of the input molecule.

File Name


1vfb pdb file

Immunoglobulin-antigen complex

Input files for the run described in section Input: Specifications and file types .

Output: geometric interfaces

PreviewFile Name


General: log file

Log file

Log file containing high level information on the run of $ \text{\bifEC} $

Module BIF: binary interfaces graph

Interfaces Graph xml file

XML archive containing the serialized binary interfaces graph

Click it Interfaces Graph dot file

dot file for visualizing the binary interfaces graph using Graphviz

Output files for the runs described in section Input: Specifications and file types, classified by modules – see Fig. fig-bif-workflow .

For visualizing the Interfaces Graph, we recommend you to install Graphviz (see the Graphviz web site), and using the circo software for drawing the graph from a .dot file. Note that there are other software from the Graphviz library for drawing the graphs with different embedding.

Binary Interfaces Graph of the signalosome (4D10-COP9).

(left) The complex contains 16 chains (right) the binary interfaces graph where interfaces with less than 15 atoms were removed.

Output: biochemical annotations

The command $ \text{\bifEC} $ also calls the functionalities from the package Tertiary_quaternary_structure_annotator, so as to report a number of specific interactions between regions in a structure or complex, such as:

  • salt bridges,
  • disulfide bonds,
  • other covalent interactions.

Figure fig-1igt-example illustrates the result of the following calculation on a complete antibody, so as to illustrate the disulfide bonds found between the four chains. For a more complex example involving the decomposition of a chain into regions called units, the user is referred to the package Tertiary_quaternary_structure_annotator .

sbl-bif-chainsW-atomic.exe -f data/1igt.pdb --directory results --verbose -p 1 --internal 

Biochemical annotations for a complete immunoglobulin (PDB:1igt).

(left) The structure involves four chains. Note in particular the 3 disulfides bonds connecting the two heavy chains (right) The graph produced, with edges counting disulfide bonds and salt bridges. Note that there is a total of 17 / 17 S-S bonds and 18 salt bridges.

Using BIF: analysis between units of a molecule

This section presents the program $ \text{\bifED} $, which deals with the case where one unit refers to a set of residues in a protein.


For the program $ \text{\bifED} $, the labels are defined from the class SBL::Models::Domain_label_traits, which allows a user to specify his own labels. These labels typically define domains within a protein.

Using the specification file, one can define a template dissecting a chain into domains–or other segments, resulting in one primitive label for each segment. This template can be used for several chains, resulting in a hierarchy of labels for each chain.

An example of such template file is found in Table table-bif-domains-input-files. See also the class SBL::Models::Domain_label_traits of the concept MolecularSystemLabelsTraits for the detailed specification of such labels.

If one defines an incomplete template that is attributed to a chain, i.e there are atoms of this chain that are not included in any domain defined by the template, the atoms are attributed to the chain. This may lead to uncontrolled behaviors: an extra virtual domain representing all the remaining atoms of a chain should always be defined.

Input: Specifications and file types

Running $ \text{\bifED} $ requires two input files: the input PDB file, and the labels specification file. The following command runs $ \text{\bifED} $ over the homotrimer secret-C_elegans-EFF-1, dividing its three chains onto their domains:

sbl-bif-domainsW-atomic.exe -f data/secret-C_elegans-EFF-1.pdb --domain-labels data/secret-C_elegans-EFF-1-partners.txt --directory results --verbose --output-prefix --log
The main options of the program $ \text{\bifED} $ are:
-f string: PDB file of the input molecule
–domain-labels string: file specifying the domains of the input molecule

File Name


secret-C_elegans-EFF-1 pdb file


secret-C_elegans-EFF-1 labels file

Specification file defining the domains of molecules in secret-C_elegans-EFF-1.pdb

Input files for the run described in section Input: Specifications and file types .

Output: binary interfaces graph

PreviewFile Name



Log file

Log file containing high level information on the run of $ \text{\bifED} $


Interfaces Graph xml file

XML archive containing the serialized binary interfaces graph

Click it Interfaces Graph dot file

dot file for visualizing the binary interfaces graph using Graphviz

Output files for the runs described in section Output: binary interfaces graph .

Output: biochemical annotations

Annotations are identical to those reported in the case of chains, see Output: biochemical annotations , except that the nodes of the graph reported correspond to domains, as specified by the user.

Visualization, plugins, GUIs

The SBL provides VMD and PyMOL plugins to use the programs of Space_filling_model_interface_finder . The plugins are accessible in the Extensions menu of VMD or in the Plugin menu of PyMOL . Upon termination of a calculation launched by the plugin, the following visualizations are available:

  • A graph, called the Binary Interfaces Graph, representing the binary interfaces found:

    • each vertex of this graph is embedded at the center of mass of the atoms of its corresponding label,
    • each edge of this graph is decorated by the number of atoms involved in the interface, and also by the number of connected components of the corresponding interface.

Algorithms and methods


Using the notions of bicolor and mediated contacts recalled in the section Pre-requisites for geometric interfaces, assume that

  • each particle of the partners has been attributed a primitive partner's label
  • water molecules sandwiched between any pair of partners have been identified.

The applications perform two tasks:

  • First, for each primitive tricolor interface (composed of bicolor and mediated contacts), labels, the following pieces of information are reported: the number of atoms contributed by each partner, the number of water molecules sandwiched, and the number of contacts of the three types.
  • Second, a Union-Find algorithm is run on the mediated interfaces, so as to identify the connected components between the previous interfaces.

Ionic interactions

See algorithms in the package Pointwise_interactions.

Programmer's workflow

The programs of Space_filling_model_interface_finder described above are based upon generic C++ classes, so that additional versions can easily be developed for protein or nucleic acids, both at atomic or coarse-grain resolution.

In order to derive such versions, there are two important ingredients, that are the workflow class, and its traits class.

The traits class


This class defines the main types used in the modules of the workflow. It is templated by the classes of the concepts required by these modules. This design makes it possible to use the same workflow within different(biophysical) contexts to make new programs. To use the workflow T_Space_filling_model_interface_finder_workflow , one needs to define:

  • what is a particle (atoms or pseudo-atoms),
  • what are the partners (e.g a binary complex, an IG/Ag complex, etc.),
  • how to annotate the particles,
  • how to build a particle if non-trivial steps are required (e.g., building pseudo-atoms from residues in a protein).
Template Parameters
ParticleTraitsBaseTraits class defining the type of particles (atoms or pseudo-atoms) following the concept ParticleTraits. It is a base for the class SBL::Models::T_Particle_with_system_label_traits that adds a system's label to each particle.
PartnerLabelsTraitsTraits class defining the type of system's labels for the partners following the concept MolecularSystemLabelsTraits.
ParticleAnnotatorFollow the concept ParticleAnnotator.
ParticlesBuilderFunctor building the input particles, as defined in the concept ParticleTraits.

The workflow class