Open Babel  3.0
Classes | Typedefs | Functions
Substructure Searching

Classes

class  OBIsomorphismMapper
 
class  OBSmartsPattern
 
class  OBQueryAtom
 
class  OBQueryBond
 
class  OBQuery
 

Typedefs

typedef OBIsomorphismMapper::Mapping Automorphism
 
typedef OBIsomorphismMapper::Mappings Automorphisms
 

Functions

bool MapsTo (const OBIsomorphismMapper::Mapping &map, unsigned int queryIndex, unsigned int &queriedIndex)
 
bool FindAutomorphisms (OBMol *mol, std::vector< OBIsomorphismMapper::Mapping > &aut, const std::vector< unsigned int > &symmetry_classes, const OBBitVec &mask=OBBitVec(), std::size_t maxMemory=3000000)
 
bool FindAutomorphisms (OBMol *mol, std::vector< OBIsomorphismMapper::Mapping > &aut, const OBBitVec &mask=OBBitVec(), std::size_t maxMemory=3000000)
 
void FindAutomorphisms (OBIsomorphismMapper::Functor &functor, OBMol *mol, const std::vector< unsigned int > &symmetry_classes, const OBBitVec &mask=OBBitVec())
 
OBQueryCompileMoleculeQuery (OBMol *mol, const OBBitVec &mask=OBBitVec())
 
OBQueryCompileSmilesQuery (const std::string &smiles, const OBBitVec &mask=OBBitVec())
 

Detailed Description

Substructure Search

Since
version 2.3

Substructure searching is finding a mapping for a query to a target molecule. Such a mapping is also known as a graph isomorphism. A graph isomorphism maps the vertexes (i.e. atoms) from the query to vertexes in the molecule such that two vertexes adjacent in the query are also adjacent in the target molecule. In other words, no bonds are broken and no new bonds are formed.

SMARTS Substructure Search

Smarts is an extension of smiles to create powerful queries. Smarts substructure search has been available in OpenBabel for many years. It is also used for many of OpenBabel's algorithms. Although smarts is only a syntax for queries, the implementation has it's own matching algorithm. For many purposes smarts are the easiest way to do substructure searches. See the OBSmartsPattern documentation for details on how to use smarts.

Queries

Since OpenBabel version 2.3, there are some classes for representing generic queries. The OBQuery, OBQueryAtom and OBQueryBond class define interfaces that can be reimplemented to get custom behavior. The classes also contain some methods to access topological information which are used by the mapping algorithms. The default implementations allow very simple exact substructure searches to be performed but subclassing allows very advanced queries to be used (e.g. smarts).

While it is possible to construct these queries manually, "compilers" are provided to convert a query representation to a OBQuery object. Currently, only two exact substructure search compilers exist. The first is CompileMoleculeQuery which converts an OBMol object to an OBQuery object. The second is CompileSmilesQuery and converts a smiles string to an OBQuery object.

using namespace OpenBabel;
OBMol *mol = new OBMol;
// ... read molecule ...
OBQuery *query;
query = CompileMoleculeQuery(mol);
query = CompileSmilesQuery("c1ccccc1CC(=O)O");

Mapping Isomorphisms

The OBIsomorphismMapper class defined an interface for mapping queries to target molecules. Multiple implementations can be added but they all do the same. The MapFirst, MapUnique and MapAll methods are used for gettings the map(s).

MapFirst

This method returns the first map found. The main reason for getting only one map is improved performance since it is considerably faster than MapUnique and MapAll. However, depending on the use case a single map is all that is needed. For example, to check if a molecule in a database contains a phenyl ring, a single mapping is enough.

MapUnique

MapUnique returns all unique maps. A map is considered unique if there is no other map covering exactly the same atoms in the target molecule. For example, when a phenyl query is performed on a molecule with 2 phenyl rings, MapUnique will return 2 maps. These 2 maps are selected from the 24 found non-duplicate maps (6 atoms to start from * 2 directions (CW/CCW) * 2 rings).

MapAll

MapAll returns all non-duplicate maps. For example, when a phenyl query is performed on a molecule with 2 phenyl rings, MapAll will return 24 maps (6 atoms to start from * 2 directions (CW/CCW) * 2 rings).

MapGeneric

MapGeneric takes a functor object and calls the functor to handle found isomorphisms. This allows for custom mapping results to be obtained by filtering or avoid storing all results. To implement a custom functor, a simple class that inherits OBIsomorphismMapper::Functor and implements the required operator().

