Interaction Perception

OEBio TK provides the following APIs to perceive protein-ligand interactions:

The function that perceives protein-ligand interactions.

The class that stores the parameters that control the interaction perception.

The default geometric parameters have been set based on literature data ([Kumar-2002], [Cavallo-2016], [Bissantz-2010], and [Marcou-2007] ).

Interaction Hint Container

Interactions perceived by the OEPerceiveInteractionHints function are stored in an OEInteractionHintContainer object. The architecture of the OEInteractionHintContainer class is depicted in Schematic representation of interaction hint container.

Schematic representation of interaction hint container

This is the main container that stores typed molecules (OEMolBase), fragments of those molecules (OEInteractionHintFragment) and typed interactions (OEInteractionHint) between the fragments.

The abstract class that enables to type molecules stored in the interaction container. Each molecule added to the container has to have a specific type. Currently, there are two built-in component types available:

Set of atoms of a molecule that is stored in the interaction container. These are the atoms that are contribute to an interaction (OEInteractionHint). Some interactions, such as hydrogen bonds, are between two atoms; other ones define interactions between set of atoms. For example, a stacking interaction is between atoms of two aromatic ring systems.
An iteration is defined between two fragments (OEInteractionHintFragment) stored in the container. An interaction can be either inter (OEInteractionHint::IsInter) or intra (OEInteractionHint::IsIntra) molecular. Each interaction has a specific type that is derived from the OEInteractionHintTypeBase class.

The abstract class that enables to type interactions stored in the interaction container. The table below shows the specific interaction types currently available in OEBio TK. Some interaction classes are also associated with namespaces that enable to subtype the main interaction types. For example, the stacking interaction have two subtypes:

Interaction types currently available in OEBio TK
name corresponding interaction class corresponding interaction type namespace
cation-pi OECationPiInteractionHint OECationPiInteractionHintType
chelator OEChelatorInteractionHint OEChelatorInteractionHintType
clash OEClashInteractionHint None
contact OEContactInteractionHint None
covalent OECovalentInteractionHint None
halogen bond OEHalogenBondInteractionHint OEHalogenBondInteractionHintType
hydrogen bond OEHBondInteractionHint OEHBondInteractionHintType
salt-bridge OESaltBridgeInteractionHint OESaltBridgeInteractionHintType
stacking (T and Pi) OEStackingInteractionHint OEStackingInteractionHintType

Other related APIs:

This function checks whether the interaction container initialized correctly as active site i.e. containing two molecules: one typed as ligand and one typed as protein.
This function iterates over all interaction types (including subtypes) that are perceived by the OEPerceiveInteractionHints function.

Code Examples

Interaction Hint Predicates

The table below list all interaction predicates that are currently available in OEBio TK.

OEBio TK interaction predicates
Access interactions Functor Name
with given interaction type OEHasInteractionHintType
with given atom OEHasInteractionHint
with given residue OEHasResidueInteractionHint
contact OEIsContactInteractionHint
hydrogen bond OEIsHBondInteractionHint
inter-molecular hydrogen bond OEIsIntermolecularHBondInteractionHint
intra-molecular hydrogen bond OEIsIntramolecularHBondInteractionHint
chelator OEIsChelatorInteractionHint
inter-molecular chelator OEIsIntermolecularChelatorInteractionHint
intra-molecular chelator OEIsIntramolecularChelatorInteractionHint
covalent OEIsCovalentInteractionHint
clash OEIsClashInteractionHint
salt-bridge OEIsSaltBridgeInteractionHint
T and Pi-stacking OEIsStackingInteractionHint
cation-Pi OEIsCationPiInteractionHint
halogen bond OEIsHalogenBondInteractionHint
inter-molecular OEIsInterInteractionHint
intra-molecular OEIsIntraInteractionHint
non-ideal hydrogen bond OEIsNonIdealHBondInteractionHint
unpaired ligand OEIsUnpairedLigandInteractionHint
unpaired protein OEIsUnpairedProteinInteractionHint

The following logical operations allow to combine both the built-in and the user defined interaction predicates.

Interaction Composite Functors
Composite Functor Description
OENot logical not
OEOr logical or
OEAnd logical and

Accessing Calculated Interaction Hint Geometries

When interaction hints are perceived using the OEPerceiveInteractionHints function, various geometries (such as distances and angles) are calculated that are checked against the geometric constraints stored in the given OEPerceiveInteractionOptions class.

The following code snippet shows how to access these calculated geometries:

