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

Buried_surface_area

Authors: F. Cazals and T. Dreyfus

Introduction

BSA. Consider a complex involving two species, $a_i$ and $a_j$, called partner's labels — see the package MolecularSystemLabelsTraits for a description of such labels. Denote ${\cal B}[a_i]$ and ${\cal B}[a_j]$ their associated molecular models. In general, each such model is represented by a collection of balls defining the partner's solvent accessible model. With these notations, the complex involving the two partners is defined by ${\cal B} = {\cal B}[a_i]\cup {\cal B}[a_j]$.

The Buried Surface Area (BSA for short) of the molecular model $\cal B$ is the area of the surface of ${\cal B}[a_i]$ and ${\cal B}[a_j]$ which gets buried within $\cal B$.

More formally, let $\partial{\cal B}[a_i]$ be the boundary of the union of balls in ${\cal B}[a_i]$, and likewise for ${\cal B}[a_j]$. The BSA is defined by the surface area exposed by the individual partners, minus that of the complex:

$BSA({\cal B}) = \marea{\partial{\cal B}[a_i]} + \marea{\partial{\cal B}[a_j]} - \marea{\partial{\cal B}}$.

The BSA can be assigned to the individual partners, which yields an algorithms to compute it. To see how, let $\partial{\cal B}[a_i]\cap\partial{\cal B}$ be the surface of $\cal B$ restricted to the exposed surface of ${\cal B}[a_i]$, that is, prosaically, the contribution of ${\cal B}[a_i]$ to the exposed surface of the complex.

The BSA associated with the partners $a_i$ verifies

$BSA({\cal B}[a_i]) = \marea{\partial{\cal B}[a_i]} - \marea{\partial{\cal B}[a_i]\cap\partial{\cal B}}$,

so that one has

$BSA({\cal B}) = BSA({\cal B}[a_i]) + BSA({\cal B}[b_i])$.

This package. Provides tools to

  • compute the BSA of one partner in a molecular structure, possibly at different scales (the label of the partner may be primitive or hierarchical);
  • possibly serialize the BSA on a per particle basis.

Illustration of BSA computation of a binary complex The molecular complex $\cal B$ is decomposed using two labels $a$ (blue) and $b$ (red). The straight circular arcs are the surfaces of the restrictions ${\cal B}[a]$ and ${\cal B}[b]$, while the dashed circular arcs are the buried surfaces of ${\cal B}[a]$ and ${\cal B}[b]$. The BSA of $\cal B$ is the sum of the BSAs of each restriction.

Algorithms

In order to compute the BSA in the context of hierarchical labels (see the package MolecularSystemLabelsTraits for a description of this hierarchy), we need to extend the formulae in the section Introduction .

Remind that in this context, labels are the nodes of rooted trees. Let $a$ be a hierarchical label such that it is a root of one of these trees, and $P(a)$ the set of primitive labels having $a$ as ancestor in the tree. The formulae in the section Introduction apply for $a$ but not for labels in $P(a)$, since for some couple of labels in $P(a)$, the associated restrictions possibly intersect : this means that we cannot sum the BSA of the restrictions to the labels in $P(a)$ for computing the BSA of $a$.

To overcome this difficulty, we consider only the restrictions to a label that is a root of a tree. Thus, there are two cases for computing the BSA associated to a label $l$:

  • $l$ is a root of a tree and we can apply formulae in section Introduction .
  • $l$ is not a root of a tree: considering $r$ the root of the tree containing $l$, we use the restriction to $r$ for computing the BSA, but we only count the area of the surface of balls having the label $l$;

In this way, the BSA of any label remains additive. This case is illustrated on Fig. fig-bsa-example-IGAg with a IG-Ag complex.

There are two important remarks related to the computation of the BSA for any restriction of a molecular structure:

  • the BSA depends on the mediators: if a partner's particle with a label $l$ is partially buried in an interfacial mediator's particle, the buried portion of this partner's particle counts in the computation of the BSA. However, non-interfacial mediator's particles does not count in the computation. To distinguish these two types of mediator's particles, we just consider the non-interfacial mediator's particles as part of ${\cal B}[l]$.
  • the BSA does not depend on the extras: as for the non-interfacial mediator's particles, the extra particles does not count in the computation of the BSA, and we treat them in the same way.

Illustration of BSA computation of a IGAg complex The immunoglobulin (IG) in red is decomposed onto its heavy (H) and light (L) chains. The antigen (Ag) is in blue. The straight circular arcs represent the exposed surface of the whole complex, and the non straight circular arcs represent the buried surface of each restriction in the whole complex. The dashed circular arcs represent the surface of each restriction that is buried in the whole complex, but exposed in its own partner. The sum of the BSA of the restrictions to H and L is the BSA of the restriction to IG.

