ParticleTraits

Authors: F. Cazals and T. Dreyfus

Introduction

In the SBL, a number of low-level algorithms are based upon combinatorial, geometric and topological representations, so that these algorithms do not require any specific biophysical information. This fact allows developing several programs taking as input the same geometric objects, yet, in different biological contexts.

The iconic example is the calculation of molecules surfaces and volumes: such a calculation requires a set of balls, which may be atoms or pseudo-atoms. For this reason, the SBL proposes two programs, namely $\text{\sblvorlumepdb}$ for atoms, and $\text{\sblvorlumetxt}$ for a collection of balls out of any biomolecular context. Such programs make up an application.

Another example related to the problem of detecting and modeling of interfaces between partners in a complex, using e.g. the program. Again, this problem is geometric in nature, since one essentially seeks pairs of balls belonging to nearby partners. For example, $\text{\sblintervorabw}$ provides such a calculation for proteins; and $\text{\sblintervorigagw}$ uses the same geometric machinery to provide more accurate information for the case where the partners have a complex hierarchical structure (such as that of an antibody, whose binding site involves six loops, namely the Complementarity Determining Regions).

In fact, the very generic nature of prerequisites on objects makes it possible to use very generic algorithms within the SBL.

A particle is an elementary physical object. It is of geometric nature, but is potentially endowed with other properties. To handle these pieces of information, the ParticleTraits package define classes to:

model the geometric properties of particles, (sections Geometric Representation, Atoms and Pseudo-atoms),

decorate particles with biophysical properties (section Particles with Annotations)

assign particles to molecular systems using labels (see section Molecular Labeling)

Using existing models in existing Applications : I/O

Guidelines

From the user standpoint, using programs resorting to models of ParticleTraits has two implications:

(i) the models used by these programs represent different biophysical particle types (e.g. an atom and a pseudo-atom representing a residue). Thus, the output will typically have different attributes.

(ii) the models may refer to the same object, yet, with different attributes. For example, an atom may be accompanied by the SSE it belongs to in one case, but not the other. Thus, the level of detail of pieces of information provided may vary.

To ease things, when an application is instantiated with several models of ParticleTraits, the name of the corresponding programs contains a key-word identifying the type of the particle (see section Example: Running a Program using Particles).

Example: Running a Program using Particles

The following example shows the differences between two programs of an application using two different models of the concept ParticleTraits. Let consider the programs of the application Space_filling_model_surface_volume, that computes the volume and the surface area of an input molecule. The input molecule may be stored in files with different formats, as the PDB file format, or as a simple list of 3D spheres in a plain text file. Depending on the format, the way to load and to represent a particle will not be the same, so that two programs are provided:

$\text{\sblvorlumepdb}$ uses the model SBL::Models::T_Atom_with_flat_info_and_annotations_traits, that defines an atom with "flat" information, an annotated name, an annotated radius and a list of dynamic annotations; it will load a PDB file, build the particles from the loaded atoms, and annotate the particles with default or loaded names and radii (and possibly optional annotations);

sbl-vorlume-pdb.exe -v -c -f demos/data/1vfb.pdb

$\text{\sblvorlumetxt}$ uses the model SBL::Models::T_Geometric_particle_traits that defines an atom as a simple 3D sphere; it will load a plain text file and build the particles from the 3D spheres listed in the input file.

sbl-vorlume-txt.exe -v -c -f demos/data/spheres.txt

The output files of $\text{\sblvorlumepdb}$ will be naturally decorated with the information contained in the input PDB file. For $\text{\sblvorlumetxt}$ , the output files will be minimalist since only geometric information is contained in the input plain text file.

Using existing models to develop novel applications

Geometric Representation

The class SBL::Models::T_Geometric_particle_traits< GeometricKernel , GeometricRepresentation > defines a type of particle that is purely geometric and has no attached biophysical information.

The geometric part of the SBL is based upon the CGAL library: the template parameter GeometricKernel determines the geometric primitives used for representing a particle (number type, point type, etc...), as explained in the documentation of the CGAL library. The second template parameter GeometricRepresentation is the geometric representation of the particle, which may be represented by CGAL objects such as Weighted_point, Point_3, Sphere_3. The default geometric representation used is the Weighted_point type from CGAL type.

