Classes
class	OBIsomorphismMapper
	Abstract class defining interface for isomorphism (i.e. substructure) searches. More...
class	OBSmartsPattern
	SMARTS (SMiles ARbitrary Target Specification) substructure searching. More...
class	OBQueryAtom
	Atom in an OBQuery. More...
class	OBQueryBond
	Bond in an OBQuery. More...
class	OBQuery
	A substructure query. More...
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())
OBQuery *	CompileMoleculeQuery (OBMol *mol, const OBBitVec &mask=OBBitVec())
OBQuery *	CompileSmilesQuery (const std::string &smiles, const OBBitVec &mask=OBBitVec())

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.

 #include <openbabel/query.h>
 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().

 #include <openbabel/isomorphism.h>
 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

OBIsomorphismMapper::Mapping Automorphism

A single automorphic permutation.

Since:: 2.3

OBIsomorphismMapper::Mappings Automorphisms

A group of automorphic permutations.

Since:: 2.3

Function Documentation

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

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:

mol	The molecule for which to find the automorphisms.
aut	The result will be stored here.
symmetry_classes	The graph invariants to use. See OBGraphSym or use the FindAutomorphisms function that computes these for you below.
mask	A bit vector specifying which atoms to consider. An empty mask will consider all atoms. The bits are indexed from 1 (i.e. OBAtom::GetIdx()).
maxMemory	Maximum 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().

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

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

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

Create an OBQuery object from an OBMol object.

Parameters:

mol	The query molecule.
mask	The 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().

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

Create an OBQuery object from a smiles string.

Parameters:

smiles	The query smiles string.
mask	The 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

Substructure Searching

Classes

Typedefs

Functions