OEHBondInteractionHint hbond(OEHBondInteractionHintType::LigandDonates);
OEHasInteractionHintType hbondpred(hbond);
for (OEIter<const OEInteractionHint> inter = asite.GetInteractions(hbondpred); inter; ++inter)
  const OEInteractionHintTypeBase& itype = inter->GetInteractionType();
  cout << "Calculated geometries for '" << itype.GetName() << "' interaction type:" << endl;
  for (OEIter<const string> gname = inter->GetCalculatedGeometries(); gname; ++gname)
    cout << *gname << ":\t" << inter->GetCalculatedGeometry(*gname) << endl;

For the OEHBondInteractionHintType::LigandDonates hydrogen bond interaction type, three geometries are calculated:

The “distance” values are always given in Angstroms and the “angle” values are always given in radians. The output of the code snippet above might look like this:

Calculated geometries for 'bio:active-site:hbond:ligand2protein' interaction type:
bio:interaction:distance       : 2.722
bio:intaraction:acceptor-angle : 0.155
bio:interaction:donor-angle    : 0.241

For different interactions, different geometries are calculated. The following snippet shows how to access the names of the geometries that are available for a given interaction type using the OEGetCalculatedInteractionGeometries function:

OEHBondInteractionHint hbondacc(OEHBondInteractionHintType::LigandAccepts);
cout << "Calculated geometries for '" << hbondacc.GetName() << "' interaction type:" << endl;
for (OEIter<const string> gi = OEGetCalculatedInteractionGeometries(hbondacc); gi; ++gi)
  cout << *gi << endl;

All interaction geometry names start with the bio:interaction: prefix. However, both the OEInteractionHint::HasCalculatedGeometry and OEInteractionHint::GetCalculatedGeometry methods accept names with or without the bio:interaction: prefix.

The following code snippet shows how to access the calculated geometries directly:

if (inter->HasCalculatedGeometry("distance"))
  const auto distance = inter->GetCalculatedGeometry("distance");
  cout << "distance: " << distance << " Angstrom(s)" << endl;
if (inter->HasCalculatedGeometry("acceptor-angle"))
  const auto angle = inter->GetCalculatedGeometry("acceptor-angle") * OEMath::Rad2Deg;
  cout << "acceptor angle: " << angle << " degree(s)" << endl;

The output of the code snippet above might look like this:

distance: 2.722  Angstrom(s)
acceptor angle: 8.863 degree(s)


It is a good practice to call OEInteractionHint::HasCalculatedGeometry prior to invoking the OEInteractionHint::GetCalculatedGeometry method to check whether the interaction hint has a geometry with a given name.

Currently, the following names are used for the interaction geometries:

  • bio:interaction:distance
  • bio:interaction:angle
  • bio:interaction:acceptor-angle
  • bio:interaction:donor-angle

For most interactions (except the unpaired ones), the calculated distance is available by using the bio:interaction:distance name. None of the unpaired interactions have any calculated geometries since they only “suggest” how they could contribute to the binding but are not actually formed in the complex.

A calculated geometry, such as a distance, can have different meanings based on the interaction type. For example, in a hydrogen bond interaction it means the distance between the acceptor and donor heavy atoms. For a pi-staking interaction, it means the distance between the center of the two ring systems. The following table shows the correspondence between the calculated geometries and the geometric constraints.

Set method Interaction type Associated geometry name
SetMaxHBondDistance hbond bio:interaction:distance
SetMaxChargeAidedHBondDistance hbond (charged) bio:interaction:distance
SetMaxNonIdealHBondDistance non-ideal hbond bio:interaction:distance
SetMaxAcceptorAngle hbond bio:interaction:acceptor-angle
SetMaxDonorAngle hbond bio:interaction:donor-angle
SetMaxNonIdealAcceptorAngle non-ideal hbond bio:interaction:acceptor-angle
SetMaxNonIdealDonorAngle non-ideal hbond bio:interaction:donor-angle
SetMaxMetalBondDistance chelator bio:interaction:distance
SetMaxSaltBridgeDistance salt bridge bio:interaction:distance
SetMaxCationPiDistance cation-Pi bio:interaction:distance
SetMaxCationPiAngle cation-Pi bio:interaction:angle
SetMaxPiStackDistance Pi-stacking bio:interaction:distance
SetMaxPiStackAngle Pi-stacking bio:interaction:angle
SetMaxTStackDistance T-stacking bio:interaction:distance
SetMaxTStackAngle T-stacking bio:interaction:angle
SetMaxHalogenBondDistance halogen bond bio:interaction:distance
SetMaxHalogenAngle halogen bond bio:interaction:angle