Atoms

The SBL provides two main data structures for handling atoms, that are presented just below:

a partially serializable (see section Partial Serialization) data structure with complete information in section ESBTL Molecular Atom as Particle Type ,

a serializable data structure with less information than its counterpart in section SBL Atom as Particle Type.

ESBTL Molecular Atom as Particle Type

The ESBTL provides the hierarchical data structure ESBTL::Molecular_atom to represent an atom in a hierarchical manner–namely the atom belongs a residue which is itself in a chain which itself belongs to a molecular model. The SBL provides the model SBL::Models::T_Atom_with_hierarchical_info_traits< GeometricKernel , SystemItems > for using the class ESBTL::Molecular_atom within the SBL algorithms. The template parameter GeometricKernel is a class defining the number type FT used to represent the coordinates of the atoms, and the type Point_3 used to represent the atoms themselves as geometric entities. It has a default type for defining geometric objects with float coordinates and calculations. The template parameter SystemItems is a class defining the base classes used to represent atoms, residues, chains and models in a molecule (see the ESBTL documentation). It has the default type from the ESBTL library.

Note that this data structure is only partially serializable, see section Partial Serialization.

SBL Atom as Particle Type

Due to the previous remark, in order to serialize an atom, the entire molecule containing it has to be serialized. For this reason, in the SBL, the ESBTL Molecular Atom can only be partially saved in a file, and cannot be loaded from a file. In order to have a completely serializable data structure, the SBL provides a "flat" data structure, in the sense that all the information on the atom is contained in the atom. The SBL provides the model SBL::Models::T_Atom_with_flat_info_traits< GeometricKernel , SystemItems >. The two template parameters are the same ones as explained in section ESBTL Molecular Atom as Particle Type .

Pseudo-atoms

The ESBTL provides a pseudo-atom data structure ESBTL::Coarse_atom to represent residues with a fix number of pseudo-atoms. As for the ESBTL atom data structure, the ESBTL pseudo-atom data structure is not fully savable: the SBL provides a "flat" pseudo-atom data structure SBL::Models::T_Pseudo_atom_per_residue_spec_with_flat_info and a model of ParticleTraits for this pseudo-atom class: SBL::Models::T_Pseudo_atom_per_residue_spec_with_flat_info_traits< GeometricKernel , SystemItems >.

Particles with Annotations

As explained in the user manual of the package ParticleAnnotator, a particle may be decorated with annotations: these annotations may be compulsory or optional, depending on the context.

The class SBL::Models::T_Particle_with_annotations_traits< ParticleTraitsBase , AnnotationsType > inherits from the base traits class ParticleTraitsBase and re-implements the class Particle_type by simply adding an annotations attribute of type AnnotationsType .

Each of the predefined particle traits class without annotation has its own version with annotations, using the class SBL::Models::T_Particle_with_annotations_traits:

SBL::Models::T_Atom_with_hierarchical_info_and_annotations_traits< Annotations , GeometricKernel , SystemItems >

SBL::Models::T_Atom_with_flat_info_and_annotations_traits< Annotations , GeometricKernel , SystemItems >

SBL::Models::T_Pseudo_atom_per_residue_spec_with_flat_info_and_annotations_traits< Annotations , GeometricKernel , SystemItems >

In any case, such classes have fixed annotations inheriting from the template parameter Annotations (if not void) such that:

the annotations type has a name and a radius field; all applications in the SBL using particles require a radius (see Space Filling Model); name and radius are handled by the class SBL::Models::T_Name_and_radius_annotations;

the annotations type has a list of optional annotations loadable from a file; optional annotations are handled by a list of SBL::Models::T_Dynamic_annotator_for_atoms::T_Annotations_with_dynamic .

Note that all the corresponding traits classes define also a Default_annotator type that is the annotator type for the default annotations (the template parameter Annotations is void).

Particles with System's Label

