OESubSearch

class OESubSearch

This class represents OESubSearch.

The OESubSearch class performs substructure searches, also known as subgraph isomorphism determination, on molecular graphs. In a molecular graph, atoms are considered nodes and bonds are edges. The OESubSearch class is capable of performing both colored and uncolored graph comparison. The ‘color’ properties of a query graph are stored as expression trees associated with atoms and bonds of a query molecule.

See also

Code Example

Hint

It is a good practice to call the OEPrepareSearch function before calling any of the following methods:

If there is any atom or bond property that is not perceived but it is necessary to successfully execute the substructure search, then the above methods throw a warning. These warnings can be suppressed by calling the OEPrepareSearch function.

Constructors

OESubSearch()

Default constructor.

OESubSearch(const OESubSearch &rhs)

Copy constructor.

OESubSearch(const OEQMolBase &qmol)

Constructs an OESubSearch object using a query molecule (OEQMolBase). Query molecules must have atom and bond expressions (see OEQMolBase::BuildExpressions) built for the entire molecule before being passed to this constructor. Failure to do so will result in the OESubSearch object being constructed as uninitialized.

Note

The OESubSearch object will store its own copy of the given query molecule, and the OESubSearch::Match method will return matches between copied query and the target.

OESubSearch(const OEMolBase &mol, unsigned int aexpr, unsigned int bexpr)

Constructs an OESubSearch object using a molecule and expression options. The atom and bond expression options passed as the second and third arguments to the method are defined in the OEExprOpts namespace. The expression options are used to convert the atom and bond data into expression trees which are used during the subgraph search.

OESubSearch(const char *smarts, bool allowReorderAtoms=true)

Constructs an OESubSearch object using a SMARTS pattern that is passed as the first argument to the constructor. The second argument of the method determines the traversal order used in subgraph isomorphism detection. This argument is currently not used, therefore the traversal order always reflects the atom and bond ordering of the passed SMARTS pattern.

operator=

OESubSearch &operator=(const OESubSearch &rhs)

Assignment operator that copies the data of the ‘rhs’ OESubSearch object into the right-hand side OESubSearch object.

operator bool

operator bool() const

Tests whether initialization of an OESubSearch object is successful . If initialization was attempted with an invalid SMARTS pattern or query molecule then this method will return false. If initialization was completed successfully this method will return true. An OESubSearch object is considered to be uninitialized when constructed with the default constructor.

AddConstraint

bool AddConstraint(const OEMatchPair<OEAtomBase> &)
bool AddConstraint(const OEMatchPair<OEBondBase> &)

The search space of a subgraph isomorphism determination can be restricted by constraining pairs of nodes or edges (atoms or bonds) to be mapped onto one another in all valid subgraph solutions. Failure to satisfy atom or bond pairwise constraints will prevent any subgraph solutions from being identified by any of the match methods in OESubSearch. Both OESubSearch::AddConstraint methods return true if a constraint is added successfully. If the pattern atom or bond in the OEMatchPair does not exist as part of the query molecule created in the initialization of the OESubSearch object then OESubSearch::AddConstraint will return false. Multiple calls OESubSearch::AddConstraint using the same pattern atom or bond will cause previously stored constraints to be overwritten as constraints are mutually exclusive. It is impossible to satisfy multiple simultaneous constraints for a single pattern atom or bond, hence the exclusivity.

AtomMatch

bool AtomMatch(const OEAtomBase *) const

Searches for a single valid subgraph isomorphism starting with the passed target atom mapped to the first pattern atom with which the OESubSearch was initialized. If a valid subgraph is identified the method will return true. This method is the effective combination of sequential calls to OESubSearch::AddConstraint followed by OESubSearch::SingleMatch.

ClearConstraints

void ClearConstraints()

Eliminates all prior match constraints set with the OESubSearch::AddConstraint method.

GetMaxMatches

unsigned int GetMaxMatches() const

Returns the maximum number of subgraph isomorphism solutions that the OESubSearch object will identify before terminating the search. A value of zero indicates that no arbitrary limit has been set on the total number of subgraph isomorphism solutions to be identified. By default, the maximum number of matches is set to 1024.

See also

GetPattern

const OEQMolBase &GetPattern() const

Returns the read-only reference to the query molecule contained in an OESubSearch object. Const OEQMolBase methods can be used to interrogate the returned OEQMolBase reference. If the OESubSearch object has not been initialized, a reference to an empty molecule will be returned.

Init

bool Init(const OEQMolBase &)

(Re)initializes an OESubSearch object with a query molecule (OEQMolBase) reference. The method will return true if initialization completes successfully, and false upon failure. Prior state information is cleared before initialization, and is lost even if the method fails to initialize properly.

bool Init(const char *smarts, bool allowReorderAtoms=false)

(Re)initializes an OESubSearch object with a SMARTS pattern, which is parsed to create a query molecule available for substructure search. The method will return true if initialization completes successfully, and false upon failure. Prior state information is cleared before initialization, and is lost even if the method fails to initialize properly. The second argument of the method determines the traversal order used in subgraph isomorphism detection. This argument is currently not used, therefore the traversal order always reflects the atom and bond ordering of the passed SMARTS pattern.

bool Init(const OEMolBase &mol, unsigned int atomexpr, unsigned int bondexpr)

(Re)initializes an OESubSearch object using a molecule and expression options that are used to convert the given molecule into a OEQMolBase query object.

mol

The query molecule of the maximum common substructure search.

atomexpr

This value has to be any combination of atom expressions of the OEExprOpts namespace.

bondexpr

This value has to be any combination of bond expressions of the OEExprOpts namespace.

Expression options are used to convert the atom and bond data into expression trees which are used during the substructure search to map atoms and bonds. The method will return true if initialization completes successfully, and false upon failure.

Note

Prior state information is cleared before initialization, and is lost even if the method fails to initialize properly.

See also

Match

OESystem::OEIterBase<OEMatchBase> *Match(const OEMolBase &mol,
                                         bool uniquematch=false) const

Performs search in order to identify subgraphs of OEMolBase which are isomorphic to the graph with which an OESubSearch object was initialized. It returns an iterator pointer (OEIterBase) over graph matches (OEMatchBase), and should be assigned to an OEIter < OEMatchBase > in order to prevent memory leaks.

mol

The target molecule in which the substructure is identified.

uniquematch

By default all possible subgraphs up to and including the maximum number of matches are returned by these methods. If this parameters is true then only the unique matches will be included in the iterator over the matches. A match or subgraph is considered unique if it differs from all other subgraphs found previously by at least one atom. Two subgraph matches which cover the same atoms, albeit in different orders, will be called duplicates and the subgraph found later in the search will be discarded.

SetMaxMatches

bool SetMaxMatches(unsigned int m)

Sets the maximum number of subgraphs to be determined by the OESubSearch::Match method. Once the maximum number of subgraphs have been found the search for additional subgraphs is terminated. By default, maximum number of matches is set to 1024. The constraint on the maximum number of matches can be removed by calling this method with a value of zero.

See also

SingleMatch

bool SingleMatch(const OEMolBase &) const

Returns true, if a single subgraph isomorphism is detected in the molecule passed as the function argument. If no subgraph isomorphism is detected the method will return false.

See also