Implementation

In the context of a molecular structure, each particle has a system's label identifying which partner, mediator or extra partner it belongs to. This information is mandatory for computing the BSA, but it may happen that in some context, the partners are not clearly identified, so that the particles has no label.

In section Main classes, one can find the two main classes provided by the package Buried_surface_area corresponding to the two possible situations. Then, each of these two main class leads to a module shown in section Modules .

Main classes

The package Buried_surface_area provides two ways for computing the BSA:

With labels. When the partners can be specified using labels, one should use the class SBL::CSB::T_Buried_surface_area_with_labels< ParticleWithSystemLabelTraits , ParticleBSARecord , FT > : it is a functor (1) computing the BSA associated to a partner's label using the algorithm described in section Algorithms , and (2) storing the BSA on a per particle basis, using a type Particle_BSA_record – see below.

The three template parameters read as follows:

  • The first template parameter is a traits class defining a particle with an attached system's label, as defined in the package ParticleTraits.
  • The second template parameter is a class used to record BSA information on a per particle basis. In addition to the BSA, when the particle is an atom, one record the atomid, the resid, the chain id, etc; when the particle is a pseudo-atom, one may want to record the coordinates, radius, etc. Default implementations of these behaviors are provided with the classes SBL::CSB::T_BSA_record_atomic and and SBL::CSB::T_BSA_record_pseudoatom . Nb: the type corresponding to this second template parameter is passed to the BSA algorithm as a type of the traits calss passed to the class SBL::Modules::T_Buried_surface_area_with_labels_module< ModuleTraits > , see below.
  • The third template parameter is the type of the returned BSA (it is set by default to an interval certified to contain the true surface area). See Computing the BSA with partner's labels for an example.

Without labels.

  • when the partners cannot be specified using labels (e.g there is no label), one should use the class SBL::CSB::T_Buried_surface_area_without_label< ParticleTraits , FT > : it is a functor for computing the BSA associated to a given partner. In this version, no partner label is attached to the particles, but the functor takes as argument a predicate checking that a particle is in the partner for which we want the BSA. See Computing the BSA with a predicate for an example.

While the first version takes advantage of the knowledge on the composition of each partner for computing the BSAs of all primitive partners at the construction of the functor, the second version recompute the volume of the input partner each time the functor is called. Furthermore, there is no notion of hierarchy in the second version.

An object of the class SBL::CSB::T_Buried_surface_area_with_labels or SBL::CSB::T_Buried_surface_area_without_label may be constructed on two ways:

  • by providing the alpha-complex of the molecular structure.
  • by providing a range of particles defining the molecular structure (in this case, it is possible to add a constant value (i) to the radius of all particles and (ii) to the squared radius of all particles. For a discussion about these two parameters, see the section ...).

Once the object is constructed, it can be used as a function taking as argument:

In both cases, the functor returns the BSA of the particles in the input partner.

Modules

In addition to these two classes, two modules are available:

The ModuleTraits class must defined the type Particle_BSA_record which is used to store information on a per particle basis.



Examples

Computing the BSA with partner's labels

In this example, atoms of a molecule are loaded from a PDB file, then annotated with default radii and systems' label, and inserted in a $\alpha$-complex data structure. Then, the BSA data structure is created from the $\alpha$-complex and the BSA of each chain is then printed.

