 |
 |
 | OEChem - API Manual | ||||
 |
 |
 |
 |
||||
class 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 classes 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.
OESubSearch()
Default constructor.
OESubSearch(const char *smarts, bool reorder=true)
Construct an instance of an OESubsearch object using a SMARTS
pattern. The SMARTS pattern is passed as the first argument to the
constructor.
The Boolean reorder flag determines the match order of the query
atoms and bonds. If reorder is set to true then the atoms and bonds will be
matched in an arbitrary order. If false, atoms and bonds will be
matched using the input order of the SMARTS pattern.
OESubSearch(const OEQMolBase &qmol, bool reorder=true)
Construct an instance of an OESubSearch object using a query
molecule (OEQMolBase). The query molecule is passed as the first
argument to the constructor. 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 instance being constructed as
uninitialized. The Boolean reorder flag determines the match order of
the query atoms and bonds. If reorder is set to true then the atoms and
bonds will be matched in an arbitrary order. If false, atoms and bonds
will be matched in the order that they appear in the query molecule.
OESubSearch(const OESubSearch &ss)
Copy constructor.
OESubSearch& operator = (const OESubSearch &ss)
Assignment operator. This method makes a copy of an existing
OESubSearch instance.
operator bool() const
This method is used to test for successful initialization of an
OESubSearch object. 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 instance of OESubSearch is considered to be
uninitialized when constructed with the default constructor.
bool AddConstraint(const OEMatchPair<OEAtomBase> &ac) bool AddConstraint(const OEMatchPair<OEBondBase> &bc)
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 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 AddConstraint will return false. Multiple calls to 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.
bool AtomMatch(const OEAtomBase *atm) const bool AtomMatch(const OEQAtomBase *atm) const
The AtomMatch method is the effective combination of sequential calls to AddConstraint followed by SingleMatch. AtomMatch 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. The method can be called using either an OEAtomBase or OEQAtomBase pointer. If a valid subgraph is identified the method will return true.
void ClearConstraints()
The ClearConstraints method eliminates all prior match constraints set with the AddConstraint methods.
unsigned int GetMaxMatches() const
This method returns the maximum number of subgraph isomorphism solutions that the instance of OESubSearch 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, instances of OESubSearch set the maximum number of matches to 1024.
const OEQMolBase &GetPattern()
A read-only reference to the query molecule contained in an instance of OESubSearch can be obtained with this method. Const OEQMolBase methods can be used to interrogate the returned OEQMolBase reference. If the instance of OESubSearch has not been initialized, a reference to an empty molecule will be returned.
bool Init(const char *smarts,bool reorder = true)
This method (re)initializes an OESubSearch instance 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 OEQMolBase &qmol)
This method (re)initializes an OESubSearch instance 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 OEMolBase &mol,unsigned int,unsigned int)
This method (re)initializes an OESubSearch instance using a molecule
(OEMolBase) and expression options used to convert the molecule into a
query molecule (OEQMolBase). The atom and bond expression options
passed as the second and third arguments to the method are defined in
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. Prior state
information is cleared before initialization, and is lost even if the
method fails to initialize properly.
OESystem::OEIterBase<OEMatchBase> *Match(const OEMolBase &mol,
bool uniq = false) const
OESystem::OEIterBase<OEMatchBase> *Match(const OEQMolBase &mol,
bool uniq = false) const
These methods perform subgraph isomorphism determination for instances
of OEMolBase or OEQMolBase. Subgraphs which are isomorphic to the
graph with which an instance of OESubSearch was initialized are
identified. Subgraph matches are returned as a pointer to an
OESystem::OEIterBase<OEMatchBase>, and should be assigned to an
OESystem::OEIter<OEMatchBase> in order to prevent memory leaks.
By default all possible subgraphs up to and including the maximum number
of matches are returned by these methods. If the boolean argument
passed to the methods 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 or bond. Two subgraph matches which
cover the same atoms and bonds, albeit in different orders, will be
called duplicates and the subgraph found later in the search will be
discarded.
bool SingleMatch(const OEMolBase &mol) const bool SingleMatch(const OEQMolBase &mol) const
The SingleMatch methods return 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.
bool SetMaxMatches(unsigned int max)
This method sets the maximum number of subgraphs to be determined by the OESubSearch::Match methods. Once the maximum number of subgraphs have been found the search for additional subgraphs is terminated. By default, instances of OESubSearch are constructed with a maximum number of matches set to 1024. The constraint on the maximum number of matches can be removed by calling this method with a value of zero.
|
|
| OEChem - API Manual | ||||
|
|
|
|
||||