As explained in the user manual of the package MolecularSystemLabelsTraits, when particles are part of a molecular structure, the particles are associated to one of the partner of the structure, or to interfacial water, or even to extra particles. The class SBL::Models::T_Particle_with_system_label_traits< ParticleTraitsBase , PartnerLabelsTraits , MediatorLabelsTraits , ExtraLabelsTraits , IsSerializedLabel > provides a type of particle enriched with a system's label. The template parameters are, in their order of appearance:

the base traits class used to derive the enriched particle type,

the traits class defining the labels to assign particles to partners (see package MolecularSystemLabelsTraits),

the traits class defining the labels to assign particles to mediators (see package MolecularSystemLabelsTraits),

the traits class defining the labels to assign particles to extra partners (see package MolecularSystemLabelsTraits),

a boolean tag to save the system's label when serialazing the particle (default is false).

[Advanced] Suppose that the tag IsSerializedLabel is false. If the particle type is serializable, saved particles may be loaded by another application using particle devoid of labels. For example, the application Space_filling_model_shelling_diagram_surface_encoding requires particle belonging to partners, so as to compute binding patches on these partners. Those patches can then be loaded by a program which does not use the notion of partner. Example such programs can be found in the application Space_filling_model_shelling_diagram_comparison.

Example: Instantiating particle Traits

This example shows the source file of the program $\text{\sblvorlumepdb}$ , and explains how to use different models of ParticleTraits for this application:

This source file is organized as follows:

(i) first, a number definitions occur: the model of ParticleTraits to be used and its particle type, the way to load those particles, and the way they are built.

(ii) second, the program use the Workflow framework for instantiating an Application Traits class and an Application Workflow clas.

(iii) third, the main function creates a Workflow and start it.

Note that it is sufficient to change the models used in (i) for making a new program with a new type of particle. When particles are atoms, one may use the model SBL::Models::T_Atom_with_flat_info_and_annotations_traits as shown:

When particles are simple 3D spheres, one may use the model SBL::Models::T_Geometric_particle_traits as shown:

Developing new models of ParticleTraits concept

The C++ concept ParticleTraits has five requirements:

the Geometric_kernel type: defines a number of geometric primitives for dealing with 3D geometric objects (in particular, the 3D points and the number type of the coordinates of the 3D points),

the Particle_type type: a serializable data structure representing the particle; it can be either a new data structure, or a simple typedef of an existing data structure,

the Get_geometric_representation type: a functor returning the geometric representation of a particle (e.g a 3D point, or a 3D weighted point),

it has to be serializable has mentioned in the Boost Serialization,

it has to be drawable as specified in the package Molecular_viewers.

Example: Defining Custom Particle Traits

This example shows the model SBL::Models::T_Geometric_particle_traits of the concept ParticleTraits representing a particle as a simple 3D geometric object (a weighted point by default):

    template <class GeometricKernel = CGAL::Exact_predicates_inexact_constructions_kernel,
#ifdef CGAL_VERSION_GEQ_4_10
              class GeometricRepresentation = typename GeometricKernel::Weighted_point_3 >
#else
              class GeometricRepresentation = CGAL::Weighted_point<typename GeometricKernel::Point_3, typename GeometricKernel::FT> >
#endif
    class T_Geometric_particle_traits 
    {
    public:
 
      typedef T_Geometric_particle_traits<GeometricKernel, GeometricRepresentation>    Self;
 
      typedef GeometricKernel                                                          Geometric_kernel;
 
      typedef GeometricRepresentation                                                  Particle_type;
 
      typedef SBL::Models::No_particle_annotator                                       Annotator_default;
 
      class Get_geometric_representation
      {
 
      public:
 
        template <class ParticleType>
        inline const GeometricRepresentation& operator()(const ParticleType& A)const
        {       
          return A;
        }
 
      };//end class Get_geometric_representation
 
    };//end class T_Geoemtric_particle_traits

While the three main types discussed in section Developing new models of ParticleTraits concept are defined in this header file, the serialization of the default type (the weighted point) is included from another header file (SBL/IO/Weighted_point_serialize.hpp), and the weighted-points are by default drawable using the package Molecular_viewers.

There is an additional type SBL::Models::T_Geometric_particle_traits::Annotator_default that is not a requirement but that is used for simplifying the code when instantiating an application with several models of ParticleTraits.

Table of Contents