using namespace OpenBabel;
class MyCustomFunctor : public OBIsomorphismMapper::Functor
{
private:
// store all mappings in m_data
std::vector<OBIsomorphismMapper::Mapping> &m_data;
public:
MyCustomFunctor(std::vector<OBIsomorphismMapper::Mapping> &data) : m_data(data) {}
bool operator()(OBIsomorphismMapper::Mapping &map)
{
// code to handle found isomorphism...
// examples: - store the mapping
// - filter mappings
// - use the found map in some way
m_data.push_back(map);
// continue mapping
return false;
}
}

Automorphisms

The automorphisms of a graph or molecule are a group of isomorphism mappings of the molecule onto itself (i.e. the query and target are the same). The automorphisms make it easy to take symmetry into account. See FindAutomorphisms for detials.

Typedef Documentation

◆ Automorphism

A single automorphic permutation.

Since
2.3

◆ Automorphisms

A group of automorphic permutations.

Since
2.3

Function Documentation

◆ MapsTo()

bool OpenBabel::MapsTo ( const OBIsomorphismMapper::Mapping map,
unsigned int  queryIndex,
unsigned int &  queriedIndex 
)
inline

◆ FindAutomorphisms() [1/3]

bool OpenBabel::FindAutomorphisms ( OBMol mol,
std::vector< OBIsomorphismMapper::Mapping > &  aut,
const std::vector< unsigned int > &  symmetry_classes,
const OBBitVec mask = OBBitVec(),
std::size_t  maxMemory = 3000000 
)

Find the automorphisms of a molecule by using an OBIsomorphismMapper. This function is a wrapper for FindAutomorphisms with a functor to store all automorphisms.

Parameters
molThe molecule for which to find the automorphisms.
autThe result will be stored here.
symmetry_classesThe graph invariants to use. See OBGraphSym or use the FindAutomorphisms function that computes these for you below.
maskA bit vector specifying which atoms to consider. An empty mask will consider all atoms. The bits are indexed from 1 (i.e. OBAtom::GetIdx()).
maxMemoryMaximum memory limit for aut. The number of automorphisms for certain graphs can be large. The default is 300MB, consider using a functor to process automorphisms when they are found.
Since
version 2.3

Referenced by OpenBabel::FindAutomorphisms(), and OBAlign::SetRefMol().

◆ FindAutomorphisms() [2/3]

bool OpenBabel::FindAutomorphisms ( OBMol mol,
std::vector< OBIsomorphismMapper::Mapping > &  aut,
const OBBitVec mask = OBBitVec(),
std::size_t  maxMemory = 3000000 
)

Find the automorphisms of a molecule by using an OBIsomorphismMapper. This function will first find the graph invariants (i.e. symmetry_classes) using the mask. This function is a wrapper for FindAutomorphisms with a functor to store all automorphisms.

Since
version 2.3

◆ FindAutomorphisms() [3/3]

void FindAutomorphisms ( OBIsomorphismMapper::Functor functor,
OBMol mol,
const std::vector< unsigned int > &  symmetry_classes,
const OBBitVec mask = OBBitVec() 
)

Find the automorphisms of a molecule by using an OBIsomorphismMapper. This is the main implementation for finding automorphisms and uses an OBIsomorphismMapper::Functor to process found isomorphisms. Wrapper functions are provided to find and store all automorphisms but the number of automorphisms can be large for certain graphs making it not feasible to store all automorphisms in memory (RAM).

See also
MapGeneric
Since
version 2.3

◆ CompileMoleculeQuery()

OBQuery * CompileMoleculeQuery ( OBMol mol,
const OBBitVec mask = OBBitVec() 
)

Create an OBQuery object from an OBMol object.

Parameters
molThe query molecule.
maskThe mask specifying the atoms to use. Indexed from 1 (i.e. OBAtom::GetIdx()).
Returns
A pointer to an OBQuery object for the smiles string. This pointer should be deleted.
Since
version 2.3

Referenced by OpenBabel::CompileSmilesQuery().

◆ CompileSmilesQuery()

OBQuery * CompileSmilesQuery ( const std::string &  smiles,
const OBBitVec mask = OBBitVec() 
)

Create an OBQuery object from a smiles string.

Parameters
smilesThe query smiles string.
maskThe mask specifying the atoms to use. Indexed from 1 (i.e. OBAtom::GetIdx()).
Returns
A pointer to an OBQuery object for the smiles string. This pointer should be deleted.
Since
version 2.3