Loading...
Searching...
No Matches
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())
OBQuery * | CompileMoleculeQuery (OBMol *mol, const OBBitVec &mask=OBBitVec())
OBQuery * | CompileSmilesQuery (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.

#include <openbabel/query.h>
using namespace OpenBabel;
OBMol *mol = new OBMol;
// ... read molecule ...
OBQuery *query;
query = CompileMoleculeQuery(mol);
query = CompileSmilesQuery("c1ccccc1CC(=O)O");
OpenBabel::OBMol
Molecule Class.
Definition mol.h:121
OpenBabel::OBQuery
A substructure query.
Definition query.h:198
OpenBabel::CompileSmilesQuery
OBQuery * CompileSmilesQuery(const std::string &smiles, const OBBitVec &mask=OBBitVec())
Definition query.cpp:75
OpenBabel::CompileMoleculeQuery
OBQuery * CompileMoleculeQuery(OBMol *mol, const OBBitVec &mask=OBBitVec())
Definition query.cpp:43
OpenBabel
Global namespace for all Open Babel code.
Definition alias.h:23
query.h
OBQuery, OBQueryAtom & OBQueryBond classes.

# 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;
}
}
OpenBabel::OBIsomorphismMapper::Functor
Functor base class to be used in combination with MapGeneric.
Definition isomorphism.h:149
OpenBabel::OBIsomorphismMapper::Mapping
std::vector< std::pair< unsigned int, unsigned int > > Mapping
Definition isomorphism.h:84
isomorphism.h
OBIsomorphismMapper class for finding isomorphisms.

# 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

typedef OBIsomorphismMapper::Mapping Automorphism

A single automorphic permutation.

Since
  2.3

## Automorphisms

typedef OBIsomorphismMapper::Mappings Automorphisms

A group of automorphic permutations.

Since
  2.3

## Function Documentation

## MapsTo()

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

inline

## FindAutomorphisms() [1/3]

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 )

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 FindAutomorphisms(), FindAutomorphisms(), and OBAlign::SetRefMol().

## FindAutomorphisms() [2/3]

bool 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

  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 CompileSmilesQuery().

## 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