#include <SBL/Models/Atom_with_flat_info_and_annotations_traits.hpp>
#include <SBL/Models/Chain_label_traits.hpp>
#include <SBL/Models/Particle_with_system_label_traits.hpp>
#include <SBL/Models/PDB_file_loader.hpp>
#include <SBL/CSB/Buried_surface_area.hpp>
#include <iostream>
#include <SBL/CSB/Buried_surface_area_particle_visitor.hpp>
typedef Alpha_complex::Triangulation Triangulation;
int main(int argc, char *argv[]){
if(argc < 2)
return -1;
//Loads a PDB file.
Molecular_geometry_loader loader;
loader.add_input_file_name(argv[1]);
loader.load(true, std::cout);
//Annotates the loaded atoms (default radii + 1.4 A from SAS model).
Particle_annotator annotator;
annotator.load(true, std::cout);
std::vector<Particle_traits::Particle_type> atoms(loader.get_geometric_model().atoms_begin(),
loader.get_geometric_model().atoms_end());
for(unsigned i = 0; i < atoms.size(); i++)
annotator(atoms[i]);
//Builds the alpha-complex of the loaded atoms.
Triangulation T(atoms.begin(), atoms.end());
//Attribute a label to all particles.
for(Alpha_complex::Finite_vertices_iterator it = A.finite_vertices_begin(); it != A.finite_vertices_end(); it++)
it->get_particle().set_system_label(chain_label_classifier, no_label_classifier, extra_label_classifier);
//Compute BSA
//Iterating over the primitive labels corresponding to the chains
std::cout << SBL::Models::Chain_label_traits::to_string(i) << ": " << bsa(i) << std::endl;
return 0;
}
Derived class from CGAL alpha-complex for filling it with particles.
Definition: Alpha_complex_of_molecular_model.hpp:598
Definition: Buried_surface_area_particle_visitor.hpp:15
Compute the buried surface area of two given partners
Definition: Buried_surface_area.hpp:108
Molecular_structure_traits::Molecular_structure Alpha_complex
Geometric representation of a molecule where particles have a label.
Definition: Buried_surface_area.hpp:126
Model of MolecularSystemLabelTraits for chains.
Definition: Chain_label_traits.hpp:216
Defines a generic serializable atom with annotations (default is name, radius and optional annotation...
Definition: Atom_with_flat_info_and_annotations_traits.hpp:121
static unsigned get_number_of_primitive_labels(void)
Definition: Chain_label_traits.hpp:129
static std::string to_string(Label label)
Return the string representation of the labels.
Definition: Chain_label_traits.hpp:140
Loader for one or more PDB files, even listed in a file. Loader for one or more PDB files,...
Definition: PDB_file_loader.hpp:94
Collector for models of ParticleAnnotator.
Definition: Particle_annotator_collector.hpp:84
bool load(unsigned verbose, std::ostream &out)
Loads the data.
Definition: Particle_annotator_collector.hpp:169
Model of ParticleTraits for defining particles with a system's label.
Definition: Particle_with_system_label_traits.hpp:380
dictionary T
Definition: extract-wales-graph.py:35
Functor returning a pair classifying a particle.
Definition: Extra_label_traits.hpp:118
Traits class defining one extra's label. Traits class defining one extra's label.
Definition: Extra_label_traits.hpp:70
Functor returning a pair classifying a particle.
Definition: No_label_traits.hpp:112
Traits class defining no system's label. Traits class defining no system's label.
Definition: No_label_traits.hpp:70
Functor returning a pair classifying a particle.
Definition: Chain_label_traits.hpp:150

Using the module computing the BSA with partner's labels

This example does the same work as the example of section Computing the BSA with partner's labels, but using the module SBL::CSB::T_Buried_surface_area_with_labels_module.

#include <SBL/Models/Atom_with_flat_info_and_annotations_traits.hpp>
#include <SBL/Models/Chain_label_traits.hpp>
#include <SBL/Models/Particle_with_system_label_traits.hpp>
#include <SBL/Models/PDB_file_loader.hpp>
#include <SBL/CSB/Buried_surface_area.hpp>
#include <iostream>
//Module
#include <SBL/Modules/Buried_surface_area_with_labels_module.hpp>
#include <SBL/CSB/Buried_surface_area_particle_visitor.hpp>
//Module Traits
class Module_traits
{
public:
};
//Module
int main(int argc, char *argv[]){
if(argc < 2)
return -1;
//Loads a PDB file.
Molecular_geometry_loader loader;
loader.add_input_file_name(argv[1]);
loader.load(true, std::cout);
//Annotates the loaded atoms (default radii + 1.4 A from SAS model).
Particle_annotator annotator;
annotator.load(true, std::cout);
std::vector<Particle_traits::Particle_type> atoms(loader.get_geometric_model().atoms_begin(),
loader.get_geometric_model().atoms_end());
for(unsigned i = 0; i < atoms.size(); i++)
annotator(atoms[i]);
//Builds the alpha-complex of the loaded atoms.
Module_traits::Alpha_complex::Triangulation T(atoms.begin(), atoms.end());
//Attribute a label to all particles.
for(Module_traits::Alpha_complex::Finite_vertices_iterator it = A.finite_vertices_begin(); it != A.finite_vertices_end(); it++)
it->get_particle().set_system_label(chain_label_classifier, no_label_classifier, extra_label_classifier);
//initialize and run the BSA module with the labelled alpha-complex
BSA_module bsa_module;
bsa_module.get_alpha_complex() = &A;
bsa_module.run(true, std::cout);
bsa_module.statistics(std::cout);
return 0;
}
Module building the buried surface areas from the alpha-complex of a molecular model....
Definition: Buried_surface_area_with_labels_module.hpp:63
void run(unsigned verbose, std::ostream &out)
Runs the module following the input options.
Definition: Buried_surface_area_with_labels_module.hpp:289
void statistics(std::ostream &out)
Reports high-level statistics on the module.
Definition: Buried_surface_area_with_labels_module.hpp:307
Alpha_complex *& get_alpha_complex(void)
Reference to a pointer over the input -complex.
Definition: Buried_surface_area_with_labels_module.hpp:263

Computing the BSA with a predicate

This example shows how to compute the BSA associated to selected partners in a molecular structure when atoms do not have an associated system's label. Assuming the input molecule is composed of three chains A, B and C, three predicates are defined for checking whether an atom is in a chain or another one. Then, after loading, annotating the particles and inserting them in the $\alpha$-complex, the BSA is computed for each chain using the three predicates.

#include <SBL/Models/Atom_with_flat_info_and_annotations_traits.hpp>
#include <SBL/Models/PDB_file_loader.hpp>
#include <SBL/CSB/Buried_surface_area.hpp>
#include <iostream>
typedef Alpha_complex::Triangulation Triangulation;
//Predicates checking that a particle is in a partner.
struct Is_in_chain_A
{bool operator()(Particle_traits::Particle_type& p)const{return (p.chain_identifier() == 'A');}};
struct Is_in_chain_B
{bool operator()(Particle_traits::Particle_type& p)const{return (p.chain_identifier() == 'B');}};
struct Is_in_chain_C
{bool operator()(Particle_traits::Particle_type& p)const{return (p.chain_identifier() == 'C');}};
int main(int argc, char *argv[]){
if(argc < 2)
return -1;
//Loads a PDB file.
Molecular_geometry_loader loader;
loader.add_input_file_name(argv[1]);
loader.load(true, std::cout);
//Annotates the loaded atoms (default radii + 1.4 A from SAS model).
Particle_annotator annotator;
annotator.load(true, std::cout);
std::vector<Particle_traits::Particle_type> atoms(loader.get_geometric_model().atoms_begin(),
loader.get_geometric_model().atoms_end());
for(unsigned i = 0; i < atoms.size(); i++)
annotator(atoms[i]);
//Builds the alpha-complex of the loaded atoms.
Triangulation T(atoms.begin(), atoms.end());
//Compute BSA
//Computing the BSA of the three partners.
std::cout << "A: " << bsa(Is_in_chain_A()) << std::endl;
std::cout << "B: " << bsa(Is_in_chain_B()) << std::endl;
std::cout << "C: " << bsa(Is_in_chain_C()) << std::endl;
return 0;
}
Compute the buried surface area of two given partners.
Definition: Buried_surface_area.hpp:228
Wrapper representing the atom.
Definition: Atom_with_flat_info_traits.hpp:107
p
Definition: extract-wales-graph.py:74

Using the module computing the BSA with a predicate

This example generalizes the work done by the example of section Computing the BSA with a predicate by using the module SBL::CSB::T_Buried_surface_area_without_label_module. The main difference is that a generic predicate Is_in_partner is defined such that it is possible to iterate over the chains of the input molecule and to set the chain identifier of the current chain as the chain identifier of the predicate.

#include <SBL/Models/Atom_with_flat_info_and_annotations_traits.hpp>
#include <SBL/Models/PDB_file_loader.hpp>
#include <SBL/CSB/Buried_surface_area.hpp>
#include <iostream>
//Module
#include <SBL/Modules/Buried_surface_area_without_label_module.hpp>
//Module Traits
class Module_traits
{
public:
class Is_in_partner
{
public:
char m_chain;
Is_in_partner(char chain = ' ') : m_chain(chain){}
bool operator()(Particle_traits::Particle_type& p)const{return this->m_chain == p.chain_identifier();}
};//end class Is_in_partner
};
//Module
int main(int argc, char *argv[]){
if(argc < 2)
return -1;
//Loads a PDB file.
Molecular_geometry_loader loader;
loader.add_input_file_name(argv[1]);
loader.load(true, std::cout);
//Annotates the loaded atoms (default radii + 1.4 A from SAS model).
Particle_annotator annotator;
annotator.load(true, std::cout);
std::vector<Particle_traits::Particle_type> atoms(loader.get_geometric_model().atoms_begin(),
loader.get_geometric_model().atoms_end());
for(unsigned i = 0; i < atoms.size(); i++)
annotator(atoms[i]);
//Builds the alpha-complex of the loaded atoms.
Module_traits::Alpha_complex::Triangulation T(atoms.begin(), atoms.end());
//for each chain in the input molecule, run the BSA module:
for(Particle_traits::Molecular_system::Model::Chains_iterator it = loader.get_geometric_model().chains_begin();
it != loader.get_geometric_model().chains_end(); it++)
{
BSA_module bsa_module;
bsa_module.get_alpha_complex() = &A;
bsa_module.get_is_in_partner().m_chain = (*it).chain_identifier();
bsa_module.run(true, std::cout);
bsa_module.statistics(std::cout);
}
return 0;
}
Module building the buried surface area of a partner from the alpha-complex of a molecular model....
Definition: Buried_surface_area_without_label_module.hpp:60