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.
Substructure Search section
Perform substructure searches example
It is a good practice to call the
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
OESubSearch(const OESubSearch &rhs)
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.
The OESubSearch object will store its own copy of the
given query molecule, and the
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.
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() 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
If initialization was completed successfully this method will return
true. An OESubSearch object is considered to be
uninitialized when constructed with the default constructor.
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.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
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.
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
Eliminates all prior match constraints set with the
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
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.
bool Init(const OEQMolBase &)
(Re)initializes an OESubSearch object with a query
molecule (OEQMolBase) reference. The method will
true if initialization completes successfully, and
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
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.
The query molecule of the maximum common substructure search.
This value has to be any combination of atom expressions of the
This value has to be any combination of bond expressions of the
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,
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 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.
The target molecule in which the substructure is identified.
By default all possible subgraphs up to and including the maximum number of matches are returned by these methods. If this parameters is
truethen 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.
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
constraint on the maximum number of matches can be removed by calling
this method with a value of zero.
bool SingleMatch(const OEMolBase &) const
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
Example program molgrep.py